第10章 全栈联调与排错作者亢AIRTC| 源码地址https://github.com/kang-airtc/ollama-mini-book走到本章读者已经在前面九章里把所有零件分别讲清楚。但分头跑通与整套跑通是两回事Ollama、MCP Server、FastAPI、Next.js 四个进程需要按正确顺序启动相互的端口、依赖、模型必须就位。本章把全栈联调的步骤、常见故障、调试技巧一并整理作为读者跑通本书项目的最后一道指南。完成本章后读者将拥有一份可重复使用的本地部署 Checklist并具备在任意环境下迅速定位 RAG 链路故障的能力。10.1 启动顺序与端口规划本项目涉及四个独立进程各自占用不同端口启动顺序不能乱上游服务必须先于依赖它的下游服务启动。完整的服务拓扑与启动顺序“如图10-1”所示。10.1.1 各服务的端口与依赖关系服务的端口分配与上下游依赖“如表10-1”所示。表 10-1 RAG 全栈服务的端口与依赖关系服务端口上游依赖下游消费者Ollama11434无MCP Server、FastAPIMCP Server8001OllamaFastAPIFastAPI 后端8000Ollama、MCP ServerNext.js 前端Next.js 前端3000FastAPI浏览器用户读者从表中可以看到Ollama 是整个链路的根依赖必须最先启动MCP Server 与 FastAPI 都直接依赖 Ollama前端只与 FastAPI 交互启动顺序最晚。10.1.2 启动命令清单四个服务的启动命令按顺序整理。ollama serveOllama 默认会被系统服务托管如果已经在后台运行可跳过这一步。手动启动用于希望观察日志的场景。cdagentsourcevenv/bin/activate python agent_server.pyMCP Server 启动时会先初始化样本数据如果向量库为空看到“启动电商工单向量检索 MCP Server…”字样即就绪。cdbackendsourcevenv/bin/activate uvicorn main:app--reload--port8000FastAPI 后端用 uvicorn 启动–reload 让代码改动后自动重启便于开发。生产部署应去掉 --reload 并由 gunicorn 或 systemd 托管。cdfrontendnpmrun devNext.js 开发服务器默认监听 3000 端口。读者打开浏览器访问 http://localhost:3000 即可进入聊天页面。注意venv 是各服务各自的虚拟环境目录互不相同切换服务时记得先用 deactivate 退出当前环境再激活下一个避免依赖混用。10.2 联调前的环境检查每次重新拉取代码或换机器先按 Checklist 走一遍环境检查能避免大部分“莫名其妙跑不起来”的问题。10.2.1 Ollama 与模型可用性执行三条命令逐一确认。curlhttp://localhost:11434 ollama list ollama run llama3.2你好第一条确认服务可达第二条确认两个模型都在本地第三条做一次最小生成验证模型可用。任何一条失败都说明 Ollama 侧有问题应优先解决。10.2.2 Python 依赖完整性两个 Python 项目的 requirements.txt 必须分别安装。cdagentpipinstall-rrequirements.txtcd../backendpipinstall-rrequirements.txt如果 pip 安装中报错常见原因是 Python 版本过低或国内网络拉取 PyPI 失败。本书项目建议 Python 3.10 及以上网络问题可通过临时切换镜像源解决。10.2.3 Node 依赖与版本前端项目执行依赖安装与启动前的快速验证。cdfrontendnpminstallnpx next infonext info 输出 Node 版本与 Next.js 版本便于读者确认本地环境与项目期望匹配。Node 版本应不低于 18。注意Next.js 主版本迭代较快API 变化频繁读者把代码迁移到新机器时应优先按 package.json 中的版本锁定安装避免大版本跳跃带来兼容问题。10.3 常见故障与排查本节把笔者在搭建过程中遇到的高频问题汇总提供症状与解决思路。10.3.1 Ollama 调用层面Ollama 端常见故障与处理“如表10-2”所示。表 10-2 Ollama 调用常见故障症状可能原因排查动作ConnectionRefusedErrorOllama 服务未启动执行 ollama serve 或检查后台进程404 model not found模型未 pull 到本地执行 ollama pull 对应模型生成卡住无输出模型首次加载耗时较长等待 10 至 30 秒或检查内存占用中文输出乱码终端编码非 UTF-8设置 LANG 与 LC_ALL 为 zh_CN.UTF-810.3.2 MCP Server 与客户端MCP 链路常见问题与处理“如表10-3”所示。表 10-3 MCP 调用常见故障症状可能原因排查动作客户端调用 hangsMCP Server 未启动或端口被占用curl http://localhost:8001/mcp 验证连通工具列表为空mcp.tool 装饰器未生效确认装饰器写在 mcp 实例化之后工具返回 JSON 解析失败工具内部抛异常未捕获在工具内部 try/except 把异常转 JSONChromaDB 报维度不匹配嵌入模型变更未重建集合删除 chroma_db 目录后重启 MCP Server读者特别注意维度不匹配这一类问题一旦更换嵌入模型必须删除整个 ChromaDB 目录重建否则旧向量与新查询向量无法做比较。10.3.3 FastAPI 与 SSE后端常见问题与处理“如表10-4”所示。表 10-4 FastAPI 后端常见故障症状可能原因排查动作前端长时间无响应Ollama 生成耗时过长调小 num_predict、关闭其他模型释放内存CORS 报错前端 origin 不在 allow_origins 中把实际域名加入 CORS 配置SSE 连接立即断开路由函数没有写成 async 生成器把 return 改为 yield或确认 yield 路径可达asyncio.CancelledError 被吞except Exception 误捕获单独处理 CancelledError 不吞10.3.4 Next.js 前端前端常见问题与处理“如表10-5”所示。表 10-5 Next.js 前端常见故障症状可能原因排查动作EventSource 报错 401/403后端鉴权或反向代理拦截检查后端 CORS 与代理是否放过 SSE流式回答只在最后一次性出现反向代理或 CDN 做了缓冲关闭代理对 text/event-stream 的缓冲useEffect 中连接被立刻关闭React Strict Mode 二次触发把核心连接逻辑移出 useEffect中文输入框光标错位CSS 中 line-height 与 input 高度不一致在 input 上单独设置合适的行高注意流式回答只在最后一次性出现是部署环境最常见的坑本地开发顺畅、上线后却卡住几乎都是反向代理如 Nginx默认对 HTTP/1.1 流做了缓冲所致。10.4 端到端验证流程跑通后建议按一份固定的验证流程做回归确认整条链路没有断点。10.4.1 三组典型查询构造三组覆盖不同分支的查询验证检索与生成行为。1. 命中检索的查询输入“客户投诉物流配送延迟怎么办”预期检索到与物流查询、退款相关的工单并由 LLM 给出结构化回答。2. 部分命中的查询输入“账户登录问题”预期检索到账户问题相关工单一条LLM 应能基于单条工单给出回答。3. 未命中检索的查询输入“如何提升 NPS 评分”预期检索为空LLM 走兜底模板明确告知“知识库中无相关工单”。三组查询覆盖了 RAG 链路的三种主要分支命中、部分命中、未命中。每次代码或数据有较大变化后跑一遍能快速发现回归。10.4.2 数据重建验证启动 MCP Client 单独验证 rebuild_vector_store 工具可用。resultawaitcall_agent_tool(rebuild_vector_store,{})print(result)读者预期看到返回 “向量库重建完成当前共 10 条数据”。这一步验证了向量库可重建、MCP 写操作工具可被调用、ChromaDB 写入路径正常。10.4.3 SSE 事件顺序验证打开浏览器 DevTools 的 Network 面板过滤 EventStream 协议发起一次查询后应能看到以下顺序的事件流。事件顺序与含义“如表10-6”所示。表 10-6 一次完整请求的 SSE 事件顺序顺序事件名说明1status收到查询请求2status开始语义检索3retrieved_data检索结果推送4status开始 LLM 生成5 至 Nllm_chunk多条 LLM 生成片段最后status回答完成如果在任意阶段卡住问题就出现在对应模块。比如卡在 2 与 3 之间问题在 MCP 或 ChromaDB卡在 4 与 5 之间问题在 Ollama 生成首字延迟。10.5 本地部署的提升路径跑通最小可用之后读者可能希望把项目部署到团队内或个人服务器上。本节给出几条延伸方向作为本书的收尾。10.5.1 进程管理开发时直接 python、uvicorn、npm run dev 启动方便长期运行应交给 systemd、supervisor 或 pm2 等进程管理工具。它们提供自动重启、日志切割、开机自启等能力让服务长期稳定运行。10.5.2 反向代理与 TLS把三个后端服务Ollama、MCP、FastAPI放在内网对外只通过 Nginx 反向代理暴露前端与必要的 API 路径并配上 TLS 证书。对 text/event-stream 的代理需要显式关闭 proxy_buffering 与 gzip。10.5.3 数据备份ChromaDB 数据目录与配套的原始文本应一并备份建议每次重建向量库前打快照。原始文本如工单 JSON作为可追溯的事实来源单独管理向量库作为可重建的派生产物管理这种分层能让数据恢复变得简单。注意本地大模型部署的真正瓶颈是硬件资源模型升级前应先观察当前模型在峰值负载下的 CPU、内存、延迟表现再决定是否值得换更大模型。10.6 本章小结本章把 RAG 全栈四个服务的启动顺序、环境检查、常见故障与端到端验证流程整理为一份可复用的指南。读者按本章 Checklist 操作即可顺畅地把项目跑起来并在出问题时迅速定位故障所在。回到本书开头笔者的目标是带领读者用本地大模型完整构建一条 RAG 链路让数据与模型都留在自己机器上。十章过后读者手中应有的不只是一个工单检索 Demo而是一套可迁移到任意业务的本地 AI 全栈方法论。把工单换成产品文档、把客服分析换成代码助手、把工单类型换成自定义元数据链路结构几乎不变。希望这本小册成为读者本地 AI 实践之路上的可靠起点。本章配套源码https://github.com/kang-airtc/agent-ollama-book作者光谷老亢配套源码https://github.com/kang-airtc/ollama-mini-book
第10章 全栈联调与排错
发布时间：2026/5/30 14:58:31
第10章 全栈联调与排错作者亢AIRTC| 源码地址https://github.com/kang-airtc/ollama-mini-book走到本章读者已经在前面九章里把所有零件分别讲清楚。但分头跑通与整套跑通是两回事Ollama、MCP Server、FastAPI、Next.js 四个进程需要按正确顺序启动相互的端口、依赖、模型必须就位。本章把全栈联调的步骤、常见故障、调试技巧一并整理作为读者跑通本书项目的最后一道指南。完成本章后读者将拥有一份可重复使用的本地部署 Checklist并具备在任意环境下迅速定位 RAG 链路故障的能力。10.1 启动顺序与端口规划本项目涉及四个独立进程各自占用不同端口启动顺序不能乱上游服务必须先于依赖它的下游服务启动。完整的服务拓扑与启动顺序“如图10-1”所示。10.1.1 各服务的端口与依赖关系服务的端口分配与上下游依赖“如表10-1”所示。表 10-1 RAG 全栈服务的端口与依赖关系服务端口上游依赖下游消费者Ollama11434无MCP Server、FastAPIMCP Server8001OllamaFastAPIFastAPI 后端8000Ollama、MCP ServerNext.js 前端Next.js 前端3000FastAPI浏览器用户读者从表中可以看到Ollama 是整个链路的根依赖必须最先启动MCP Server 与 FastAPI 都直接依赖 Ollama前端只与 FastAPI 交互启动顺序最晚。10.1.2 启动命令清单四个服务的启动命令按顺序整理。ollama serveOllama 默认会被系统服务托管如果已经在后台运行可跳过这一步。手动启动用于希望观察日志的场景。cdagentsourcevenv/bin/activate python agent_server.pyMCP Server 启动时会先初始化样本数据如果向量库为空看到“启动电商工单向量检索 MCP Server…”字样即就绪。cdbackendsourcevenv/bin/activate uvicorn main:app--reload--port8000FastAPI 后端用 uvicorn 启动–reload 让代码改动后自动重启便于开发。生产部署应去掉 --reload 并由 gunicorn 或 systemd 托管。cdfrontendnpmrun devNext.js 开发服务器默认监听 3000 端口。读者打开浏览器访问 http://localhost:3000 即可进入聊天页面。注意venv 是各服务各自的虚拟环境目录互不相同切换服务时记得先用 deactivate 退出当前环境再激活下一个避免依赖混用。10.2 联调前的环境检查每次重新拉取代码或换机器先按 Checklist 走一遍环境检查能避免大部分“莫名其妙跑不起来”的问题。10.2.1 Ollama 与模型可用性执行三条命令逐一确认。curlhttp://localhost:11434 ollama list ollama run llama3.2你好第一条确认服务可达第二条确认两个模型都在本地第三条做一次最小生成验证模型可用。任何一条失败都说明 Ollama 侧有问题应优先解决。10.2.2 Python 依赖完整性两个 Python 项目的 requirements.txt 必须分别安装。cdagentpipinstall-rrequirements.txtcd../backendpipinstall-rrequirements.txt如果 pip 安装中报错常见原因是 Python 版本过低或国内网络拉取 PyPI 失败。本书项目建议 Python 3.10 及以上网络问题可通过临时切换镜像源解决。10.2.3 Node 依赖与版本前端项目执行依赖安装与启动前的快速验证。cdfrontendnpminstallnpx next infonext info 输出 Node 版本与 Next.js 版本便于读者确认本地环境与项目期望匹配。Node 版本应不低于 18。注意Next.js 主版本迭代较快API 变化频繁读者把代码迁移到新机器时应优先按 package.json 中的版本锁定安装避免大版本跳跃带来兼容问题。10.3 常见故障与排查本节把笔者在搭建过程中遇到的高频问题汇总提供症状与解决思路。10.3.1 Ollama 调用层面Ollama 端常见故障与处理“如表10-2”所示。表 10-2 Ollama 调用常见故障症状可能原因排查动作ConnectionRefusedErrorOllama 服务未启动执行 ollama serve 或检查后台进程404 model not found模型未 pull 到本地执行 ollama pull 对应模型生成卡住无输出模型首次加载耗时较长等待 10 至 30 秒或检查内存占用中文输出乱码终端编码非 UTF-8设置 LANG 与 LC_ALL 为 zh_CN.UTF-810.3.2 MCP Server 与客户端MCP 链路常见问题与处理“如表10-3”所示。表 10-3 MCP 调用常见故障症状可能原因排查动作客户端调用 hangsMCP Server 未启动或端口被占用curl http://localhost:8001/mcp 验证连通工具列表为空mcp.tool 装饰器未生效确认装饰器写在 mcp 实例化之后工具返回 JSON 解析失败工具内部抛异常未捕获在工具内部 try/except 把异常转 JSONChromaDB 报维度不匹配嵌入模型变更未重建集合删除 chroma_db 目录后重启 MCP Server读者特别注意维度不匹配这一类问题一旦更换嵌入模型必须删除整个 ChromaDB 目录重建否则旧向量与新查询向量无法做比较。10.3.3 FastAPI 与 SSE后端常见问题与处理“如表10-4”所示。表 10-4 FastAPI 后端常见故障症状可能原因排查动作前端长时间无响应Ollama 生成耗时过长调小 num_predict、关闭其他模型释放内存CORS 报错前端 origin 不在 allow_origins 中把实际域名加入 CORS 配置SSE 连接立即断开路由函数没有写成 async 生成器把 return 改为 yield或确认 yield 路径可达asyncio.CancelledError 被吞except Exception 误捕获单独处理 CancelledError 不吞10.3.4 Next.js 前端前端常见问题与处理“如表10-5”所示。表 10-5 Next.js 前端常见故障症状可能原因排查动作EventSource 报错 401/403后端鉴权或反向代理拦截检查后端 CORS 与代理是否放过 SSE流式回答只在最后一次性出现反向代理或 CDN 做了缓冲关闭代理对 text/event-stream 的缓冲useEffect 中连接被立刻关闭React Strict Mode 二次触发把核心连接逻辑移出 useEffect中文输入框光标错位CSS 中 line-height 与 input 高度不一致在 input 上单独设置合适的行高注意流式回答只在最后一次性出现是部署环境最常见的坑本地开发顺畅、上线后却卡住几乎都是反向代理如 Nginx默认对 HTTP/1.1 流做了缓冲所致。10.4 端到端验证流程跑通后建议按一份固定的验证流程做回归确认整条链路没有断点。10.4.1 三组典型查询构造三组覆盖不同分支的查询验证检索与生成行为。1. 命中检索的查询输入“客户投诉物流配送延迟怎么办”预期检索到与物流查询、退款相关的工单并由 LLM 给出结构化回答。2. 部分命中的查询输入“账户登录问题”预期检索到账户问题相关工单一条LLM 应能基于单条工单给出回答。3. 未命中检索的查询输入“如何提升 NPS 评分”预期检索为空LLM 走兜底模板明确告知“知识库中无相关工单”。三组查询覆盖了 RAG 链路的三种主要分支命中、部分命中、未命中。每次代码或数据有较大变化后跑一遍能快速发现回归。10.4.2 数据重建验证启动 MCP Client 单独验证 rebuild_vector_store 工具可用。resultawaitcall_agent_tool(rebuild_vector_store,{})print(result)读者预期看到返回 “向量库重建完成当前共 10 条数据”。这一步验证了向量库可重建、MCP 写操作工具可被调用、ChromaDB 写入路径正常。10.4.3 SSE 事件顺序验证打开浏览器 DevTools 的 Network 面板过滤 EventStream 协议发起一次查询后应能看到以下顺序的事件流。事件顺序与含义“如表10-6”所示。表 10-6 一次完整请求的 SSE 事件顺序顺序事件名说明1status收到查询请求2status开始语义检索3retrieved_data检索结果推送4status开始 LLM 生成5 至 Nllm_chunk多条 LLM 生成片段最后status回答完成如果在任意阶段卡住问题就出现在对应模块。比如卡在 2 与 3 之间问题在 MCP 或 ChromaDB卡在 4 与 5 之间问题在 Ollama 生成首字延迟。10.5 本地部署的提升路径跑通最小可用之后读者可能希望把项目部署到团队内或个人服务器上。本节给出几条延伸方向作为本书的收尾。10.5.1 进程管理开发时直接 python、uvicorn、npm run dev 启动方便长期运行应交给 systemd、supervisor 或 pm2 等进程管理工具。它们提供自动重启、日志切割、开机自启等能力让服务长期稳定运行。10.5.2 反向代理与 TLS把三个后端服务Ollama、MCP、FastAPI放在内网对外只通过 Nginx 反向代理暴露前端与必要的 API 路径并配上 TLS 证书。对 text/event-stream 的代理需要显式关闭 proxy_buffering 与 gzip。10.5.3 数据备份ChromaDB 数据目录与配套的原始文本应一并备份建议每次重建向量库前打快照。原始文本如工单 JSON作为可追溯的事实来源单独管理向量库作为可重建的派生产物管理这种分层能让数据恢复变得简单。注意本地大模型部署的真正瓶颈是硬件资源模型升级前应先观察当前模型在峰值负载下的 CPU、内存、延迟表现再决定是否值得换更大模型。10.6 本章小结本章把 RAG 全栈四个服务的启动顺序、环境检查、常见故障与端到端验证流程整理为一份可复用的指南。读者按本章 Checklist 操作即可顺畅地把项目跑起来并在出问题时迅速定位故障所在。回到本书开头笔者的目标是带领读者用本地大模型完整构建一条 RAG 链路让数据与模型都留在自己机器上。十章过后读者手中应有的不只是一个工单检索 Demo而是一套可迁移到任意业务的本地 AI 全栈方法论。把工单换成产品文档、把客服分析换成代码助手、把工单类型换成自定义元数据链路结构几乎不变。希望这本小册成为读者本地 AI 实践之路上的可靠起点。本章配套源码https://github.com/kang-airtc/agent-ollama-book作者光谷老亢配套源码https://github.com/kang-airtc/ollama-mini-book
