别把十个 AI 仓库全装一遍:先跑通这条本地 Agent 链
我以前看到开源项目清单,第一反应是逐个点星,第二反应是挨个装。到了半夜三点,终端里多了六个虚拟环境,硬盘少了几十个 GB,真正能用的东西还是零。
后来我才想明白:学 AI 工程,不该按仓库数量算进度。更有效的办法,是用几个成熟组件拼出一条完整链路,让一个项目经历模型调用、检索、状态管理、评测和部署。缺了哪一环,问题会自己冒出来,比看十小时教程诚实得多。
先定一个够小、又会暴露问题的项目
我建议从“本地文档值班助手”开始。给它一批项目文档和故障记录,输入一个报错,它要找出相关片段,给出排查顺序,并保留本轮处理状态。
这个题目不花哨,却会逼你碰到 AI 应用最常见的几件事:文档怎么切、向量怎么存、模型答错时怎么追、工具失败后怎么恢复。做一个普通聊天壳,只能证明接口通了;做这个,才会开始理解系统为什么不稳。
第一版别接太多外部服务。模型先用 Ollama 在本机跑,文档量小的时候甚至可以先用内存索引。等流程成立,再换 Qdrant 这类向量数据库。太早上全家桶,报错时你连锅该甩给谁都不知道。
我现在只按五个环节装东西
- 1跑通推理用本地模型完成最小问答,记录模型名、上下文和耗时
- 2接入检索切分文档并召回相关片段,先看召回结果再让模型回答
- 3管理状态把任务步骤、工具结果和失败次数显式保存
- 4建立评测固定一组问题,检查召回、忠实度和答案相关性
- 5容器化交付固定依赖、配置和启动方式,在干净环境重跑
框架也按环节选。LlamaIndex 适合先把文档接进来;需要复杂的有状态流程时,再考虑 LangGraph。LangChain 能提供大量现成连接器,但我不会在第一天就把所有逻辑塞进去。能用模型 SDK 加几十行代码说清楚的事,先写直白一点,调试舒服得多。
多 Agent 更应该晚点上。CrewAI 这类框架能快速划分角色和任务,但单个 Agent 的输入、输出、失败重试还没理顺时,增加角色只会把一次报错变成一场群聊。
RAG 真正费时间的不是向量库
Qdrant 启动起来不难,难的是放进去什么。文档按固定字数硬切,常把标题和正文拆开;切得太大,又会让一段无关内容占满上下文。我的做法是保留标题层级,代码块和步骤列表尽量完整,再给每个片段留文档名、章节和更新时间。
检索阶段要单独打印候选片段和分数。别只看最终答案。模型答错可能是没召回,也可能是召回了却没用,还可能是原文互相冲突。这三种病的药完全不同。
向量检索也别当唯一入口。报错码、函数名、配置键这类精确字符串,关键词检索往往更靠谱。实际项目里,向量召回和关键词召回合并后再重排,通常比押宝一种方法省心。
评测要在“看起来能用”之前出现
我最晚学会的一件事,是在项目刚能回答时就建测试集。准备二三十个固定问题,里面要有能回答的、文档里没有的、容易召回错章节的。每次改分块、提示词或模型都重跑,别靠聊天窗口里的三次顺利回答给自己打气。
Ragas 可以拿来搭 RAG 评测,但指标不是裁判。忠实度和相关性分数能帮你找回退,最终仍要检查引用片段是否真的支持结论。尤其是中文文档、代码和表格混在一起时,自动评分偶尔也会一本正经地误判。
我还会记录四样东西:输入、检索片段、模型输出、总耗时。先别急着上漂亮的观测平台,JSON Lines 就够用。没有这些记录,Agent 出错后只能靠回忆复盘,和修一个没有日志的线上服务没区别。
最容易翻车的是最后那一公里
本机能跑,不等于别人能跑。真正交付时,常见问题反而很朴素:环境变量没写全、模型版本漂了、向量库没持久化、任务失败后无限重试、容器里访问不到宿主机模型。
所以项目最后要在一个干净环境里重建。用 Docker 固定应用和数据库依赖,把模型地址、索引目录、超时和重试次数放进配置;启动后先做健康检查,再跑固定评测集。密钥不要写进镜像,文档数据也别顺手打包上传。
至于 MCP,可以等主链稳定后再接。它适合把文件、数据库或内部工具变成统一接口,但接入前要先收紧权限。一个只需要读日志的助手,不该顺便拿到执行任意命令的能力。
九十天能得到什么
九十天当然不够把十个框架都吃透,也没必要。能交付一个可复现的小系统,知道答案错在检索、编排还是模型,已经比攒一排仓库图标有用。
我现在给自己的验收标准很简单:换台机器能启动,固定问题能重跑,失败有记录,组件能替换。做到这里,才算搭过一条 AI 工程链。否则只是又过了一个安装很热闹的晚上。