从API调用到Agent开发：大模型应用开发四阶段学习路径与实战经验

1. 从调用API到搭建Agent我的大模型应用开发入门路径2023年初我跟很多人一样觉得大模型应用开发这件事离自己挺远。当时能做的就是调一调在线接口写个问答小脚本感觉已经摸到天花板了。直到我真正把一个RAG知识库项目从零搭起来才发现调用API只是冰山露出水面的那一角水面下藏着检索策略、上下文管理、工具编排、状态机设计这一整套工程体系。这篇内容就是把我这两年从零散摸索到形成完整学习路径的过程拆开讲清楚适合刚入门想系统学习大模型应用开发的朋友也适合已经会调API但不知道下一步往哪走的开发者。先说结论大模型应用开发不是学一个框架就能搞定的事它更像是一条从会用模型到会编排模型再到会评估和优化模型的渐进路线。我把它拆成四个阶段——基础调用与提示工程、RAG检索增强、Agent工具编排、工程化与评估。每个阶段都有明确的能力目标和对应的技术栈下面逐个展开。我一开始最大的误区是以为LangChain就是大模型应用开发的全部。后来才明白LangChain只是编排层的一个工具库它解决的是怎么把模型、提示、工具、记忆串起来的问题但检索质量、状态管理、评估体系这些更底层的东西它给不了你答案。想清楚这一点之后我的学习路径才真正清晰起来。2. 第一阶段把模型调用和提示工程练到肌肉记忆2.1 为什么先啃提示工程而不是直接上框架很多人一上来就装LangChain跑通一个Chain就觉得自己会了。我踩过的坑是框架帮你封装了提示模板但你根本不知道底层拼出来的prompt长什么样出了问题完全无从下手。所以我的建议是先用最原始的方式调模型把提示工程的基本功打扎实。具体怎么做找一个支持OpenAI兼容接口的模型服务用requests或者官方SDK直接发请求。重点练三件事系统提示system prompt的写法、少样本示例few-shot的组织方式、输出格式的约束比如强制返回JSON。这三件事练熟了后面用任何框架你都能一眼看穿它到底在干什么。我当时的练习方法是拿同一个问题用五种不同的提示写法去问对比输出质量的差异。比如总结这段文字这个任务可以写成请总结、请用三句话总结、请以要点形式总结、请先提取关键信息再总结、请扮演编辑为这段文字写摘要。实测下来提示越具体、角色越明确、输出格式约束越清晰结果越稳定。这个结论听起来简单但只有自己反复对比过才会形成直觉。2.2 本地部署模型这件事什么时候该做热词里ai大模型本地部署配置ollama本地部署大模型哪个模型最佳出现频率很高说明很多人关心本地跑模型。我的经验是学习阶段本地部署很有必要但不要一上来就追求大参数模型。本地部署的核心价值有两个一是省钱二是数据不出本地。对于学习来说主要是第一个。用Ollama拉一个7B到14B量级的模型在消费级显卡上就能跑起来。我自己的机器是RX 6750 GRE12G显存跑7B的量化模型Q4量化大概占用5到6G显存速度可以接受。如果你要跑14B建议Q4量化起步显存最好16G以上。提示本地部署模型时优先选量化版本GGUF格式的Q4_K_M或Q5_K_M在质量和资源占用之间平衡得比较好。不要一上来就下FP16全精度版本显存直接爆掉。这里有个容易忽略的点本地模型和在线模型的能力差距在简单任务上不明显但在复杂推理和长上下文任务上差距很大。所以我的做法是——学习和调试阶段用本地小模型快速迭代验证逻辑跑通后再切到能力更强的在线模型做最终效果验证。这样既省了调试成本又保证了最终质量。2.3 提示工程里最容易被低估的输出解析提示工程不只是写好提示词还包括怎么把模型的输出变成程序能用的结构化数据。这一步在框架里叫Output Parser但你应该先手写一遍。我最早做的一个小工具是从一段招聘描述里提取岗位名称、薪资范围、技能要求。如果直接让模型返回文本后续处理非常痛苦。后来改成让模型返回JSON再用json.loads解析整个流程就顺了。但这里有个坑模型有时候会在JSON外面包一层json的代码块标记直接解析会报错。解决办法是在提示里明确说只返回JSON不要任何额外文字同时在代码里做一层容错——先尝试直接解析失败就用正则把JSON部分抠出来再解析。这个容错逻辑看起来不起眼但它是从玩具demo到能用工具的分水岭。我建议每个学大模型应用开发的人都手写一遍这个解析容错的流程理解为什么框架里要有Output Parser这个东西。3. 第二阶段RAG是绕不过去的坎但别把它想简单了3.1 RAG的本质不是向量检索而是信息组织很多人对RAG的理解停留在把文档切块、向量化、存进向量库、检索Top-K、拼进提示。这个流程没错但它只是骨架。真正决定RAG效果的是信息怎么组织。我做过一个企业知识库项目最初就是简单的固定长度切块比如每500字一块结果检索出来的内容经常是半截话上下文不完整。后来改成按语义边界切块——按段落、按标题层级、按问答对来切检索质量立刻上了一个台阶。再后来引入元数据过滤比如按文档类型、时间范围筛选又提升了一截。这里的关键认知是RAG的检索质量70%取决于文档预处理和切块策略30%才取决于向量模型和检索算法。很多人花大量时间调向量模型却忽略了切块这个最基础的环节。3.2 向量库选型pgvector为什么值得优先考虑热词里基于 fastapilangchainlanggraphragpgvector 的 ai agentic rag这个组合出现得很频繁说明pgvector在实际项目中很受欢迎。我自己的项目也从专用向量库切到了pgvector原因很实际对比维度专用向量库如Milvuspgvector部署复杂度需要独立部署和维护复用现有PostgreSQL数据一致性向量和业务数据分离向量和业务数据在同一事务学习成本需要学新API用SQL就能操作适用规模千万级以上向量百万级向量足够对于大多数中小规模项目pgvector完全够用而且省去了维护两套存储系统的麻烦。我现在的做法是业务数据、向量数据、对话历史全放PostgreSQL用pgvector做向量检索用普通表做元数据过滤一个数据库搞定所有事。注意pgvector的索引类型选HNSW还是IVFFlat取决于你的数据量和查询模式。数据量小于10万条时暴力检索不做索引反而更快更准10万到100万用HNSW超过100万再考虑专用向量库。3.3 检索策略从单路召回到混合检索最简单的RAG是单路向量检索。但实测下来纯向量检索有个明显问题对关键词精确匹配不敏感。比如用户问RX6750GRE训练大模型向量检索可能返回一堆泛泛的显卡训练模型的内容但真正包含RX6750GRE这个精确型号的文档反而排不到前面。解决办法是混合检索向量检索 关键词检索BM25或全文索引然后做结果融合。PostgreSQL自带的全文检索就能做关键词那一路配合pgvector做向量那一路两路结果用RRFReciprocal Rank Fusion算法融合。我实测下来混合检索在专业领域问答上的召回率比单路向量检索高20%以上。再进阶一点是重排序Rerank先召回Top-50再用一个交叉编码器模型对这50条做精排取Top-5。这一步会慢一些但对最终答案质量的提升很明显。我的建议是召回阶段追求高召回率宁可多召回重排阶段追求高准确率。4. 第三阶段Agent和LangGraph从链到图的思维跃迁4.1 LangChain和LangGraph到底有什么区别这是热词里问得最多的问题之一。我的理解是LangChain解决的是线性流程的编排LangGraph解决的是带状态、带分支、带循环的流程编排。打个比方LangChain像一条流水线原料从一头进成品从另一头出中间可以加几个工位Chain但整体是单向的。LangGraph像一张流程图可以有条件分支if-else、可以有循环重试直到满足条件、可以有并行同时做几件事再汇总、可以有中断和恢复人工审核后继续。为什么需要LangGraph因为真实的Agent场景几乎都不是线性的。比如一个客服Agent先判断用户意图如果是查询订单就走查询流程如果是退款就走退款流程退款流程里可能还需要人工审核审核不通过要回到用户确认环节。这种带状态、带分支、带中断的流程用LangChain硬写会非常别扭用LangGraph就很自然。4.2 用LangGraph搭一个带人工审核的Agent我拿一个实际项目举例一个内部文档问答Agent流程是接收问题→检索文档→生成答案→判断置信度→高置信度直接返回低置信度转人工审核→人工修改后返回。用LangGraph实现核心是定义好状态State和节点Node。状态里至少要有用户问题、检索到的文档、生成的答案、置信度分数、是否需要人工审核、人工修改后的答案。节点包括检索节点、生成节点、置信度判断节点、人工审核节点、返回节点。边Edge包括普通边和条件边根据置信度决定走哪条路。这里有个实操心得LangGraph的checkpointer机制非常有用。它可以把每一步的状态持久化到数据库这样即使服务重启流程也能从中断处恢复。对于需要人工审核的场景这个机制是刚需——人工审核可能要等几小时甚至几天不可能让流程一直挂在内存里。# LangGraph状态定义示例简化版 from typing import TypedDict, List class AgentState(TypedDict): question: str documents: List[str] answer: str confidence: float needs_review: bool final_answer: str提示LangGraph的官方文档写得比较抽象建议先跑通官方Quick Start里的那个条件分支例子理解State、Node、Edge、Conditional Edge这四个概念再去看复杂例子。我当初就是卡在概念理解上跑通例子之后豁然开朗。4.3 Agent开发中最容易踩的坑工具调用的边界Agent的核心能力是调用工具。但工具调用有个很容易被忽略的问题模型不知道工具的边界。比如你给Agent一个查询数据库的工具模型可能会传入一个不存在的表名或者传入一个格式不对的参数然后工具报错整个流程就断了。我的处理方式是三层防护第一层在工具描述里写清楚参数格式和取值范围让模型尽量传对第二层在工具函数内部做参数校验不合法就返回一个友好的错误信息而不是抛异常第三层在Agent层面做重试如果工具调用失败把错误信息喂回给模型让它重新生成参数。这三层防护做下来Agent的鲁棒性会好很多。我实测过一个查询天气的Agent没做防护时成功率大概70%做了三层防护后稳定在95%以上。5. 第四阶段工程化和评估决定项目能不能上生产5.1 为什么你的RAG项目Demo很惊艳上线就拉胯这是很多人的真实经历。Demo阶段用几个精心挑选的问题测试效果很好。一上线用户问什么的都有效果立刻崩了。根本原因是没有建立评估体系。评估体系包括两部分一是评估数据集二是评估指标。评估数据集要覆盖真实用户的各种问法——直接问、间接问、带错别字问、多轮追问。评估指标包括检索命中率相关文档有没有被召回、答案准确率答案对不对、答案忠实度答案有没有编造、响应延迟。我自己的做法是从真实用户日志里采样200到500个问题人工标注标准答案形成一个固定的评估集。每次修改检索策略或提示词都跑一遍评估集看指标是涨了还是跌了。没有这个评估集所有的优化都是盲猜。5.2 用FastAPI把RAG服务封装成API热词里基于 fastapilangchainlanggraphragpgvector这个组合FastAPI是标配。原因很简单FastAPI原生支持异步而大模型调用和向量检索都是IO密集型操作异步能大幅提升并发能力。我的服务结构大概是这样的一个/chat接口接收用户问题内部走完整的RAGAgent流程返回答案。一个/ingest接口用于文档入库接收文档、切块、向量化、存库。一个/feedback接口接收用户反馈用于后续优化。这里有个性能优化的点向量化操作调用embedding模型是耗时的文档入库时不要一条一条调要批量调。我实测批量大小设为32到64时吞吐量最高。另外embedding结果要缓存同样的文本不要重复向量化。5.3 评估Agent效果别只看最终答案Agent的评估比RAG更复杂因为Agent是多步的。只看最终答案对不对会掩盖中间步骤的问题。比如一个Agent最终答对了但中间调用了错误的工具、走了弯路这种侥幸正确在生产环境是不可靠的。我的评估方法是分步评估每一步的工具调用是否正确、参数是否合理、中间结果是否有效最后再看最终答案。LangGraph的trace功能可以记录每一步的状态配合LangSmith之类的工具可以做可视化分析。如果没有这些工具至少要在日志里把每一步的输入输出打出来方便事后排查。注意Agent评估不要追求100%自动化。有些判断比如这个工具调用是否合理目前还是人工判断更准。我的做法是自动化评估覆盖80%的常见场景剩下20%的边界场景人工抽查。6. 学习资源怎么选少即是多热词里动手学大模型上海交大langchain入门langgraph教程rag实战这些学习资源相关的词很多。我的建议是不要贪多每个阶段选一个主线资源就够了。入门阶段找一份能跑通的LangChain教程把Chain、Prompt、Output Parser、Memory这几个概念过一遍。RAG阶段找一份完整的RAG实战项目从文档加载到检索到生成全流程走一遍。Agent阶段直接看LangGraph官方文档的教程部分配合一个实际小项目练手。我自己的学习节奏是看文档占30%动手写代码占70%。光看不动手看完就忘。只有自己踩过坑、调过参数、对比过效果知识才真正变成自己的。另外说一个反直觉的体会不要过早追求最佳实践。网上有很多RAG最佳实践Agent最佳实践的文章但你的场景和别人的场景不一样别人的最佳实践到你这里可能完全不适用。先跑通一个能用的版本再根据实际效果去优化比一开始就照搬最佳实践更有效。7. 我踩过的三个典型坑和对应的解法第一个坑过早引入框架。我一开始就用LangChain的RetrievalQA结果检索效果不好时我完全不知道是切块的问题、向量模型的问题还是检索策略的问题。后来我把整个流程拆开每一步单独测试才定位到是切块策略的问题。解法是先用最原始的方式实现一遍理解每一步在干什么再用框架提效。第二个坑忽视上下文长度限制。我早期做长文档问答时把检索到的所有内容一股脑塞进提示结果超出模型上下文限制报错。后来改成按相关性排序只取Top-K并且对每段内容做长度限制。解法是永远要计算你的提示总长度留出足够的空间给模型生成答案。第三个坑没有做错误处理。模型调用会超时、向量库会连接失败、工具会报错这些在生产环境都是常态。我早期没做错误处理一个环节出错整个请求就挂了。后来加了重试、降级、超时控制服务稳定性大幅提升。解法是把每一个外部调用都当作可能失败来处理设计好失败后的行为。8. 关于学完能做什么的一点个人看法经常有人问学完大模型应用开发能做什么。我的观察是这个技能目前最直接的应用场景是企业内部知识库、智能客服、文档处理自动化、数据分析助手这几类。这些场景的共同特点是有明确的业务边界、有可获取的领域数据、对答案准确性有要求。但我想说的是不要为了学而学。最好的学习方式是找一个你真正想解决的问题用大模型应用开发的技术去解决它。哪怕这个问题很小——比如帮你自动整理会议纪要、自动分类邮件、自动生成周报——只要是你自己的真实需求你就会有动力去优化它去踩坑去把它做到能用。这个过程本身就是最好的学习。我自己就是从想给自己做一个能问答的技术文档助手这个需求出发一路学到了RAG、Agent、LangGraph、评估体系。回头看如果当初只是漫无目的地学框架大概率早就放弃了。有一个真实的目标牵引着学习路径会自然清晰起来。