从原型到交付15 分钟上手的 v1.0.0M8 收官系列城市管理 Agentic RAG —— 从零搭建城市管理问答系统本篇M8 · 文档完善 最终交付实测版系列收官篇源码https://gitee.com/Chester_Xue/city-agentic-rag一、M7 之后还差什么M7 之后系统已经很好用了点两下就出研判报告日志可复盘引用可溯源。但站在交付的角度还差最后一口气只有作者本人会用这个系统。不信你换个视角一个完全没参与开发的新同事拿到这个仓库他能跑起来吗大概率卡在第一步——README 没有截图不知道界面长什么样没有部署手册不知道.env里那些参数是什么意思甚至不知道要先python -m src.index建索引。M8 的验收标准写得很朴素「新同事按 README 可在 15 分钟内完成配置并首次问答」。这一阶段不写一行业务代码只做四件事README 完善项目背景、架构图、安装步骤、场景截图新增docs/部署手册.md详细配置说明代码整理删除调试语句推送 Gitee打v1.0.0标签 创建 Release。二、交付了什么1. README从「作者笔记」变成「项目门面」补齐了三块最要命的内容场景截图用无头浏览器打开真实界面截了两张——首页 点「暴雨应急」后的综合研判结果。读者一眼就知道这个系统长什么样、能干什么部署手册链接文档索引里加了《部署手册》安装配置一步不落版本信息徽章更新到 v1.0.0 / M8 已完成。2. 部署手册15 分钟被拆成了 5 3 7docs/部署手册.md是这一阶段的重点交付物完全按「新同事」视角写5 分钟安装clone → venv →pip install -r requirements.txt附国内镜像命令→cp .env.example .env→python -m src.index建索引3 分钟启动Web 界面一行命令CLI 一行命令各给一段真实输出示例7 分钟缓冲.env全参数表12 个参数逐个解释、场景自定义方法、日志说明、FAQ 七个问题国内网络慢怎么办 / GPU 报错怎么办 / 没配 API Key 怎么办 / 端口占用怎么办 / 为什么总说「暂无相关信息」 / 回答与资料不符怎么办 / 想换模型换向量库怎么办、验收自检清单。写 FAQ 的原则把作者踩过的坑提前变成读者的答案。M7 踩的四个环境坑缺依赖、镜像冻结、老 GPU、模型重复加载全部变成了 FAQ 条目或代码里的注释——别人不会再花一个下午。比如「老架构 GPU 崩溃」这个坑M7 排查花了整整半天在手册里就是一条 FAQQ模型推理报 CUDA error: no kernel image is available A老架构 GPU如 GTX 950M / sm_50与新版 torch CUDA 内核不兼容。 代码已内置 CUDA_VISIBLE_DEVICES 强制 CPU 推理bge-small-zh 很小CPU 完全够用 一般无需处理若显式设置过 CUDA_VISIBLE_DEVICES 请留空。后来者遇到同样的问题半分钟就能解决。3. 代码整理搜索式排查而不是肉眼过一遍用正则全库扫TODO / FIXME / debugger / pdb / XXX结果是0 条。CLI 里那些[路由]、[检索]、[反思]打印行是设计上的可配置演示开关.env里SHOW_ROUTE等可关不是调试残留保留。4. v1.0.0标签 Release 发布说明按版本规范打了v1.0.0标签并在 Gitee 创建了正式 Release发布说明覆盖 M0~M8 九个版本的全量信息里程碑表、核心能力、快速开始、演示效果、环境适配说明。三、最关键的一步从标签验证交付物文档写完、标签打完、Release 创建完——然后呢「我能跑」和「别人拿到手能跑」是两回事。所以 M8 的最后一步是把 v1.0.0 标签 clone 到临时目录完整模拟一遍新同事流程gitclone--branchv1.0.0 gitgitee.com:Chester_Xue/city-agentic-rag.git /tmp/verifycd/tmp/verifycp.env.example .env# 填入 API Keypipinstall-rrequirements.txt python-msrc.index# 重建索引python-msrc.cli# 首次问答python-msrc.webui# Web 冒烟每一步的结果步骤结果文件完整性README/部署手册/截图/源码/示例配置✅ 齐全.env、chroma_db/、日志确认未入库✅ 新同事拿到的确实是干净初始态pip install -r✅ 秒过依赖清单完整无缺失重建索引✅ 13 份文档42.6 秒CLI 首次问答暴雨弱势群体 → 路由 weathercivil → 反思核查✅ 诚实作答Web 冒烟场景填充 问候✅ 1 秒就绪验证通过然后立刻把临时目录删了——里面有一份真实的 API Key处理完即删是底线。为什么必须做这一步两个原因Release 的 zip/tar 是创建时刻的静态快照之后改代码不会自动更新git status干净 ≠ 交付物可运行——文件在不在、依赖全不全、索引能不能重建只有从零走一遍才知道。还有一个容易被忽略的点这次验证是一次通过的。这不是运气而是因为部署手册里的每一条命令都是从真实执行记录里抄出来的——安装步骤是装环境时一步步敲过的索引命令是重建时跑过的问答示例是 CLI 转录的。文档如果凭记忆写验证时一定会翻车文档照着执行记录写验证就是走个确认流程。四、回头看10 天、9 个版本这个项目验证了什么M0骨架 数据到 M8交付10 天、9 个版本标签每个里程碑都有验收产出版本里程碑一句话v0.2.0M0 骨架 四部门模拟数据数据层物理隔离每部门独立目录v0.3.0M1 文档加载器txt → 统一文档对象部门标签解析v0.4.0M2 切分 向量化 索引自研切分器Chroma 按部门分库v0.5.0M3 基础 RAG检索 → 生成 → 引用标注跨部门问答打通v0.6.0M4 Agentic 路由问题自动分诊到部门零成本问候v0.7.0M5 自适应检索 答案反思分低自动扩展检索答完自查作业v0.8.0M6 部门过滤 综合研判/dept 精准圈定/all 四域研判报告v0.9.0M7 Web 界面点两下出报告场景化入口v1.0.0M8 文档 交付15 分钟上手从标签验证交付物回头看支撑它走完的是最初定下的三条原则数据隔离——四部门分目录分库互不污染这是后面一切「精准检索」「领域纯净」的地基接口预留——向量模型、向量库、大模型、场景配置全部留了替换口子。M7 加场景只改一个字典二期换国产模型只改一个参数步进验收——每晚一个可演示产出验收不过不进入下一步。10 天没有一天累积技术债。还有一条贯穿始终的隐性原则系统要诚实。资料不足就明说「无法查询到」不编造答完要反思自查每条结论标来源。「模型会一本正经胡说八道」是这个领域最大的风险而它被工程手段压到了最低。五、写在系列最后这个系列从楔子「预告片」开始到今天的收官篇一共九篇跟着项目从一行代码都没有走到 v1.0.0 正式交付。写这个系列的初衷是把「从零搭建」的过程完整留下来包括那些坑。回头看最有价值的可能不是架构图也不是验收表而是每一篇里那些「踩过的坑」——缺一个依赖能卡你一下午import gradio的先后顺序能让模型加载直接连到被墙的地址一张老显卡能让整条推理链路崩溃。这些坑单独看都很小但它们才是真实工程和 Demo 的区别。项目本身已经交付但路还没走完——二期还有一堆预留接口等着兑现实时气象 API、数据库接入、规则校验器、国产化模型替换。那是另一个故事了。感兴趣的小伙伴可以持续关注博主会持续修复bug、更新配置。感谢你看到这里陪伴喵喵走到这里。开源链接在这里https://gitee.com/Chester_Xue/city-agentic-rag欢迎starissue上一篇M7 Gradio Web 界面点两下就出研判报告系列目录城市管理 Agentic RAG —— 从零搭建城市管理问答系统想了解更专业的内容本文是项目实战记录。如果你对 RAG 的原理、Prompt 工程技巧、大模型 API 接入的完整方案感兴趣欢迎访问我的 CSDN 专栏喵本喵叁肆的 Agentic RAG 实战专栏阅读完整的技术博客系列含可运行代码、架构图与验收标准。