一 API 通道的完整安裝方法)
1. QAnything 本地部署為什么值得折騰以及它到底解決什么問題QAnything 是網(wǎng)易有道開源的一套本地知識庫問答系統(tǒng)全稱 Question and Answer based on Anything核心能力是把你手頭的 PDF、Word、PPT、Excel、Markdown、TXT、圖片、CSV、網(wǎng)頁鏈接等文件直接丟進去就能基于這些內(nèi)容做問答。它適合誰適合手里有一堆內(nèi)部文檔、產(chǎn)品手冊、技術(shù)資料又不想把數(shù)據(jù)傳到第三方云服務(wù)的團隊和個人。它最大的特點是支持全程斷網(wǎng)安裝使用數(shù)據(jù)不出本地同時內(nèi)置了兩階段檢索embedding 召回 rerank 重排數(shù)據(jù)量越大檢索效果越穩(wěn)這一點比單純用向量檢索要靠譜得多。但真正動手部署過的人會碰到一個很現(xiàn)實的問題QAnything 默認要拉一堆模型服務(wù)LLM、embedding、rerank 各占一塊如果你還想接外部大模型 APIKey 就會散落在好幾個配置文件里。今天改 LLM 的 Key明天換 embedding 的地址配置一多就容易亂。這篇就聚焦 Docker 本地部署場景用 TaoToken 把多模型 API Key 收斂成一條統(tǒng)一通道給出可復(fù)制的 docker-compose 與 config 骨架最后驗證容器啟動和問答連通性。2. 部署前先把 TaoToken 這條統(tǒng)一通道準(zhǔn)備好QAnything 從 v1.2.0 開始支持自定義大模型包括 OpenAI 兼容接口。這意味著只要你的 API 網(wǎng)關(guān)是 OpenAI 格式就能直接接進去。TaoToken 提供的正是這樣一條 OpenAI 兼容通道把不同模型的調(diào)用統(tǒng)一到一個 Base URL 和一把 Key 上QAnything 里那些分散的 LLM 配置就能合并。你需要先拿到兩樣?xùn)|西API Key 和 Base URL。Key 在控制臺的 API Keys 頁面創(chuàng)建地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 創(chuàng)建后復(fù)制保存后面填進配置文件。Base URL 統(tǒng)一用 https://taotoken.net/api 注意這個地址后面不加任何路徑后綴QAnything 會自己在后面拼 /v1/chat/completions 這類端點。如果你只是想先驗證模型通不通可以到模型對話頁面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 直接發(fā)一條消息試試確認 Key 有效再往下走。長期跑編碼或 Agent 類任務(wù)的話可以了解下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 按套餐走比單次調(diào)用更劃算。接入細節(jié)和參數(shù)說明都在接入文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里遇到字段對不上時優(yōu)先查這里。注意TaoToken 是合規(guī)的 API 聚合通道配置時只填 Base URL 和 Key不要在任何配置文件里寫額外的網(wǎng)絡(luò)代理參數(shù)QAnything 本身也不需要這些。3. 可復(fù)制的 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 為例核心是改兩處編排文件里的環(huán)境變量以及 QAnything 自己的模型配置文件。先看 docker-compose 里跟 LLM 相關(guān)的片段通常長這樣你需要把 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]這里的關(guān)鍵點是把 LLM、embedding、rerank 三處的 Base URL 全部指向https://taotoken.net/apiKey 也統(tǒng)一成同一把。這樣你以后換模型、換 Key只改這一處不用滿項目找配置。接著是 QAnything 內(nèi)部的模型配置文件一般在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參數(shù)對照可以看這張表方便你按需替換配置項作用建議值base_urlAPI 入口https://taotoken.net/apiapi_key鑒權(quán)密鑰控制臺創(chuàng)建的 Keymodel調(diào)用的模型名按套餐支持的模型填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 以上可以用對應(yīng)的啟動參數(shù)具體看bash ./run.sh -h的輸出。啟動過程會拉鏡像、起 Milvus、MySQL、MinIO 這些依賴服務(wù)第一次會比較慢耐心等日志刷完。啟動成功后前端地址是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說明后端服務(wù)正常。接著往知識庫里傳一個測試文件再發(fā)一條問答請求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 字段有內(nèi)容且不是報錯信息說明 LLM 通道打通了。實測下來第一次問答會稍慢因為要等 embedding 和 rerank 走完后面就快了。5. 本篇常見錯誤排查部署過程中最容易卡在幾個地方我按出現(xiàn)頻率排一下。第一個是模型下載失敗。QAnything 默認會從 HuggingFace 拉模型網(wǎng)絡(luò)不穩(wěn)就會斷。解決辦法是手動下載模型放到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 填錯導(dǎo)致的 401/404。檢查三點Base URL 是不是https://taotoken.net/api且沒多加/v1Key 有沒有多余空格模型名是不是當(dāng)前套餐支持的。日志在QAnything/logs/debug_logs/下llm_server_entrypoint.log和sanic_api.log最有用。第五個是容器間網(wǎng)絡(luò)不通。QAnything 內(nèi)部服務(wù)通過容器名互相訪問如果你改了 compose 的服務(wù)名記得同步改配置里的地址。關(guān)閉服務(wù)用bash close.sh別直接docker rm否則數(shù)據(jù)卷可能殘留。6. 后續(xù)怎么把這套配置用順整套跑通之后你會發(fā)現(xiàn)最大的收益是配置收斂。以前 LLM、embedding、rerank 三套 Key 三套地址現(xiàn)在全指向 TaoToken 一條通道換模型只改 model 字段換 Key 只改一處。如果你要長期跑知識庫問答或者接 Agent建議把 Key 管理放到控制臺統(tǒng)一做地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 需要新 Key 時在 API Keys 頁面創(chuàng)建 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。接入過程中如果碰到字段對不上、報錯看不懂優(yōu)先翻接入文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面把 OpenAI 兼容格式的請求體和返回都列清楚了。想先確認某個模型能不能用直接去模型對話頁面發(fā)一條最快 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。 QAnything 本地部署：用 Docker 配 TaoToken 統(tǒng)一 API 通道的完整安裝方法
1. QAnything 本地部署為什么值得折騰以及它到底解決什么問題QAnything 是網(wǎng)易有道開源的一套本地知識庫問答系統(tǒng)全稱 Question and Answer based on Anything核心能力是把你手頭的 PDF、Word、PPT、Excel、Markdown、TXT、圖片、CSV、網(wǎng)頁鏈接等文件直接丟進去就能基于這些內(nèi)容做問答。它適合誰適合手里有一堆內(nèi)部文檔、產(chǎn)品手冊、技術(shù)資料又不想把數(shù)據(jù)傳到第三方云服務(wù)的團隊和個人。它最大的特點是支持全程斷網(wǎng)安裝使用數(shù)據(jù)不出本地同時內(nèi)置了兩階段檢索embedding 召回 rerank 重排數(shù)據(jù)量越大檢索效果越穩(wěn)這一點比單純用向量檢索要靠譜得多。但真正動手部署過的人會碰到一個很現(xiàn)實的問題QAnything 默認要拉一堆模型服務(wù)LLM、embedding、rerank 各占一塊如果你還想接外部大模型 APIKey 就會散落在好幾個配置文件里。今天改 LLM 的 Key明天換 embedding 的地址配置一多就容易亂。這篇就聚焦 Docker 本地部署場景用 TaoToken 把多模型 API Key 收斂成一條統(tǒng)一通道給出可復(fù)制的 docker-compose 與 config 骨架最后驗證容器啟動和問答連通性。2. 部署前先把 TaoToken 這條統(tǒng)一通道準(zhǔn)備好QAnything 從 v1.2.0 開始支持自定義大模型包括 OpenAI 兼容接口。這意味著只要你的 API 網(wǎng)關(guān)是 OpenAI 格式就能直接接進去。TaoToken 提供的正是這樣一條 OpenAI 兼容通道把不同模型的調(diào)用統(tǒng)一到一個 Base URL 和一把 Key 上QAnything 里那些分散的 LLM 配置就能合并。你需要先拿到兩樣?xùn)|西API Key 和 Base URL。Key 在控制臺的 API Keys 頁面創(chuàng)建地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 創(chuàng)建后復(fù)制保存后面填進配置文件。Base URL 統(tǒng)一用 https://taotoken.net/api 注意這個地址后面不加任何路徑后綴QAnything 會自己在后面拼 /v1/chat/completions 這類端點。如果你只是想先驗證模型通不通可以到模型對話頁面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 直接發(fā)一條消息試試確認 Key 有效再往下走。長期跑編碼或 Agent 類任務(wù)的話可以了解下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 按套餐走比單次調(diào)用更劃算。接入細節(jié)和參數(shù)說明都在接入文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里遇到字段對不上時優(yōu)先查這里。注意TaoToken 是合規(guī)的 API 聚合通道配置時只填 Base URL 和 Key不要在任何配置文件里寫額外的網(wǎng)絡(luò)代理參數(shù)QAnything 本身也不需要這些。3. 可復(fù)制的 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 為例核心是改兩處編排文件里的環(huán)境變量以及 QAnything 自己的模型配置文件。先看 docker-compose 里跟 LLM 相關(guān)的片段通常長這樣你需要把 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]這里的關(guān)鍵點是把 LLM、embedding、rerank 三處的 Base URL 全部指向https://taotoken.net/apiKey 也統(tǒng)一成同一把。這樣你以后換模型、換 Key只改這一處不用滿項目找配置。接著是 QAnything 內(nèi)部的模型配置文件一般在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參數(shù)對照可以看這張表方便你按需替換配置項作用建議值base_urlAPI 入口https://taotoken.net/apiapi_key鑒權(quán)密鑰控制臺創(chuàng)建的 Keymodel調(diào)用的模型名按套餐支持的模型填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 以上可以用對應(yīng)的啟動參數(shù)具體看bash ./run.sh -h的輸出。啟動過程會拉鏡像、起 Milvus、MySQL、MinIO 這些依賴服務(wù)第一次會比較慢耐心等日志刷完。啟動成功后前端地址是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說明后端服務(wù)正常。接著往知識庫里傳一個測試文件再發(fā)一條問答請求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 字段有內(nèi)容且不是報錯信息說明 LLM 通道打通了。實測下來第一次問答會稍慢因為要等 embedding 和 rerank 走完后面就快了。5. 本篇常見錯誤排查部署過程中最容易卡在幾個地方我按出現(xiàn)頻率排一下。第一個是模型下載失敗。QAnything 默認會從 HuggingFace 拉模型網(wǎng)絡(luò)不穩(wěn)就會斷。解決辦法是手動下載模型放到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 填錯導(dǎo)致的 401/404。檢查三點Base URL 是不是https://taotoken.net/api且沒多加/v1Key 有沒有多余空格模型名是不是當(dāng)前套餐支持的。日志在QAnything/logs/debug_logs/下llm_server_entrypoint.log和sanic_api.log最有用。第五個是容器間網(wǎng)絡(luò)不通。QAnything 內(nèi)部服務(wù)通過容器名互相訪問如果你改了 compose 的服務(wù)名記得同步改配置里的地址。關(guān)閉服務(wù)用bash close.sh別直接docker rm否則數(shù)據(jù)卷可能殘留。6. 后續(xù)怎么把這套配置用順整套跑通之后你會發(fā)現(xiàn)最大的收益是配置收斂。以前 LLM、embedding、rerank 三套 Key 三套地址現(xiàn)在全指向 TaoToken 一條通道換模型只改 model 字段換 Key 只改一處。如果你要長期跑知識庫問答或者接 Agent建議把 Key 管理放到控制臺統(tǒng)一做地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 需要新 Key 時在 API Keys 頁面創(chuàng)建 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。接入過程中如果碰到字段對不上、報錯看不懂優(yōu)先翻接入文檔 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面把 OpenAI 兼容格式的請求體和返回都列清楚了。想先確認某個模型能不能用直接去模型對話頁面發(fā)一條最快 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。