1. Airweave 是什么为什么 AI 代理需要它Airweave 是一个把各类应用、生产力工具、数据库和文档存储统一变成「可语义搜索知识库」的平台。它做的事情可以这样理解你平时用的 Notion、Confluence、Asana、各类数据库里散落着大量内容AI 代理想用这些内容回答问题就得一个个对接、一个个写检索逻辑。Airweave 把这些数据源接进来转成向量化的知识图谱再通过一套标准接口暴露出去代理只需要调一个搜索接口就能跨应用拿到语义相关的结果。它适合谁如果你正在做 AI 代理、RAG 应用、企业知识助手或者需要让模型在多个业务系统之间做语义检索Airweave 就是那个「中间层」。它后端基于 Python FastAPI用 PostgreSQL 存元数据、Qdrant 存向量认证走 Auth0 JWT 加 API 密钥回退任务调度用 Redis 加 Temporal整体是 Docker 容器化部署。前端是 React/TypeScript。但真正落地时很多开发者卡在同一个地方Airweave 本身要调用大模型做 embedding 和语义理解而模型通道的配置、密钥管理、多环境切换很琐碎。这篇就聚焦一件事——用 TaoToken 作为统一的模型 Key/API 通道把 Airweave 的 settings.json 和 config.toml 配好再跑通 REST API 的语义搜索命中测试。全程可复制小白也能跟着做。2. 前置准备TaoToken 统一 Key 与 Airweave 环境在动 Airweave 之前先把模型通道准备好。TaoToken 的作用是给你一个统一的 API 入口和 KeyAirweave 里所有需要调模型的地方embedding、语义理解都指向它省得你在多个供应商之间来回切。第一步拿到你的 Key。打开 TaoToken 控制台进入 API Keys 页面创建一个新 Key复制保存。地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。这个 Key 后面会写进 Airweave 的环境变量和配置文件。第二步确认 Airweave 的运行环境。官方要求 Docker 和 Docker Compose、Python 3.11、Node.js 20、PostgreSQL。开发环境这样起git clone https://github.com/airweave-ai/airweave.git cd airweave pip install pre-commit pre-commit install cp .env.example .env ./start.sh.env里要填的关键项包括数据库连接、Qdrant 地址、Auth0 配置以及模型通道。模型通道这块我们把 base_url 指向 TaoToken 的 API 地址 https://taotoken.net/api Key 用刚才创建的那个。这样 Airweave 在生成 embedding 和做语义处理时走的就是统一通道。注意TaoToken 的 API 地址不带任何多余参数直接写 https://taotoken.net/api 即可Key 放在请求头里。如果你还没决定用哪个模型做 embedding可以先到模型对话页面确认一下可用模型和调用方式 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。选一个支持 embedding 的模型记下模型名下一步要写进配置。3. 可复制配置settings.json 与 config.toml 骨架Airweave 的配置分两块一块是应用级的环境与模型通道settings.json 风格一块是代理/工具侧的接入配置config.toml 风格。下面给出可直接改用的骨架。先看 settings.json放在项目配置目录下重点是模型通道和向量库{ model_provider: { base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, embedding_model: 你的embedding模型名, chat_model: 你的对话模型名, timeout: 60 }, vector_store: { type: qdrant, url: http://localhost:6333, api_key: , collection_prefix: airweave }, database: { url: postgresqlasyncpg://airweave:airweavelocalhost:5432/airweave }, auth: { mode: api_key_fallback, auth0_domain: your-tenant.auth0.com, auth0_audience: https://your-tenant.auth0.com/api/v2/ }, sync: { scheduler: temporal, redis_url: redis://localhost:6379/0 } }再看 config.toml这是给代理或 CLI 工具读取的接入配置把 Airweave 的搜索接口和 TaoToken 通道都写进去[provider] name taotoken base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 embedding_model 你的embedding模型名 [airweave] base_url http://localhost:8000 api_key aw-你的Airweave密钥 default_collection default [search] top_k 8 score_threshold 0.35 mode semantic [logging] level info两个文件里的 Key 建议用环境变量注入不要硬编码进仓库。比如在.env里写TAOTOKEN_API_KEYsk-xxx配置里用${TAOTOKEN_API_KEY}引用。这样多环境切换时只改环境变量配置文件不动。配置写完后重启服务docker compose down docker compose up -d docker compose logs -f api日志里如果看到模型通道初始化成功、Qdrant 连接正常说明配置生效了。4. 验证请求REST API 语义搜索命中测试配置对不对跑一次真实搜索就知道。Airweave 暴露了标准的 REST API搜索集合内容的接口是/collections/search。下面用 curl 做连通性和命中测试。先验证服务活着curl -s http://localhost:8000/health返回{status:ok}就说明 API 起来了。接着创建或确认一个集合然后执行语义搜索curl -s -X GET http://localhost:8000/collections/search \ -H Authorization: Bearer aw-你的Airweave密钥 \ -H Content-Type: application/json \ -G \ --data-urlencode query如何配置模型通道 \ --data-urlencode collection_id你的集合UUID如果返回里包含results数组且每条结果有score、payload、content字段说明语义搜索链路通了。score越高表示语义越接近一般 0.35 以上算有效命中。想更直观地看命中质量可以写个小脚本批量测几条 queryimport httpx BASE http://localhost:8000 HEADERS {Authorization: Bearer aw-你的Airweave密钥} COLLECTION 你的集合UUID queries [ 模型通道怎么配, 向量库连接失败怎么办, 如何创建 API 密钥, ] with httpx.Client(base_urlBASE, headersHEADERS, timeout30) as client: for q in queries: resp client.get( /collections/search, params{query: q, collection_id: COLLECTION}, ) data resp.json() top data.get(results, [])[:1] if top: print(f[{q}] 命中: {top[0][score]:.3f} - {top[0][payload].get(title, N/A)}) else: print(f[{q}] 无命中)跑出来如果每条 query 都能命中相关文档且分数合理说明 Airweave 的语义搜索和 TaoToken 的模型通道配合正常。这一步是整个接入的核心验证过了这关后面接代理就顺了。5. 本篇常见错排查接入过程中最容易踩的坑集中在几个地方逐个说。报错一模型通道 401 或 403。多半是 Key 写错或没带对请求头。检查 settings.json 里的api_key是否和 TaoToken 控制台里的一致base_url 是否是 https://taotoken.net/api 。如果用了环境变量确认.env已加载容器重启过。报错二Qdrant 连接超时。看vector_store.url是否指向容器内可达的地址。本地开发用http://localhost:6333容器内互访要用服务名比如http://qdrant:6333。端口映射也要确认。报错三搜索返回空结果。先确认集合里真的有数据且数据已经完成 embedding。Airweave 的数据同步是异步的刚接入的数据源可能要等一轮同步。可以查同步任务状态或者手动触发一次同步再搜。报错四embedding 维度不匹配。如果你中途换了 embedding 模型向量维度变了旧数据就搜不出来。这种情况要么重建集合要么保持模型一致。换模型前先确认新模型的维度再决定是否重新灌数据。报错五Auth0 校验失败。如果开了 Auth0 JWT 校验但本地测试用的是 API 密钥确认auth.mode设成了api_key_fallback否则请求会被 JWT 中间件拦掉。排查时养成看日志的习惯docker compose logs -f api基本能定位到具体是哪一层出的问题。模型通道的问题看请求日志里的状态码向量库的问题看连接异常认证的问题看 401/403 来源。6. 下一步把 Airweave 接进你的代理工作流搜索接口跑通之后接下来就是把它接进实际的代理或编码工作流。如果你主要做长期编码、Agent 任务建议用 Coding Plan 来统一管理模型调用和额度地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它和 Airweave 的搜索接口配合代理就能一边做语义检索、一边调模型生成。接入文档里有完整的接口说明和参数定义遇到字段不清楚的直接查 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。控制台里可以随时查看 Key 用量和调用记录 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。实测下来Airweave 加 TaoToken 这套组合最省心的地方在于模型通道统一了Airweave 的 embedding 和代理的生成走同一个入口Key 管理、额度、切换模型都在一处。你只需要维护一份配置多环境复制时改环境变量就行。把第 4 节的命中测试脚本存下来每次改完配置跑一遍几分钟就能确认整条链路是否健康。
