1. Windows 本地部署 FastGPT 知识库问答从 Docker 到 deepseek 模型接入的完整链路FastGPT 是一套开源的本地知识库问答系统能把你手头的 PDF、Word、Markdown 文档切片、向量化再配合大语言模型做检索增强问答。它适合谁适合不想把内部资料传到公有云、又希望有类似 ChatGPT 体验的开发者和小团队。整套系统跑在 Windows 上靠 Docker 拉起 FastGPT、PostgreSQL(pgvector)、One API 三个容器模型调用则通过 One API 统一转发到 deepseek。我这次的目标很明确在 Windows 上从零搭出一套能用的本地知识库问答语言模型用 deepseek-chat向量模型用 embedding-2所有模型请求都经过 One API 这个统一网关。为什么非要加 One API 这一层因为 FastGPT 本身只认 OpenAI 格式的接口而 deepseek、智谱这些厂商的地址和鉴权方式各不相同One API 把它们统一成一套 Base URL Key Model ID后面换模型、加渠道都不用动 FastGPT 的配置。整条链路的关键节点有三个Docker 环境能正常拉镜像、One API 渠道测试通过、FastGPT 的 config.json 里模型名和 One API 令牌范围对得上。这三个任意一个出问题最后的表现都是「知识库创建时模型下拉框是空的」或者「对话报错 reading choices」。下面按顺序把每一步的可复制配置和验证方法写清楚。需要提前说明的是模型调用通道除了直连厂商也可以用 TaoToken 这类统一 Key/API 通道来管理它把多家模型的调用收敛到一个入口省去在多个平台之间切换密钥的麻烦。本文的配置以 One API 为网关你可以在 One API 里把上游指向任意兼容 OpenAI 协议的服务。2. 前置环境Docker Desktop 与 WSL2 在 Windows 上的配置要点这一章解决的是「容器跑不起来」的根因问题。FastGPT 官方推荐用 Docker Compose 部署Windows 上跑 Linux 容器依赖 WSL2 后端所以 Docker Desktop 和 WSL2 必须都装好、都更新到较新版本。先装 Docker Desktop。去 Docker 官网下载 AMD64 版本安装完重启电脑启动 Docker Desktop。首次启动如果卡在登录界面直接跳过登录进主界面即可本地开发不需要账号。装完后确认左下角或状态栏显示 Engine running。接着处理 WSL2。WSL 全称 Windows Subsystem for Linux是在 Windows 上运行原生 Linux 二进制的兼容层Docker 的 Linux 容器就靠它。打开 PowerShell 或 cmd执行wsl --update这条命令会自动拉取最新版内核并检查更新。然后进入「启用或关闭 Windows 功能」确认「适用于 Linux 的 Windows 子系统」和「虚拟机平台」两项已勾选没勾就勾上再重启。回到 Docker Desktop 的设置里General 中确认 Use the WSL 2 based engine 已开启。镜像拉取慢是另一个高频卡点。在 Docker Desktop 的 Settings → Docker Engine 里把配置改成带镜像加速的版本{ debug: true, experimental: false, insecure-registries: [], registry-mirrors: [ https://docker.unsee.tech, https://docker.m.daocloud.io ] }改完点 Apply restart再重启一次 Docker Desktop。如果状态栏提示 Docker Engine Stopped按顺序排查任务管理器服务里确认 com.docker.service 在运行确认 Hyper-V 已勾选以管理员身份打开终端执行bcdedit看最后一行 hypervisorlaunchtype 是否为 Auto不是就执行下面这条再重启电脑bcdedit /set hypervisorlaunchtype auto最后确认 WSL 已更新、镜像地址配置正确。这几步做完docker info能正常输出、docker pull hello-world能拉下来前置环境就算过关了。踩过的坑基本都集中在 WSL 内核版本旧和镜像地址失效这两处先解决它们能省掉后面大量误判。3. 可复制配置docker-compose.yml 与 config.json 的模型对接这一章是全文的核心交付两份能直接用的配置文件片段。先在磁盘上新建一个空文件夹比如D:\FastGPT所有配置和启动命令都在这个目录里执行。第一份是docker-compose.yml。FastGPT 官方仓库的files/docker/目录下有 pgvector 版本可以直接下载curl -o docker-compose.yml https://raw.githubusercontent.com/labring/FastGPT/main/files/docker/docker-compose-pgvector.yml下载后重点改两个环境变量它们决定 FastGPT 去哪里调模型environment: - OPENAI_BASE_URLhttp://host.docker.internal:3001/v1 - CHAT_API_KEYsk-你的OneAPI令牌注意 Base URL 结尾必须带/v1这是 OpenAI 兼容接口的约定。容器内访问宿主机的 One API用host.docker.internal代替 localhost如果 FastGPT 和 One API 在同一个 Docker 网络里也可以直接写服务名加端口。CHAT_API_KEY填的是 One API 里生成的令牌不是 deepseek 官方的 key这一点最容易搞混。第二份是config.json它告诉 FastGPT 有哪些模型可用。语言模型加进llmModels向量模型加进vectorModels{ llmModels: [ { provider: OneAPI, model: deepseek-chat, name: deepseek-chat, maxContext: 16000, maxResponse: 4000, quoteMaxToken: 12000, maxTemperature: 1, vision: false, functionCall: false, defaultSystemChatPrompt: } ], vectorModels: [ { provider: OneAPI, model: embedding-2, name: embedding-2, defaultToken: 500, maxToken: 3000 } ] }这里的model字段必须和 One API 渠道里填写的模型名完全一致大小写都不能差。provider写 OneAPI 表示走统一网关。改完两份文件后在 FastGPT 目录下执行docker-compose pull docker-compose up -dpull会拉取镜像耗时较长属正常。up -d后台启动后用docker ps确认三个容器都是 Up 状态。FastGPT 映射到 3000 端口One API 映射到 3001 端口浏览器访问http://localhost:3000即可。FastGPT 默认账号 root、密码 1234One API 默认账号 root、密码 123456首次登录 One API 会强制改密码。如果你希望模型调用通道更集中可以在 One API 的上游渠道里指向 TaoToken 提供的统一 API 入口这样密钥和额度管理都在一个面板里完成FastGPT 侧完全不用改。4. 验证请求One API 渠道测试与知识库问答全链路确认配置写完不代表通了这一章用实际请求验证每一环。先验证 One API 到 deepseek 的链路。登录http://localhost:3001进入「渠道」→「创建新的渠道」类型选 deepseek模型填deepseek-chat密钥填 deepseek 官方申请的 sk代理地址填https://api.deepseek.com提交后点「测试」。如果返回响应时间比如 800ms说明渠道通了如果报错先检查密钥和地址。接着去「令牌」→「添加新的令牌」模型范围勾选deepseek-chat提交后复制生成的 sk 保存好。这个令牌就是前面CHAT_API_KEY要填的值。一个令牌可以覆盖多个渠道的模型后面加 embedding-2 时把范围一起勾上即可。验证 FastGPT 侧。重启服务让配置生效docker-compose down docker-compose up -d进入http://localhost:3000在工作台新建一个应用AI 模型下拉框里应该能看到deepseek-chat。如果看不到说明 config.json 的模型名和令牌范围没对上或者容器没重启。选中模型后在右侧对话框发一句「你好介绍一下你自己」能正常流式返回就说明语言模型链路通了。再验证向量模型。去智谱开放平台申请 embedding-2 的密钥在 One API 里新建渠道模型填embedding-2把该模型加入令牌范围。回到 config.json 的vectorModels确认配置无误重启服务。进入 FastGPT 的「知识库」→「新建知识库」两个模型下拉框分别选 deepseek-chat 和 embedding-2都能选中才说明向量链路也通了。最后做端到端测试在知识库里上传一份自己的文档等切片和向量化完成回到工作台新建应用类型选「知识库对话引导」关联刚才的知识库把「问题优化」模型设为 deepseek-chat保存。然后问一个只有文档里才有答案的问题比如文档里写了某个内部流程的步骤看回答是否引用了文档内容。能引用并给出正确步骤整套本地知识库问答系统就算跑通了。5. 常见报错排查401、local proxy failed 与 reading choices 的定位方法这一章按真实报错对照排查覆盖接入过程中最常撞见的几类问题。401 Unauthorized。表现是 One API 渠道测试或 FastGPT 对话返回鉴权失败。根因通常是密钥填错或令牌范围不含该模型。排查顺序确认 One API 渠道里的上游密钥是厂商原始 sk确认 FastGPT 的CHAT_API_KEY填的是 One API 令牌而非厂商密钥确认令牌的模型范围勾选了对应模型。三者任一错位都会 401。local proxy failed / connection refused。表现是 FastGPT 容器日志里出现连接 One API 失败。根因是OPENAI_BASE_URL地址不对。容器内不能用localhost指代宿主机要写host.docker.internal端口要确认是 One API 实际映射的 3001结尾的/v1不能漏。改完必须docker-compose down docker-compose up -d重启环境变量不会热加载。reading choices 报错。表现是对话时后端抛异常提示读取 choices 字段失败。这通常意味着上游返回的不是标准 OpenAI 格式或者模型名在 One API 里不存在。检查 One API 渠道里模型名是否和 config.json 完全一致检查渠道测试是否真的通过。如果用的是非 OpenAI 兼容的上游需要在 One API 里做格式转换。OAuth / 登录相关报错。One API 首次登录强制改密码如果跳过或改密失败后续接口调用会鉴权异常。重新登录http://localhost:3001完成改密流程即可。FastGPT 侧如果改了DEFAULT_ROOT_PSW环境变量要重启容器才生效。知识库创建时模型下拉框为空。这是配置类问题里最典型的。根因是 config.json 的模型名、One API 令牌范围、渠道模型三者没有对齐。按「渠道模型名 令牌范围 config.json 的 model 字段」这条等式逐个核对改完重启。另外注意 config.json 是 JSON 格式多一个逗号或少一个引号都会导致解析失败模型列表直接为空。排查时善用日志docker logs -f fastgpt看 FastGPT 报错docker logs -f oneapi看网关转发情况。大部分问题在日志里都有明确指向比盲目改配置高效得多。6. 把模型调用收敛到一个入口TaoToken 统一 Key 与 API 通道管理整套系统跑起来后你会发现模型密钥散落在多个地方deepseek 一个、智谱一个以后再加别的厂商还要继续加。One API 已经做了一层收敛但上游渠道的密钥管理、额度查看、多项目隔离仍然需要一套更顺手的通道。TaoToken 提供的统一 Key/API 通道可以把多家模型的调用收敛到一个入口。在 One API 里新建渠道时把上游地址指向 TaoToken 的 API 入口密钥填 TaoToken 生成的 Key模型名按需填写这样 FastGPT 侧完全不用感知上游是哪家厂商。想换模型时只改 One API 渠道FastGPT 的 config.json 和令牌范围都不用动。具体操作上先到 TaoToken 控制台创建一个 API Key然后在 One API 的渠道配置里代理地址填https://taotoken.net/api密钥填刚创建的 Key模型填你要用的模型 ID。提交后测试连接返回响应时间即成功。之后 FastGPT 的CHAT_API_KEY依然填 One API 令牌整条链路不变。如果你更习惯直接调模型做验证可以打开模型对话页面发一条测试消息确认 Key 和通道可用需要长期跑编码或 Agent 类任务可以了解 Coding Plan 的额度方案密钥和通道的日常管理在控制台完成接入细节和参数说明看接入文档。把这几处入口记下来后面加模型、换通道、查额度都不用再翻配置。最后留一个实用习惯每次改完docker-compose.yml或config.json先docker-compose down再up -d然后用docker ps确认容器状态再进 FastGPT 验证模型下拉框。这套动作固定下来配置类问题基本不会反复出现。