企业官网建设流程全解析

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 入口和 Key，Airweave 里所有需要调模型的地方（embedding、语义理解）都指向它，省得你在多个供应商之间来回切。

第一步，拿到你的 Key。打开 TaoToken 控制台，进入 API Keys 页面创建一个新 Key，复制保存。地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。这个 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_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。选一个支持 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": "postgresql+asyncpg://airweave:airweave@localhost: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_KEY=sk-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 以上算有效命中。

想更直观地看命中质量，可以写个小脚本批量测几条 query：

import httpx BASE = "http://localhost:8000" HEADERS = {"Authorization": "Bearer aw-你的Airweave密钥"} COLLECTION = "你的集合UUID" queries = [ "模型通道怎么配", "向量库连接失败怎么办", "如何创建 API 密钥", ] with httpx.Client(base_url=BASE, headers=HEADERS, timeout=30) 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_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。它和 Airweave 的搜索接口配合，代理就能一边做语义检索、一边调模型生成。

接入文档里有完整的接口说明和参数定义，遇到字段不清楚的直接查： https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。控制台里可以随时查看 Key 用量和调用记录： https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。

实测下来，Airweave 加 TaoToken 这套组合最省心的地方在于：模型通道统一了，Airweave 的 embedding 和代理的生成走同一个入口，Key 管理、额度、切换模型都在一处。你只需要维护一份配置，多环境复制时改环境变量就行。把第 4 节的命中测试脚本存下来，每次改完配置跑一遍，几分钟就能确认整条链路是否健康。