QAnything 本地部署：用 Docker 配 TaoToken 统一 API 通道的完整安装方法

1. QAnything 本地部署为什么值得折腾以及它到底解决什么问题QAnything 是网易有道开源的一套本地知识库问答系统全称 Question and Answer based on Anything核心能力是把你手头的 PDF、Word、PPT、Excel、Markdown、TXT、图片、CSV、网页链接等文件直接丢进去就能基于这些内容做问答。它适合谁适合手里有一堆内部文档、产品手册、技术资料又不想把数据传到第三方云服务的团队和个人。它最大的特点是支持全程断网安装使用数据不出本地同时内置了两阶段检索embedding 召回 rerank 重排数据量越大检索效果越稳这一点比单纯用向量检索要靠谱得多。但真正动手部署过的人会碰到一个很现实的问题QAnything 默认要拉一堆模型服务LLM、embedding、rerank 各占一块如果你还想接外部大模型 APIKey 就会散落在好几个配置文件里。今天改 LLM 的 Key明天换 embedding 的地址配置一多就容易乱。这篇就聚焦 Docker 本地部署场景用 TaoToken 把多模型 API Key 收敛成一条统一通道给出可复制的 docker-compose 与 config 骨架最后验证容器启动和问答连通性。2. 部署前先把 TaoToken 这条统一通道准备好QAnything 从 v1.2.0 开始支持自定义大模型包括 OpenAI 兼容接口。这意味着只要你的 API 网关是 OpenAI 格式就能直接接进去。TaoToken 提供的正是这样一条 OpenAI 兼容通道把不同模型的调用统一到一个 Base URL 和一把 Key 上QAnything 里那些分散的 LLM 配置就能合并。你需要先拿到两样东西API Key 和 Base URL。Key 在控制台的 API Keys 页面创建地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 创建后复制保存后面填进配置文件。Base URL 统一用 https://taotoken.net/api 注意这个地址后面不加任何路径后缀QAnything 会自己在后面拼 /v1/chat/completions 这类端点。如果你只是想先验证模型通不通可以到模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 直接发一条消息试试确认 Key 有效再往下走。长期跑编码或 Agent 类任务的话可以了解下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 按套餐走比单次调用更划算。接入细节和参数说明都在接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里遇到字段对不上时优先查这里。注意TaoToken 是合规的 API 聚合通道配置时只填 Base URL 和 Key不要在任何配置文件里写额外的网络代理参数QAnything 本身也不需要这些。3. 可复制的 docker-compose 与 config 骨架先把项目拉下来。QAnything 的仓库在 GitHub用 git-lfs 确保大文件能正常拉取git clone https://github.com/netease-youdao/QAnything.git cd QAnything git lfs install git lfs pull进入项目根目录后你会看到docker-compose-linux.yamlLinux和docker-compose-windows.yamlWindows WSL两个编排文件。我们以 Linux 为例核心是改两处编排文件里的环境变量以及 QAnything 自己的模型配置文件。先看 docker-compose 里跟 LLM 相关的片段通常长这样你需要把 OpenAI 兼容的地址和 Key 注入进去services: qanything_local: image: freeren/qanything:v1.2.1 container_name: qanything_local environment: - LLM_API_BASEhttps://taotoken.net/api - LLM_API_KEYsk-你的TaoToken密钥 - LLM_MODEL_NAMEgpt-4o-mini - EMBEDDING_API_BASEhttps://taotoken.net/api - EMBEDDING_API_KEYsk-你的TaoToken密钥 - RERANK_API_BASEhttps://taotoken.net/api - RERANK_API_KEYsk-你的TaoToken密钥 volumes: - ./QAnything:/workspace/QAnything - ./models:/workspace/models ports: - 8777:8777 deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu]这里的关键点是把 LLM、embedding、rerank 三处的 Base URL 全部指向https://taotoken.net/apiKey 也统一成同一把。这样你以后换模型、换 Key只改这一处不用满项目找配置。接着是 QAnything 内部的模型配置文件一般在QAnything/configs/model_config.yaml或类似路径。找到 LLM 那段改成 OpenAI 兼容模式llm: mode: openai_api openai_api: base_url: https://taotoken.net/api api_key: sk-你的TaoToken密钥 model: gpt-4o-mini temperature: 0.3 max_tokens: 2048 embedding: mode: openai_api openai_api: base_url: https://taotoken.net/api api_key: sk-你的TaoToken密钥 model: text-embedding-3-small rerank: mode: openai_api openai_api: base_url: https://taotoken.net/api api_key: sk-你的TaoToken密钥 model: rerank-english-v3.0参数对照可以看这张表方便你按需替换配置项作用建议值base_urlAPI 入口https://taotoken.net/apiapi_key鉴权密钥控制台创建的 Keymodel调用的模型名按套餐支持的模型填temperature生成随机性问答场景 0.2–0.4max_tokens单次输出上限2048 起步提示embedding 和 rerank 的模型名要跟你实际开通的模型对齐填错会报 404 或 model not found排查时先看日志里的请求体。4. 启动容器并验证问答连通性配置改完启动脚本一行搞定。QAnything 提供了run.sh默认在 0 号 GPU 上启动bash run.sh如果你想指定单卡或者你的卡是 24GB 以上、Compute Capability 8.6 以上可以用对应的启动参数具体看bash ./run.sh -h的输出。启动过程会拉镜像、起 Milvus、MySQL、MinIO 这些依赖服务第一次会比较慢耐心等日志刷完。启动成功后前端地址是http://你的主机IP:8777/qanything/API 地址是http://你的主机IP:8777/api/。先别急着传文件做一次最小连通性验证确认 TaoToken 通道是通的curl -X POST http://localhost:8777/api/local_doc_qa/new_knowledge_base \ -H Content-Type: application/json \ -d {user_id: test_user, kb_name: demo_kb}返回里如果带上了kb_id说明后端服务正常。接着往知识库里传一个测试文件再发一条问答请求curl -X POST http://localhost:8777/api/local_doc_qa/upload_files \ -F files./test.pdf \ -F user_idtest_user \ -F kb_id你的kb_id curl -X POST http://localhost:8777/api/local_doc_qa/local_doc_chat \ -H Content-Type: application/json \ -d {user_id: test_user, kb_id: 你的kb_id, question: 这份文档讲了什么}如果返回的 answer 字段有内容且不是报错信息说明 LLM 通道打通了。实测下来第一次问答会稍慢因为要等 embedding 和 rerank 走完后面就快了。5. 本篇常见错误排查部署过程中最容易卡在几个地方我按出现频率排一下。第一个是模型下载失败。QAnything 默认会从 HuggingFace 拉模型网络不稳就会断。解决办法是手动下载模型放到models/目录或者改用 OpenAI API 模式让 embedding 和 rerank 也走 TaoToken 通道本地就不需要下大模型了。第二个是端口冲突。8777 被占用时容器起不来用docker ps和lsof -i:8777查一下改 compose 里的端口映射即可。第三个是 GPU 显存不足。最低要求是 4GB 显存走 OpenAI API 模式推荐 3090 级别。如果显存不够把 LLM 切到 API 模式本地只跑 embedding 和 rerank能省不少显存。第四个是 Key 或 Base URL 填错导致的 401/404。检查三点Base URL 是不是https://taotoken.net/api且没多加/v1Key 有没有多余空格模型名是不是当前套餐支持的。日志在QAnything/logs/debug_logs/下llm_server_entrypoint.log和sanic_api.log最有用。第五个是容器间网络不通。QAnything 内部服务通过容器名互相访问如果你改了 compose 的服务名记得同步改配置里的地址。关闭服务用bash close.sh别直接docker rm否则数据卷可能残留。6. 后续怎么把这套配置用顺整套跑通之后你会发现最大的收益是配置收敛。以前 LLM、embedding、rerank 三套 Key 三套地址现在全指向 TaoToken 一条通道换模型只改 model 字段换 Key 只改一处。如果你要长期跑知识库问答或者接 Agent建议把 Key 管理放到控制台统一做地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 需要新 Key 时在 API Keys 页面创建 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。接入过程中如果碰到字段对不上、报错看不懂优先翻接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面把 OpenAI 兼容格式的请求体和返回都列清楚了。想先确认某个模型能不能用直接去模型对话页面发一条最快 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。