LLM落地实战：模型接入、RAG与Agent调用的避坑指南

把LLM接进产品和项目这件事最近一年的讨论热度一直没降但真正落到业务里且能稳定跑起来的我见过的还是少数。不是模型能力不够而是大部分人卡在了一些非常具体的工程问题上模型选哪个、接口怎么统一、知识库怎么切、工具调用为什么老是报错、成本为什么跑着跑着就失控了。你搜“LLM在产品和项目中如何落地”搜出来的常常是各种框架介绍但我更愿意换个角度直接盘一下落地过程中那些绕不过去的坎和可以照抄的做法。这篇文章不打算从LLM原理讲起但我默认你至少知道LLM能干什么。如果你连“什么是LLM”“LLM工作原理”还在补课我建议你先去把Karpathy的LLM Wiki翻一遍那是我见过信息密度最高的入门材料看完再回来实操会省很多时间。这篇文章也没有特别高深的技术主要适合两类人一是准备在自己产品里做LLM功能的产品经理和开发二是想用AnythingLLM、Obsidian这类工具给自己或团队搭知识库的人。我会尽量把实际操作路径、选型逻辑和排错经验写清楚你当成一份带避坑说明的落地手册看就行。1. 动手前先想清楚LLM落地不是“接个API”那么简单大多数项目翻车不是技术问题是需求问题。很多团队拿到LLM之后第一件事就问能不能让它当客服、写文案、做搜索这些当然都能做但每个方向对应的技术路线完全不同。比如做客服你需要知识库和意图识别做文案需要提示词工程和风格约束做搜索需要RAG加重排。方向一错后面全白搭。我见过最典型的例子是有人把LLM当成“万能数据库”希望模型记住所有业务数据然后直接回答用户。结果回答出来的东西看着挺顺细看全是编的。这不是模型不行是把“知识召回”和“文本生成”这两个环节混在一起了。任何打算长期跑下去的LLM功能第一步都不是写代码而是先定义边界模型负责什么、系统负责什么、用户输入能到达什么范围。1.1 这些搜索词背后暴露了四个共同缺口我整理“LLM在产品和项目中如何落地”时顺手把相关搜索词过了一遍很有意思。搜索词表面上看很杂但背后几乎都指向了四个共同缺口你搜的关键词暴露出来的缺口对应落地环节什么是LLM、LLM工作原理、Karpathy LLM Wiki对模型能力边界不清楚需求界定LLM环境搭建、LLM怎么搭建、LLM Studio不知道选什么模型服务、怎么跑通模型接入LLM框架、LangChain tool selector、Dify怎么让模型不输出思考过程工程组织方式没想好框架选型RAG增强LLM、AnythingLLM知识库、LLM Wiki Obsidian使用教程业务私有数据接不进来知识库与检索Codex CLI接入LLM模型只是聊天不能真正干活Agent与工具调用LocalAI、Offline AI Chat有本地化、离线或私有化部署的诉求接入与运维这也是我把整篇文章的架构拆成四件事的根本原因模型接入、框架选型、知识库RAG、Agent与工具调用。你把这四个环节逐个跑通LLM才算真正进入你的产品体系而不是一个放到哪儿都能用的“聊天框”。1.2 把“落地”拆成四件事模型、知识、Agent、生产第一件事是模型接入。你需要确定用哪个模型通过什么接口调用按什么方式计费怎么切换供应商。这一步的目标是让产品代码和具体模型解耦某个模型不好用了换一家不伤筋动骨。第二件事是框架选型。到底是裸调API还是用LangChain或者直接上Dify这样的低代码平台。不同团队情况不一样选错了会反过来束缚你。第三件事是知识库RAG。绝大部分To B或To C产品都需要让模型回答私有数据比如企业制度、商品信息、历史工单。RAG是目前性价比最高的方案但里面全是细节。第四件事是Agent与工具调用。你希望模型不只是“说”还能“做”比如查数据库、发通知、调接口。这块涉及Function Calling、工具Schema、执行安全边界是工程复杂度最高的一环。你把这四件事想清楚之后再回头看那些“如何落地”的教程就很容易判断哪些是可靠的哪些是在堆概念。2. 从零搭建LLM环境先选模型服务再跑通第一个请求很多新手一上来就装LangChain结果装了一堆依赖最后连最基本的对话请求都没跑通。我的建议是落地第一步永远是最小可用链路从代码里发一个真实的模型请求拿到返回结果再谈其他。2.1 选模型服务云API还是本地部署这个选择会影响你后面所有架构。目前主流有两种路线云上模型API和本地部署推理服务。云API的好处是效果强、不用管显卡和推理引擎、按token计费、弹性好。缺点是数据要出内网每次请求都有网络链路延迟受服务商影响长期跑起来token成本需要盯紧。本地部署则完全反过来。常见工具有Ollama、LocalAI、LM Studio也可以用vLLM这类专门做高性能推理的服务。好处是数据不出内网对隐私合规要求高的场景尤其重要单次请求成本基本可控。缺点是效果受硬件约束如果只有普通显卡跑量化模型和云端旗舰模型差距会非常明显。对比项云API本地部署部署成本无硬件成本按token计费需要显卡或大内存服务器数据安全取决于服务协议数据出内网数据留在本地首轮延迟受网络和服务商排队影响受推理设备性能影响模型效果通常可以上最新最强的模型受显存限制可能要量化维护成本低服务商维护高推理引擎、显卡驱动都要管还要提一下总被搜到的LocalAI和安卓离线场景。如果确实需要在安卓端做离线聊天技术路线也一样是本地部署只是把推理引擎塞进移动端或局域网设备用量化后的小模型跑。LocalAI就是这类的后端实现能做本地REST推理服务。它的优点是让你在完全无网环境也能对话缺点是模型能力天花板明显适合固定场景的FAQ问答不适合复杂逻辑推理。2.2 用OpenAI兼容接口写一个最小调用不管选哪家现在的模型服务商普遍提供了OpenAI兼容接口。这意味着你的核心代码不需要绑定某一家。最典型的最小调用是Python SDK看起来像这样from openai import OpenAI client OpenAI( api_key你的密钥, base_url模型服务商提供的接口地址 ) resp client.chat.completions.create( modelqwen-plus, messages[ {role: system, content: 你是一个严谨的技术助手。}, {role: user, content: 用一句话解释什么是RAG} ], temperature0.3 ) print(resp.choices[0].message.content)为什么我推荐这种方式作为起步因为所有复杂功能包括后续的RAG、Function Calling、Agent本质上都是在这个请求结构上不断加参数。你先把这个跑通再去看框架源码会有一种“原来框架也就是把底层请求包装得更友好”的清晰感不至于被各种抽象概念淹没。本地部署工具也基本同构。比如Ollama启动后本地接口一般是http://localhost:11434/v1你把base_url指向它再把model改成你本地拉下来的模型名就能在本地环境里做同一套代码的调试逻辑完全一致。这也是“本地开发和云端生产共用同一套代码”能做起来的原因。2.3 接入阶段最容易踩的坑我先说几个高频问题都是团队刚接入时经常遇到的。第一模型名和接口标识不一致。你产品页面看到的是“通义千问Plus”接口里的model参数可能叫qwen-plus也可能叫带日期后缀的版本号。写代码前先看对应服务商的官方文档确认准确模型标识否则会收到一条莫名其妙的报错。第二max_tokens不一定叫max_tokens。OpenAI早期版本用max_tokens但部分推理模型要求用max_completion_tokens。如果你把参数传错接口不会帮你纠正而是直接拒绝请求或者忽略参数。接入阶段最好把服务商的参数说明打印出来对着看。第三限流和超时处理。云API常见的问题就是并发高了开始报429或者超时。不要指望一个请求参数解决全部问题你的代码层必须有重试和熔断逻辑至少要保证某次调用失败时不会把整个服务带崩。第四上下文长度。模型有context window限制你以为把一本手册全塞进prompt就行结果要么超长报错要么模型开始漏掉中间内容。所以一开始就要养成习惯设计需求时控制输入长度需求内容长了就要考虑检索后再生成。3. LLM框架怎么选裸调API、LangChain还是Dify模型接入跑通之后第二个问题是工程组织方式。搜索词里“LLM框架”热度一直很高说明大家确实想找一个“能直接套进去的东西”。但框架这东西最大的作用不是给你魔法而是把常用模式封装好减少重复造轮子。3.1 框架到底帮你解决了什么框架核心解决四件事模型抽象、提示词管理、输出解析、工具调用编排。简单说它让你不用每次手写一大堆JSON解析和循环调用的代码。但这也带来了一个问题抽象层越厚排查问题越难。同一个报错信息裸调接口时你一眼就看出是参数不对走进框架之后你得翻两三层的封装才能定位到原始请求长什么样。所以我一般不建议项目一开始就上框架。你可以先用裸调API把核心逻辑跑通发现重复代码太多时再决定要不要引入一段框架能力甚至自己封装一个简单的调用库。3.2 LangChain适合有工程能力的团队LangChain是目前生态最完整的LLM框架组件覆盖Prompt模板、ChatModel、OutputParser、Memory、Tool、Agent、RAG。它更像一个工具箱很多东西都有但不是每一样都适合所有团队。举个例子用LangChain组织一个最简单的问答链from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate prompt ChatPromptTemplate.from_messages([ (system, 你是{role}回答要简洁。), (user, {question}) ]) chain prompt | ChatOpenAI(modelgpt-4o-mini, temperature0.3) response chain.invoke({role: 客服助手, question: 如何申请退款}) print(response.content)这里你会发现LangChain引入了一个“管道”概念用|把提示词模板和模型串联起来。代码看起来简洁但它内部帮你封装了请求、解析、重试等细节。优点是可组合性强适合搭建复杂的Agent流程缺点是抽象层级多版本升级很容易破坏之前的写法你搜“LangChain tool selector”时可能发现API已经换了几轮。3.3 Dify适合产品快速验证Dify走的是另一条路低代码、可视化、强调快速验证。它有完整的界面可以让你把模型接入、知识库、工作流、Agent节点都通过拖拽方式配置出来很适合做内部知识库或产品原型。对没有专职AI工程师的团队来说Dify是真香。你不需要写太多代码就能把“上传文档 - 自动切分 - 向量化 - 检索问答”这条路跑通。而且它对多模型供应商做了统一接入界面里切换模型成本很低。只是它也有边界一旦你的业务需要对工具或流程做非常精细的控制低代码界面就开始显得笨重你大概率还是要回到代码层面解决。3.4 我的选型建议你的情况推荐方案理由个人验证、快速做Demo裸调API心智负担最小随时能看到原始请求和返回需要复杂Prompt编排和工具调用LangChain或自己封装轻量框架灵活性高可调试性强搭内部知识库、非技术团队也要用Dify可视化流程上手快正式对外产品且对稳定性要求高裸调API 内部薄封装可观测、可兼容、出问题能快速定位我的态度是框架是手段不是目标。如果团队里有很强的工程能力自己写一个几十行的调用封装往往比引入框架更可控。别为了“没用上LangChain”而焦虑产品跑得稳才是硬道理。4. 用RAG把私有数据接进LLM先从切分和检索优化开始RAG增强是落地场景里搜索热度最高的方向之一。原因是它解决了LLM最尴尬的两个问题知识过时和不知道私有数据。你不需要重新训练模型只要把文档切碎、向量化、存起来在用户提问时先检索相关片段再把片段和问题一起交给模型生成回答。4.1 为什么RAG落地密度最高我看过很多落地方案RAG是目前综合成本最低、见效最快的。它不像微调那样需要高质量标注数据也不像重新训练那样需要强大算力。你只需要一批业务文档就能让模型瞬间“知道”你们公司的流程、产品目录、售后规则。典型场景包括企业内网知识库、客服问答、产品说明书问答、政策文件问答。还有类似AnythingLLM这类开源知识库应用也属于RAG路线它把文档上传、向量化、问答界面都打包好了适合团队内部快速自建一个问答系统。但要注意RAG不是“把文档往库里一扔就完事”。检索质量直接决定回答质量而检索质量又被切分、向量化、召回策略一层一层影响。很多人做完RAG之后发现效果差大部分问题都出在数据预处理上。4.2 从切分到检索的完整链路一条标准的RAG链路是这样的加载文档 - 切分文本 - 向量化 - 存入向量库 - 对用户问题向量化 - 检索TopK片段 - 拼装Prompt - 模型生成回答。切分这一步最容易被低估。常见做法是用固定长度切设一个chunk_size和chunk_overlapfrom langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings from langchain_chroma import Chroma text open(手册.md, encodingutf-8).read() splitter RecursiveCharacterTextSplitter( chunk_size800, chunk_overlap150 ) chunks splitter.split_text(text) vectors Chroma.from_texts( chunks, embeddingOpenAIEmbeddings(modeltext-embedding-3-small) ) results vectors.similarity_search_with_score(报销流程是什么, k5) for doc, score in results: print(doc[:100], score)这里chunk_size决定每一段多长chunk_overlap让相邻切分区域有重叠避免一句话被硬生生从中间切断。800到1000个字符是常见起点太短会丢失上下文太长会让向量表达不精准。如果你的数据本身是Markdown、HTML之类有结构的格式强烈建议优先按结构切分而不是盲目按固定长度切。比如Obsidian笔记天然带标题和双链用MarkdownHeaderTextSplitter按标题层级切分比固定长度切少很多语义撕裂。4.3 检索质量差先排查这四个点很多团队第一次跑通RAG后发现模型回答总是不对就开始怀疑模型。其实问题大概率在检索侧。一是切得不合理。分段过短导致上下文碎片化模型拿到的片段都是半句话分段过长又导致向量混淆检索出来的片段内容很杂。调整chunk_size是最容易见效的优化。二是Embedding模型不匹配。中文问答场景如果用一个对中文支持差的Embedding模型检索效果会非常差。选Embedding模型的时候最好用一批你真实业务里的问题做召回评测而不是只看榜单分数。三是TopK拉得太大。很多人为了不遗漏信息把TopK设成10甚至20结果模型输入里塞了一堆无关片段反而干扰生成。一般场景先设5如果不够再往上调同时要配合相似度阈值分数低于阈值的片段干脆不召回。四是缺少重排。向量检索只解决“语义相似”不解决“问题意图匹配”。在正式产品里通常要加一个重排环节把向量检索召回的候选重新打分排序。这也是RAG做到后面最值得投入的部分。4.4 和Obsidian、AnythingLLM这类工具怎么结合Obsidian用户经常搜“LLM Wiki Obsidian使用教程”其实本质上就是想用LLM把自己的笔记库变成可问答的知识系统。这类需求可以用两种方式实现。第一种是用现成方案比如AnythingLLM它把本地文档导入后进行向量化你连后端模型都可以接云端API或本地模型。这种方式胜在省事适合团队资料库或个人笔记库。第二种是写代码接入你可以在自己的服务里调用Embedding和LLM接口把Obsidian的Markdown文件全部加载、切分、入库然后做一个问答界面。这种方式适合你想把问答作为功能嵌入到自己的产品里。我特别想强调不管用哪种方式文档清洗都很关键。Obsidian笔记里通常有标签、模板变量、空段落、双链语法甚至被注释掉的草稿这些脏数据直接进向量库会严重污染检索结果。我在实际项目中试过同样的笔记库清洗前后回答准确率能差出一大截。所以不要急着向量化先用脚本把重复标题清理掉、把模板替换成真实内容、把空块和无效代码块过滤掉再往下走。5. 让LLM真正能干活Function Calling与工具调用的落地技巧聊到Agent大家会很兴奋觉得LLM从此能主动干活了。但从产品角度看Agent不是一个神秘的黑盒它的核心机制就是让模型学会发起工具调用然后你的系统负责真正执行。工程上做得好Agent就靠谱做得糙它就变成一只会循环调用工具的吞金兽。5.1 Function Calling的工作原理Function Calling本质上是在LLM对话接口里多传一个tools参数里面描述工具能干什么、需要哪些参数。模型收到用户问题后并不直接执行工具而是输出一个结构化的调用请求由你的代码判断是否真实执行执行完再把结果返回给模型让模型继续生成最终回答。一个工具Schema通常长这样{ type: function, function: { name: get_weather, description: 查询指定城市当前天气情况, parameters: { type: object, properties: { city: { type: string, description: 城市名称如北京 } }, required: [city] } } }关键在于description要足够清楚。模型的工具选择能力很大程度依赖这段描述你如果只写“天气查询”它可能不知道什么时候该调用如果明确写“查询指定城市当前天气情况”配合用户问题里的城市实体调用准确率会明显提升。5.2 从Codex CLI接入看命令行场景“Codex CLI接入LLM”这个热搜词很有意思它代表了一类典型需求在命令行里用自然语言让模型干活。这类工具看上去很强实际拆开就是一次完整的Agent交互循环模型解析你的指令 - 决定调用Shell命令或读取文件 - 执行命令 - 把执行结果返回 - 模型决定下一步动作。这给产品落地的启发是想让LLM“做事”最好的方式不是给它一个万能开放权限而是先给它一组很窄的、数量可控的工具。比如你做电商客服Agent一开始只开放三个工具查订单、查物流、发起退款。每个工具的边界清楚了模型的选择成功率就高容错也容易做。等验证跑通再逐步加工具。还要注意Agent的安全边界。工具调用一定要有权限控制不能让模型随意执行任何系统命令。命令行场景尤其危险做过“Codex CLI”测试的朋友应该都有体会模型会非常积极地去执行命令但有时候它执行的操作并不是你想要的。所以在Agent落地时建议把可执行命令做成白名单敏感操作一定要人工确认。5.3 工具调用报错与排查工具调用最常见的报错就是这个“provider rejected the request schema or tool payload”。我第一次遇到也挺懵后来排查多了发现基本逃不出几个原因。第一模型本身不支持tools参数。不是所有模型都支持Function Calling你拿一个纯文本模型传tools服务商就会直接拒绝。排查办法很简单换一个明确支持工具调用的模型或者去掉tools再试一次看报错是否消失。第二Schema格式不符合服务商要求。有些服务商要求parameters必须包含type: object和properties有些要求required不能为空数组还有些对工具描述长度有限制。你按固定格式写了不代表所有服务商都认对照官方文档检查一遍最靠谱。第三Tool Payload过大。当工具里面塞了大量字段说明或者工具数量特别多请求体可能超出服务商限制。不要一次性传几十个工具给模型精简到最常用的5个以内不仅能减少报错也能提高模型选对工具的概率。第四工具执行结果返回值有问题。模型执行完工具后返回给它的文本必须是干净的文字别把整个JSON对象原样塞回去尤其不要带各种乱码和转义字符。我见过不少回答质量差的问题本质是工具返回给模型的文本太乱模型根本读不懂。第五Agent循环失控。模型在你允许的工具集里反复调用就是不结束token哗哗烧。解决方式很简单给Agent设定最大调用步数通常3到5步就够再多就要从Prompt或流程设计上找原因。5.4 怎么控制模型不输出“思考过程”“Dify LLM怎么让模型不输出思考过程”被很多人搜索这确实是产品化时绕不开的问题。现在的推理模型比如带深度思考模式的模型输出里常常会多出一个思考过程字段。问题在于这个思考过程如果直接展示给终端用户体验会很差而且有些思考内容还包含中间分析步骤不适合外发。需要分几层来看。如果走API接入通常模型接口会返回两个字段一个是最终回答一个是思考过程字段名可能是reasoning_content或reasoning。你只需要把最终回答展示给用户把思考过程存到日志或直接丢弃。有些推理模型还提供了关闭思考模式的参数你可以把思考预算设为0或者选择非思考版本的模型。如果用的是Dify这样的可视化平台一般在模型配置或Agent节点里可以切换是否输出思考过程或者设置返回内容只取最终答案。还有一层朴素但有效的做法在Prompt里明确约束“只需要输出最终答案不要展示推导过程”。这对普通模型有效但对自带思考环节的推理模型不够彻底后者的控制点还是在接口参数和字段截取上。产品上线前我强烈建议你专门做一次字段检查确认前端拿到的只有最终回答不要把JSON里的全部字段一路反给用户。很多所谓“模型乱回答”的问题其实是前端展示错了字段把思考内容暴露了出去。6. 投产前的最后一关成本控制、效果评估与线上监控怎么做模型接入跑通、RAG稳了、Agent也能干活了这时候项目还没结束。真正的考验是上线之后比如成本曲线失控了怎么办回答质量怎么持续评估线上用户问了一个测试集里完全没出现过的问题怎么办。这一节我把投产前最容易忽视的三件事梳理一遍。6.1 成本控制的基本策略LLM按token计费而且输出token通常比输入token贵。很多项目的成本失控都藏在你看不见的地方比如日志里记录了全量上下文、每次请求都重复灌入长Prompt、Agent循环里反复发大请求。基本策略是先给输入瘦身。能用检索解决的问题就不要把整本文档塞进Prompt能用小模型解决的问题就不要每次都上旗舰模型。比如简单分类任务用轻量模型复杂总结和推理再切换到强模型。然后是缓存。对内容完全相同的请求做结果缓存比如高频FAQ、固定文案生成能省下不少重复费用。OpenAI等平台也提供了Prompt缓存命中后输入token价格会大幅下降你可以主动把固定系统提示词放在前面提高缓存命中率。还要盯住输出长度。很多场景其实不需要模型长篇大论你可以在接口里设置max_tokens上限再在Prompt里要求简洁。不要小看这两个小动作它能让单次调用成本下降一半以上。6.2 如何衡量落地效果没有评测集就谈不上优化。哪怕你只用LLM做了一个最简单的问答功能也建议建一个评测集数量不用太多100到200条真实业务问题就够每条都配上标准答案和可接受的关键指标。然后定期跑这些测评问题记录几个关键指标答案正确率、格式合规率、工具调用成功率、无效回答率。答案正确率就是模型这次有没有答对核心问题格式合规率是模型输出的格式能不能被下游正常解析尤其在JSON输出场景特别重要工具调用成功率是Agent场景下模型有没有正确选对工具和参数无效回答率是模型有没有乱编或者拒绝配合。我见过很多团队把所有精力都花在调模型上却连一份像样的评测集都没有结果改一个Prompt后模型变好了还是变坏了全靠感觉。这是最要不得的。评测集就是你的“回归测试”没有它就等于在开盲盒。6.3 监控与告警LLM服务上线之后监控和普通后端服务不太一样。除了常规的请求量、错误率、响应时间还要额外盯三个东西token消耗、单用户成本、答案质量异常。错误率要按错误类型细分。比如限流报错、超时报错、工具Schema报错处理方式都不相同。你可以把线上用户问过的问题持续沉淀下来整理成“十万个为什么”式的FAQ库它既是很好的测试集素材也是未来扩展知识库的原料。我还建议在监控面板里给“无效回答”单独建一个维度。如果模型突然开始大量返回“抱歉我无法回答这个问题”不一定是模型坏了很可能是你的RAG检索质量下降了比如文档更新后向量库没有同步或者某段文档被误删了。没有监控这类问题只能等用户投诉才发现。7. 写在最后一点关于LLM落地的个人体会回头再看“LLM在产品和项目中如何落地”这件事我的核心感受是真正难的不是模型而是把模型放到一个真实系统里之后那些环环相扣的工程细节。多看看像Karpathy LLM Wiki这类源头资料多读模型服务商的官方文档比什么“落地秘籍”都管用。我自己的习惯是永远先用最小模型跑通链路再逐步替换强模型永远是先把工具调用跑成功再做复杂的Agent循环优化。我帮别人查工具调用报错时见过最夸张的情况是有人把十万字业务手册硬塞进System Prompt然后抱怨模型回答又慢又错。那不是模型的问题是设计方式的问题。如果你想在自己的产品里引入LLM我建议从一个小而明确的功能开始比如“基于公司FAQ的自动问答”一周内上线把它放给真实用户记录反馈在此基础上再扩展。LLM落地的核心不是一步到位而是快速迭代中不断找到模型和能力边界之间的平衡点。先让一小部分人用起来比什么都重要。