说实话这两年AI这波浪潮起来之后最不缺的就是各种“一句话生成应用”的Demo但真正到了自己手上要搭一个能跑、能维护、能迭代的AI工程时很多人还是会被一堆问题卡住。我自己从零开始折腾AI工程已经有一段时间了从模型选型、数据清洗、Prompt调试到Agent工作流编排、模型部署和测试趟过不少坑。这篇就把我从“ai-engineering-from-scratch”这个项目里沉淀下来的思路和实操经验整理出来希望能帮那些打算独立搭一套AI工程的读者少走弯路。里面不会给你一个炫酷的PPT而是从一个项目的初始化讲起讲清楚每一步该怎么做、为什么这么做。1. 项目概述我为什么要从零开始做AI工程1.1 这个项目到底在解决什么从Demo到可维护系统的鸿沟很多人可能觉得AI工程不就是调用一个大模型API传个prompt拿回结果吗如果抱着这个想法去做项目大概率会在第一个月就栽跟头。我之前接过一个内部工具最初在Jupyter Notebook里调模型效果看起来很不错给几个样例都能正确回答。可一旦拿到真实环境问题一波接一波用户输入千奇百怪有错别字、中英混杂、甚至带着HTML标签模型返回的内容格式不稳定有时给你一长段话有时只输出半截JSON接口偶尔超时而且成本像坐过山车一样飙上去。那一刻我才意识到AI工程的难点根本不在“叫模型干活”而在于把模型放在一个真正可控的工程系统里。所以“ai-engineering-from-scratch”这个项目从一开始就定了一个目标搭建一套可复用的AI工程脚手架让一个没有历史包袱的新项目能够快速跑通同时这个脚手架本身要具备可观测、可配置、可测试的属性。这套体系覆盖了环境准备、数据治理、Prompt管理、Agent流程编排、模型部署、线上测试和问题回溯。它不依赖某个特定的大模型厂商尽量做到模型层可替换让业务侧不会被单一供应商锁死。这背后的核心问题其实就是“如何让模型输出变得稳定、可信、可维护”。模型本身是概率系统同样的输入温度调高一点结果就飘了。工程化的意义不是去消灭这种随机性而是通过设计合理的上下文、工具调用、异常处理和评估机制把随机性限制在一个可接受的范围里。我后面会详细展开每层具体是怎么做的。1.2 整体设计思路先把闭环跑通再谈优化做这个项目我坚持的第一原则是先跑通一个最小可用闭环再谈优化。最忌讳的是第一天就想把微调、向量数据库、分布式部署、A/B测试全部堆上去。你没有跑通主链路之前根本不知道瓶颈在哪里。比如你辛辛苦苦搭了一个RAG系统结果发现用户的问题都很短知识库里根本没有匹配内容那这个系统就是白做的。所以我的做法是先用最朴素的方式把业务功能实现出来用户输入问题系统拼一个prompt调用模型返回答案。整个链路用几个文件就能跑通但必须是端到端能工作的。跑通之后我再开始逐步替换和增强先用模型输出不稳定这个现象反过来驱动我去设计结构化输出和校验逻辑然后发现有的问题需要查数据库、查日历于是引入了工具调用逐渐演变成一个Agent工作流再往后要考虑并发和成本于是有了部署方案和缓存策略。整个过程很像装修房子先砌墙、拉水电再贴瓷砖、放家具而不是先把家具买齐了发现水电没留好。这种思路还有一个好处每一步都可以单独验证和回滚。举个例子我一开始用LangChain做原型但后来发现它封装得太重遇到问题很难定位于是我把核心路径逐步改成了手写调用。如果当初一上来就依赖某个大而全的框架后面想拆都拆不动。所以设计上我会刻意保持模块之间低耦合模型调用、Prompt模板、工具函数、输出校验各是一块可以独立替换和测试。1.3 技术栈选型的底层逻辑技术栈选型这件事我推荐的原则是稳定、生态好、调试方便。编程语言我选了Python这个没什么争议AI生态里的SDK、框架、工具基本都是Python优先。Web框架我用FastAPI主要是它天然支持异步对流式输出友好同时自动生成OpenAPI文档做接口联调很省事。模型调用层我没有绑定某个SDK而是自己封装了一层Client比如一个chat()函数负责接收消息列表和参数返回文本或结构化内容。这样以后从OpenAI切到开源模型或者换到国内模型API只需要改这一个小函数业务代码不用动。工具链方面向量检索我用过Chroma和Qdrant。Chroma轻量适合本地跑验证Qdrant支持过滤和更复杂的检索逻辑适合线上。实际项目里我倾向于先用Chroma把逻辑调通再平滑迁移到Qdrant因为两者API风格比较接近。模型部署这一层如果要自建开源模型我建议看看vLLM它对吞吐的优化非常明显而且兼容OpenAI的接口格式能让上层代码无缝切换。整套系统我用Docker编排模型服务、API服务、向量库各跑一个容器本地开发和云端部署保持同样环境。为什么反复强调选型要“调试方便”因为AI系统的黑盒问题太多了。如果框架把prompt的组装、模型的调用、Agent的循环都封装在内部出了错你只能看一个抽象报错根本不知道是模型抽风还是代码逻辑错了。手写核心路径看起来多写了几行代码但每一步都能打日志、断点调试长期收益远大于省下的那点开发时间。2. 核心细节解析数据与Prompt是AI工程的命门2.1 数据准备80%的精力都在这里AI工程里最容易低估的就是数据准备。我见过很多项目代码写得飞快但一问到用来评估模型效果的数据集往往只有二三十条手工写的样例。这完全不够。模型输出的质量很大程度上取决于你给它多少高质量的示例以及你拿什么标准去衡量它有没有跑偏。我现在的做法是任何一个AI功能上线前必须先准备三份数据评估集、知识库片段、Few-shot示例集。评估集是拿来判断模型改动是好是坏的基础。我会从真实用户日志里收集100到200条问题按业务场景分类再给每一条标注标准答案或者答案要点。数据清洗这一步特别关键用户输入不能直接塞给模型。我写过一个清洗函数会做这几件事去掉多余的空白符和HTML标签把全角标点转成半角对繁体中文做简单转简体对常见的同义改写做归一化。这些看起来不起眼但直接影响检索匹配和模型理解。真实项目里因为一个全角括号没转导致JSON解析失败的情况我都遇过不止一次。知识库片段则是给RAG用的格式上我坚持用结构化的Markdown或JSON统一存储。每一条知识至少包含id、标题、正文、来源、更新时间。这里有一个很容易踩的坑千万不要把几万字的长文档直接切成长度不可控的段落否则检索出来的是半截话模型根本看不懂。我的切分策略是按标题层级先分块再把超过一定长度的块按句子边界切开每块控制在500到800字左右并且保留前后的上下文摘要。切分之后的片段需要人工抽检看有没有切断关键逻辑。Few-shot示例是给prompt做示范用的这组数据要刻意覆盖边界情况。比如用户问“今天有什么安排”你要准备一个场景数据库里没有日程时助手应该怎么回答也要准备一个有日程但用户权限不够的场景看模型能不能识别。示例的意义不是让模型背答案而是帮它理解你的行为边界。我会把示例格式统一为“用户输入”加“期望行为”写进system prompt或作为执行时的上下文。2.2 Prompt Engineering实操让模型稳定输出你想要的结果Prompt Engineering这个词这两年热度一直很高但我发现很多人对它的理解停留在“写一段漂亮的话”。实际上Prompt是你在和概率模型打交道时唯一能直接控制的“接口”它需要被当成代码来管理。我最基本的要求是每个prompt模板必须有版本号改动后要记录变更原因并且立刻跑一遍评估集确认效果没有回退。在模板设计上我习惯把system prompt拆成四个部分角色、任务、约束条件、输出格式。角色定义决定模型的语气和知识边界任务描述要让模型知道它具体要完成什么约束条件要明确“不能做什么”输出格式则尽量用结构化的方式约束模型方便后续解析。举个例子如果我做一个日程助手system prompt里会写你是一个企业日程管理助手。根据用户提供的日程信息回答关于会议安排、时间冲突、日程提醒等问题。你只能基于给定的日程数据进行回答不要编造不存在的会议。输出必须是一个JSON对象包含response和data两个字段response是给用户看的自然语言回复data是结构化的日程列表。如果没有相关日程data返回空数组。这样分段写的目的是为了让每一条约束都能被单独调整。比如发现模型开始编造会议了我只需要修改“不要编造不存在的会议”这一条不需要重写整个prompt。输出格式这里我强烈建议要求模型输出JSON并在代码里做二次校验和解析。不要相信模型一定给你合法JSON哪怕概率是95%上线后的流量也会让这5%变成每天上百次报错。解析失败时我会让程序自动尝试修复比如截取第一个{到最后一个}之间的内容或者调用一次修正请求让模型把非法输出重新整理成合法JSON。参数设置方面我的经验是普通业务场景temperature设成0.2到0.4不要太高。如果这个功能要求严格符合事实直接设0如果是头脑风暴类需求才调到0.8以上。max_tokens要显式设置不设置的话模型可能因为生成了很长的废话而拖慢响应。还有frequency_penalty和presence_penalty这两个参数我一般在做长文本生成时才会用用来减少重复内容其他场景默认0就好。所有参数我都通过配置文件暴露而不是硬编码在代码里这样线上调参不需要发版本。2.3 上下文管理与结构化输出上下文窗口再大也是有限的一个AI工程只要做对话场景迟早会遇到上下文爆炸的问题。我处理上下文的基本策略是分三层短期上下文、工作记忆、长期知识。短期上下文保存最近几轮对话全文通常限制在10轮以内工作记忆是对前面内容的摘要每一轮都会用模型生成一段压缩后的状态长期知识则是通过RAG从向量库检索出来的相关片段只有在需要时才注入。这三层各有用处能有效控制token数量。对于结构化输出除了在prompt里要求JSON我更推荐基于工具调用Function Calling的机制。现在的模型API基本都支持传入工具定义模型会生成一个结构化的工具调用参数而不是自由输出文本。这样我就能直接得到一个Python字典几乎不需要正则解析。比如我需要模型从用户输入中抽取“意图”和“实体”就定义一个extract_event工具参数里写清楚日期、标题、参与人。模型一旦决定调用这个工具返回的参数绝对是合法JSON因为这是模型自己的能力而不是靠prompt要求出来的。当然结构化输出也不是银弹。工具调用的参数有时也会缺字段所以我在代码里会做schema校验缺了字段就返回一个提示信息让模型补充而不是直接崩溃。这里我踩过一个坑一开始我把schema写得特别细要求模型必须填所有字段结果模型开始编造一些不存在的值反而导致准确率下降。后来我放宽了必填字段只保留业务真正需要的字段问题才缓解。所以设计schema时要遵循“最少必要字段”原则先保证稳定再考虑丰富。3. 实操过程从零实现一个可用的AI Agent工作流3.1 Agent架构设计工具、记忆与规划当业务逻辑开始复杂单纯“prompt-回答”就不够了你需要让模型能主动调用外部工具这就是Agent。我实现的第一个Agent是日程管理助手需要完成查日程、创建日程、改时间、提醒冲突等操作。Agent的本质可以理解为一个循环模型根据当前对话状态决定是直接回复用户还是调用某个工具调用完工具后把工具结果返回给模型模型再决定下一步动作。这个循环会一直执行直到模型认为任务完成。工具设计是Agent里最基础的部分。我维护一个工具列表每个工具有名字、描述、参数schema。描述极其重要因为模型是靠描述来判断什么情况调用哪个工具的。比如“search_events”的描述我会写成“根据日期或关键词查询日程返回日程列表”如果描述里没写清楚日期格式模型就可能在参数里传乱七八糟的值。每个工具在代码里就是普通函数但函数内部要有完整的异常捕获不能让底层错误直接冒泡到Agent循环里。记忆和规划是Agent能不能真正实用的关键。我的短期记忆维护一个消息列表每次模型调用后追加新消息但列表有长度上限超过后就把最早的消息搬到“摘要系统”里。规划部分我用的是一种简单的ReAct模式每次循环让模型先输出”reasoning”思考过程再选择是否调用工具。把这个思考过程记录下来既方便调试也能在模型犯错误时回溯。不要一上来就做复杂的多Agent协作单Agent加上几个稳定工具已经能解决大部分问题。3.2 核心代码实现与关键参数说明我把核心代码简化出一个可运行的示例展示最小的Agent循环。这个版本没有依赖Agent框架只用了模型API的Function Calling能力你可以直接替换成任意兼容的接口。import json from openai import OpenAI client OpenAI() def search_events(date: str None, keyword: str None): # 实际项目里这里会查数据库或调用日历服务 return [ {event_id: 1, title: 项目评审会, date: 2025-05-06, attendees: [张三, 李四]} ] TOOLS [ { type: function, function: { name: search_events, description: 根据日期或关键词查询日程返回日程列表, parameters: { type: object, properties: { date: {type: string, description: 日期格式YYYY-MM-DD}, keyword: {type: string} } } } } ] def run_agent(user_input: str): messages [ {role: system, content: 你是日程助手尽力使用工具解答用户问题不要编造日程。}, {role: user, content: user_input} ] max_iterations 5 for i in range(max_iterations): resp client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolsTOOLS, tool_choiceauto, temperature0.2, max_tokens1024 ) msg resp.choices[0].message messages.append(msg.model_dump()) if msg.tool_calls: for tc in msg.tool_calls: result eval(tc.function.name)(**json.loads(tc.function.arguments)) messages.append({ role: tool, tool_call_id: tc.id, content: json.dumps(result, ensure_asciiFalse) }) else: return msg.content return 处理超时请稍后再试这段代码里我最想强调的参数是max_iterations。它防止Agent陷入死循环是一个保险丝。我把这个值设为5原因很简单一个日程查询任务最多经历“查表-确认-回复”三步就够了如果5步还搞不定多半是模型思路跑偏了继续循环只会浪费token和用户时间。temperature0.2也是有意为之Agent环境下需要的是稳定决策不是发散创意。max_tokens1024则是避免模型单次输出过长毕竟工具调用场景下它一次只需要生成一小段结构化内容。实际项目中工具函数千万不要用eval来调用。这里为了示例简短才这么写正规做法是用一个字典做名称到函数的映射比如注册器模式既安全又方便日志记录。另一个容易被忽略的是tool_call_id这个字段必须原样返回给API否则模型会认为工具结果对不上号导致对话状态错乱。我第一次写的时候漏过这个字段结果模型每次都说“没有收到工具返回结果”排查了很久。3.3 异常处理与日志追踪工程化的第一步代码能跑只是起点真正工程化要做的是让每一次失败都可追踪。我在Agent循环外围加了一层统一异常处理调用API超时最多重试两次如果还是失败返回一个降级话术并记录告警。工具内部抛出的异常被我统一包装成{error: tool timeout, detail: ...}这样模型看到的是一个正常的工具返回可以自行决定是重试还是告诉用户处理失败而不是让整个Agent崩溃。日志是我觉得最值得投入精力的地方。每次Agent运行我会生成一个run_idUUID贯穿整个链路。日志里记录四样东西当前使用的prompt版本号、模型名称与参数快照、每次模型返回的原始内容、每次工具调用的输入输出。为什么一定要记prompt版本号因为模型输出如果变差了可能是prompt被改动导致的也可能是模型厂商悄悄升级了底层模型。没有版本号这些问题根本没法定位。我用结构化日志JSON Lines存到一个文件里上线后用ELK或轻量日志系统做检索排查问题时按run_id拉出完整链路就够了。4. 从本地到线上模型部署与测试经验4.1 部署方案选择API、自建、混合策略模型部署是个绕不开的话题。我的选择依据是业务场景和成本约束。如果团队没有专门的GPU运维能力大多数场景直接用大模型API是最稳妥的。OpenAI、Claude、国内几家大模型API都提供了比较完整的接口开发效率最高。缺点也很明显数据要出网对某些行业不友好成本可能随调用量上涨模型版本也由厂商控制。如果项目对数据安全有硬性要求或者调用量大到API费用已经超过自建推理成本再考虑自建开源模型。自建模型我推荐vLLM它对连续批处理做得比较好能把GPU利用率拉高数倍。装好之后它能提供一个兼容OpenAI接口格式的服务所以上层代码几乎不用改只需要把Client的base_url指向本地服务。模型选择上7B到14B参数的开源模型在普通业务场景已经够用比如Qwen系列和Llama系列。硬件方面7B量化模型一张24G显存的卡能跑14B模型建议用两张卡或一块48G显存。GPU资源有限时可以考虑CPU部署但响应速度会明显变慢只能适合内部低频工具。实际项目里我更多用混合策略核心链路调用大模型API稳定且效果有保障高并发或批量离线任务走自建开源模型控制成本两套模型都封装在同一个chat()接口后面通过配置切换。这个接口的切换逻辑我放在了启动加载时而不是每次请求都判断以避免多一层分支复杂度。部署时Docker是必需品模型服务、API服务、向量库各自独立容器用docker-compose统一管理本地能跑通云服务器上也不会环境不一致。4.2 性能调优与成本计算很多人说AI应用贵其实贵不贵要看怎么算。我建过一张成本计算表核心公式是单次请求成本 输入token数 × 输入单价 输出token数 × 输出单价。假设某API定价为输入$0.005/1K token输出$0.015/1K token一个普通问答请求平均输入1.2K token输出0.3K token那单次成本大概是0.006 0.0045 0.0105美元折合人民币约7分钱。看起来不多但一天跑10000次就是700块一个月就是两万。所以成本优化必须从第一天就考虑。我最常用的三个降本手段是缓存、RAG预热、和模型分级。缓存可以缓存重复度高的query比如FAQ类问题命中缓存直接返回结果完全不用调模型。RAG预热是指对于知识库检索结果系统启动时先把热点知识片段准备好减少实时嵌入计算。模型分级是指简单任务用便宜的轻量模型复杂任务才升级到更强的模型。在代码里我还加了一个开关当某段时间调用量突增时自动把非核心流程降级到更便宜的模型保障主链路稳定。性能方面最需要注意的瓶颈往往不在模型推理而在网络或下游服务。一个模型API请求如果经常等上10秒用户体验基本就崩了。我会用流式输出SSE让文字一个字一个字地出来用户感知的延迟会小很多。同时给API设两个超时时间连接超时3秒读取超时30秒避免无谓的等待。对于长任务用异步任务替代同步请求把计算结果通过回调或轮询通知给前端。4.3 AI测试与回归策略我见到的AI项目里很多开发团队的测试还是只测“有没有报错”根本不测“回答质量有没有变差”。这不行。AI工程至少要有一层基于评测集的回归测试。我搭建的测试结构分四层单元测试、集成测试、评测测试、人工抽检。单元测试覆盖工具函数和解析逻辑比如JSON解析函数遇到非法输入能否正确返回错误。集成测试验证完整调用链从API入口到模型调用到工具执行再到响应封装确保没有拼写错误和数据结构错配。评测测试是AI项目最有特色的一层。我维护了一个评测集比如100条真实用户问题每条都标注了理想回答的关键要点。每次修改prompt或切换模型后我会跑一遍这100条数据用LLM-as-judge或者简单的人工对比来打分。这里我推荐先做一个自动打分器使用一个比业务模型更强的模型对比候选回答和标准答案按“准确性”“完整性”“意图对齐”三个维度打1到5分。自动打分能快速筛掉明显下滑的版本最后再人工确认少量边界case。这个流程看似有点重但能防止“改一个prompt修好了A问题结果B问题大面积恶化”的悲剧。5. 常见问题排查与避坑指南5.1 模型输出不稳定怎么排查遇到模型输出不稳定第一件事不是改prompt而是先复现。我把同样的输入、同样的参数、同样的上下文固定下来连续调用五次观察结果。如果五次结果差异很大多半是temperature设置太高或者模型上下文里缺少关键约束。这时候我会把temperature降到0并加强输出格式约束。如果降低温度后依然不稳定问题就出在上下文中的示例或指令本身有歧义。你让模型“总结一下”它可能理解为“提取要点”也可能理解为“用一句话概括”这时要在prompt里明确“总结”的定义和字数范围。排查不稳定问题时务必把每次请求的完整参数和响应都记录到日志里。我之前排查一个客服机器人时发现模型偶尔会在回答末尾多出一句“祝你生活愉快”有人认为是prompt问题但后来看日志发现是用户历史消息里出现过这句话模型模仿了用户风格。这种case靠肉眼猜是猜不出来的只有日志才能暴露因果。5.2 上下文爆炸与幻觉问题上下文一旦超过模型的实际处理能力最典型的表现就是对话变慢、逻辑开始混乱、甚至出现幻觉。我处理上下文爆炸的办法在2.3里已经提过这里补充一个实际案例。我有一个项目需要长期记忆用户偏好一开始把用户所有历史记录都塞进上下文结果token占用越来越多模型回答质量明显下降。后来我改为只保留最近5轮对话原文更早的偏好信息则存成结构化的用户画像对象每次请求时通过检索把最相关的几条偏好注入prompt。效果立竿见影上下文占用降了一半回答准确率反而提升了。幻觉问题的根源本质上是模型在自由生成时“编造”。我的对策是给模型划定回答边界如果知识库或工具返回结果里没有的答案必须明确说“我不知道”而不是猜测。同时把知识片段附上来源ID要求模型在回答时引用来源编号这样即使结果错误我至少能追踪到是哪条知识引起的。对于涉及计算或事实核对的场景更稳妥的做法是先让模型调用工具去查而不是直接让它凭记忆回答。5.3 部署后响应速度慢怎么办先定位瓶颈再优化这是排查响应慢问题的铁律。我的第一反应是看日志里的耗时分布模型调用耗时多少、工具执行耗时多少、网络传输耗时多少。如果90%的时间都花在模型调用上那就考虑换更快的模型参数量、使用量化的版本或者升级推理框架。如果时间花在下游数据库查询上说明工具实现需要加索引或缓存而不是跑到模型那边瞎调。另一个常见坑是同步调用模型导致API服务线程被占满。高峰期每个请求占一个工作线程每个线程要等模型返回好几秒整个服务很快就不可用了。解决方法是把模型调用改成异步模式并使用并发上限控制。此外vLLM这类框架支持Streaming在适当场景用流式响应对感知延迟帮助很大。最后别忘了对API入口做压测我常用的方法是并发50个请求持续3分钟看P95耗时和报错率如果在预期范围内再扩大流量上线。最后再分享一个小技巧所有线上日志一定要记录prompt版本号和模型版本号否则出了幻觉你根本不知道是prompt改坏了还是模型升级导致的。这个习惯帮我省了很多排查时间也让我在团队里被同事追问“最近为什么回答质量下降了”的时候能直接甩出一条日志链路而不是含糊其辞。AI工程就是个不断与不确定性博弈的过程把这些细节管住了系统才能慢慢变得可靠起来。
说实话这两年AI这波浪潮起来之后最不缺的就是各种“一句话生成应用”的Demo但真正到了自己手上要搭一个能跑、能维护、能迭代的AI工程时很多人还是会被一堆问题卡住。我自己从零开始折腾AI工程已经有一段时间了从模型选型、数据清洗、Prompt调试到Agent工作流编排、模型部署和测试趟过不少坑。这篇就把我从“ai-engineering-from-scratch”这个项目里沉淀下来的思路和实操经验整理出来希望能帮那些打算独立搭一套AI工程的读者少走弯路。里面不会给你一个炫酷的PPT而是从一个项目的初始化讲起讲清楚每一步该怎么做、为什么这么做。1. 项目概述我为什么要从零开始做AI工程1.1 这个项目到底在解决什么从Demo到可维护系统的鸿沟很多人可能觉得AI工程不就是调用一个大模型API传个prompt拿回结果吗如果抱着这个想法去做项目大概率会在第一个月就栽跟头。我之前接过一个内部工具最初在Jupyter Notebook里调模型效果看起来很不错给几个样例都能正确回答。可一旦拿到真实环境问题一波接一波用户输入千奇百怪有错别字、中英混杂、甚至带着HTML标签模型返回的内容格式不稳定有时给你一长段话有时只输出半截JSON接口偶尔超时而且成本像坐过山车一样飙上去。那一刻我才意识到AI工程的难点根本不在“叫模型干活”而在于把模型放在一个真正可控的工程系统里。所以“ai-engineering-from-scratch”这个项目从一开始就定了一个目标搭建一套可复用的AI工程脚手架让一个没有历史包袱的新项目能够快速跑通同时这个脚手架本身要具备可观测、可配置、可测试的属性。这套体系覆盖了环境准备、数据治理、Prompt管理、Agent流程编排、模型部署、线上测试和问题回溯。它不依赖某个特定的大模型厂商尽量做到模型层可替换让业务侧不会被单一供应商锁死。这背后的核心问题其实就是“如何让模型输出变得稳定、可信、可维护”。模型本身是概率系统同样的输入温度调高一点结果就飘了。工程化的意义不是去消灭这种随机性而是通过设计合理的上下文、工具调用、异常处理和评估机制把随机性限制在一个可接受的范围里。我后面会详细展开每层具体是怎么做的。1.2 整体设计思路先把闭环跑通再谈优化做这个项目我坚持的第一原则是先跑通一个最小可用闭环再谈优化。最忌讳的是第一天就想把微调、向量数据库、分布式部署、A/B测试全部堆上去。你没有跑通主链路之前根本不知道瓶颈在哪里。比如你辛辛苦苦搭了一个RAG系统结果发现用户的问题都很短知识库里根本没有匹配内容那这个系统就是白做的。所以我的做法是先用最朴素的方式把业务功能实现出来用户输入问题系统拼一个prompt调用模型返回答案。整个链路用几个文件就能跑通但必须是端到端能工作的。跑通之后我再开始逐步替换和增强先用模型输出不稳定这个现象反过来驱动我去设计结构化输出和校验逻辑然后发现有的问题需要查数据库、查日历于是引入了工具调用逐渐演变成一个Agent工作流再往后要考虑并发和成本于是有了部署方案和缓存策略。整个过程很像装修房子先砌墙、拉水电再贴瓷砖、放家具而不是先把家具买齐了发现水电没留好。这种思路还有一个好处每一步都可以单独验证和回滚。举个例子我一开始用LangChain做原型但后来发现它封装得太重遇到问题很难定位于是我把核心路径逐步改成了手写调用。如果当初一上来就依赖某个大而全的框架后面想拆都拆不动。所以设计上我会刻意保持模块之间低耦合模型调用、Prompt模板、工具函数、输出校验各是一块可以独立替换和测试。1.3 技术栈选型的底层逻辑技术栈选型这件事我推荐的原则是稳定、生态好、调试方便。编程语言我选了Python这个没什么争议AI生态里的SDK、框架、工具基本都是Python优先。Web框架我用FastAPI主要是它天然支持异步对流式输出友好同时自动生成OpenAPI文档做接口联调很省事。模型调用层我没有绑定某个SDK而是自己封装了一层Client比如一个chat()函数负责接收消息列表和参数返回文本或结构化内容。这样以后从OpenAI切到开源模型或者换到国内模型API只需要改这一个小函数业务代码不用动。工具链方面向量检索我用过Chroma和Qdrant。Chroma轻量适合本地跑验证Qdrant支持过滤和更复杂的检索逻辑适合线上。实际项目里我倾向于先用Chroma把逻辑调通再平滑迁移到Qdrant因为两者API风格比较接近。模型部署这一层如果要自建开源模型我建议看看vLLM它对吞吐的优化非常明显而且兼容OpenAI的接口格式能让上层代码无缝切换。整套系统我用Docker编排模型服务、API服务、向量库各跑一个容器本地开发和云端部署保持同样环境。为什么反复强调选型要“调试方便”因为AI系统的黑盒问题太多了。如果框架把prompt的组装、模型的调用、Agent的循环都封装在内部出了错你只能看一个抽象报错根本不知道是模型抽风还是代码逻辑错了。手写核心路径看起来多写了几行代码但每一步都能打日志、断点调试长期收益远大于省下的那点开发时间。2. 核心细节解析数据与Prompt是AI工程的命门2.1 数据准备80%的精力都在这里AI工程里最容易低估的就是数据准备。我见过很多项目代码写得飞快但一问到用来评估模型效果的数据集往往只有二三十条手工写的样例。这完全不够。模型输出的质量很大程度上取决于你给它多少高质量的示例以及你拿什么标准去衡量它有没有跑偏。我现在的做法是任何一个AI功能上线前必须先准备三份数据评估集、知识库片段、Few-shot示例集。评估集是拿来判断模型改动是好是坏的基础。我会从真实用户日志里收集100到200条问题按业务场景分类再给每一条标注标准答案或者答案要点。数据清洗这一步特别关键用户输入不能直接塞给模型。我写过一个清洗函数会做这几件事去掉多余的空白符和HTML标签把全角标点转成半角对繁体中文做简单转简体对常见的同义改写做归一化。这些看起来不起眼但直接影响检索匹配和模型理解。真实项目里因为一个全角括号没转导致JSON解析失败的情况我都遇过不止一次。知识库片段则是给RAG用的格式上我坚持用结构化的Markdown或JSON统一存储。每一条知识至少包含id、标题、正文、来源、更新时间。这里有一个很容易踩的坑千万不要把几万字的长文档直接切成长度不可控的段落否则检索出来的是半截话模型根本看不懂。我的切分策略是按标题层级先分块再把超过一定长度的块按句子边界切开每块控制在500到800字左右并且保留前后的上下文摘要。切分之后的片段需要人工抽检看有没有切断关键逻辑。Few-shot示例是给prompt做示范用的这组数据要刻意覆盖边界情况。比如用户问“今天有什么安排”你要准备一个场景数据库里没有日程时助手应该怎么回答也要准备一个有日程但用户权限不够的场景看模型能不能识别。示例的意义不是让模型背答案而是帮它理解你的行为边界。我会把示例格式统一为“用户输入”加“期望行为”写进system prompt或作为执行时的上下文。2.2 Prompt Engineering实操让模型稳定输出你想要的结果Prompt Engineering这个词这两年热度一直很高但我发现很多人对它的理解停留在“写一段漂亮的话”。实际上Prompt是你在和概率模型打交道时唯一能直接控制的“接口”它需要被当成代码来管理。我最基本的要求是每个prompt模板必须有版本号改动后要记录变更原因并且立刻跑一遍评估集确认效果没有回退。在模板设计上我习惯把system prompt拆成四个部分角色、任务、约束条件、输出格式。角色定义决定模型的语气和知识边界任务描述要让模型知道它具体要完成什么约束条件要明确“不能做什么”输出格式则尽量用结构化的方式约束模型方便后续解析。举个例子如果我做一个日程助手system prompt里会写你是一个企业日程管理助手。根据用户提供的日程信息回答关于会议安排、时间冲突、日程提醒等问题。你只能基于给定的日程数据进行回答不要编造不存在的会议。输出必须是一个JSON对象包含response和data两个字段response是给用户看的自然语言回复data是结构化的日程列表。如果没有相关日程data返回空数组。这样分段写的目的是为了让每一条约束都能被单独调整。比如发现模型开始编造会议了我只需要修改“不要编造不存在的会议”这一条不需要重写整个prompt。输出格式这里我强烈建议要求模型输出JSON并在代码里做二次校验和解析。不要相信模型一定给你合法JSON哪怕概率是95%上线后的流量也会让这5%变成每天上百次报错。解析失败时我会让程序自动尝试修复比如截取第一个{到最后一个}之间的内容或者调用一次修正请求让模型把非法输出重新整理成合法JSON。参数设置方面我的经验是普通业务场景temperature设成0.2到0.4不要太高。如果这个功能要求严格符合事实直接设0如果是头脑风暴类需求才调到0.8以上。max_tokens要显式设置不设置的话模型可能因为生成了很长的废话而拖慢响应。还有frequency_penalty和presence_penalty这两个参数我一般在做长文本生成时才会用用来减少重复内容其他场景默认0就好。所有参数我都通过配置文件暴露而不是硬编码在代码里这样线上调参不需要发版本。2.3 上下文管理与结构化输出上下文窗口再大也是有限的一个AI工程只要做对话场景迟早会遇到上下文爆炸的问题。我处理上下文的基本策略是分三层短期上下文、工作记忆、长期知识。短期上下文保存最近几轮对话全文通常限制在10轮以内工作记忆是对前面内容的摘要每一轮都会用模型生成一段压缩后的状态长期知识则是通过RAG从向量库检索出来的相关片段只有在需要时才注入。这三层各有用处能有效控制token数量。对于结构化输出除了在prompt里要求JSON我更推荐基于工具调用Function Calling的机制。现在的模型API基本都支持传入工具定义模型会生成一个结构化的工具调用参数而不是自由输出文本。这样我就能直接得到一个Python字典几乎不需要正则解析。比如我需要模型从用户输入中抽取“意图”和“实体”就定义一个extract_event工具参数里写清楚日期、标题、参与人。模型一旦决定调用这个工具返回的参数绝对是合法JSON因为这是模型自己的能力而不是靠prompt要求出来的。当然结构化输出也不是银弹。工具调用的参数有时也会缺字段所以我在代码里会做schema校验缺了字段就返回一个提示信息让模型补充而不是直接崩溃。这里我踩过一个坑一开始我把schema写得特别细要求模型必须填所有字段结果模型开始编造一些不存在的值反而导致准确率下降。后来我放宽了必填字段只保留业务真正需要的字段问题才缓解。所以设计schema时要遵循“最少必要字段”原则先保证稳定再考虑丰富。3. 实操过程从零实现一个可用的AI Agent工作流3.1 Agent架构设计工具、记忆与规划当业务逻辑开始复杂单纯“prompt-回答”就不够了你需要让模型能主动调用外部工具这就是Agent。我实现的第一个Agent是日程管理助手需要完成查日程、创建日程、改时间、提醒冲突等操作。Agent的本质可以理解为一个循环模型根据当前对话状态决定是直接回复用户还是调用某个工具调用完工具后把工具结果返回给模型模型再决定下一步动作。这个循环会一直执行直到模型认为任务完成。工具设计是Agent里最基础的部分。我维护一个工具列表每个工具有名字、描述、参数schema。描述极其重要因为模型是靠描述来判断什么情况调用哪个工具的。比如“search_events”的描述我会写成“根据日期或关键词查询日程返回日程列表”如果描述里没写清楚日期格式模型就可能在参数里传乱七八糟的值。每个工具在代码里就是普通函数但函数内部要有完整的异常捕获不能让底层错误直接冒泡到Agent循环里。记忆和规划是Agent能不能真正实用的关键。我的短期记忆维护一个消息列表每次模型调用后追加新消息但列表有长度上限超过后就把最早的消息搬到“摘要系统”里。规划部分我用的是一种简单的ReAct模式每次循环让模型先输出”reasoning”思考过程再选择是否调用工具。把这个思考过程记录下来既方便调试也能在模型犯错误时回溯。不要一上来就做复杂的多Agent协作单Agent加上几个稳定工具已经能解决大部分问题。3.2 核心代码实现与关键参数说明我把核心代码简化出一个可运行的示例展示最小的Agent循环。这个版本没有依赖Agent框架只用了模型API的Function Calling能力你可以直接替换成任意兼容的接口。import json from openai import OpenAI client OpenAI() def search_events(date: str None, keyword: str None): # 实际项目里这里会查数据库或调用日历服务 return [ {event_id: 1, title: 项目评审会, date: 2025-05-06, attendees: [张三, 李四]} ] TOOLS [ { type: function, function: { name: search_events, description: 根据日期或关键词查询日程返回日程列表, parameters: { type: object, properties: { date: {type: string, description: 日期格式YYYY-MM-DD}, keyword: {type: string} } } } } ] def run_agent(user_input: str): messages [ {role: system, content: 你是日程助手尽力使用工具解答用户问题不要编造日程。}, {role: user, content: user_input} ] max_iterations 5 for i in range(max_iterations): resp client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolsTOOLS, tool_choiceauto, temperature0.2, max_tokens1024 ) msg resp.choices[0].message messages.append(msg.model_dump()) if msg.tool_calls: for tc in msg.tool_calls: result eval(tc.function.name)(**json.loads(tc.function.arguments)) messages.append({ role: tool, tool_call_id: tc.id, content: json.dumps(result, ensure_asciiFalse) }) else: return msg.content return 处理超时请稍后再试这段代码里我最想强调的参数是max_iterations。它防止Agent陷入死循环是一个保险丝。我把这个值设为5原因很简单一个日程查询任务最多经历“查表-确认-回复”三步就够了如果5步还搞不定多半是模型思路跑偏了继续循环只会浪费token和用户时间。temperature0.2也是有意为之Agent环境下需要的是稳定决策不是发散创意。max_tokens1024则是避免模型单次输出过长毕竟工具调用场景下它一次只需要生成一小段结构化内容。实际项目中工具函数千万不要用eval来调用。这里为了示例简短才这么写正规做法是用一个字典做名称到函数的映射比如注册器模式既安全又方便日志记录。另一个容易被忽略的是tool_call_id这个字段必须原样返回给API否则模型会认为工具结果对不上号导致对话状态错乱。我第一次写的时候漏过这个字段结果模型每次都说“没有收到工具返回结果”排查了很久。3.3 异常处理与日志追踪工程化的第一步代码能跑只是起点真正工程化要做的是让每一次失败都可追踪。我在Agent循环外围加了一层统一异常处理调用API超时最多重试两次如果还是失败返回一个降级话术并记录告警。工具内部抛出的异常被我统一包装成{error: tool timeout, detail: ...}这样模型看到的是一个正常的工具返回可以自行决定是重试还是告诉用户处理失败而不是让整个Agent崩溃。日志是我觉得最值得投入精力的地方。每次Agent运行我会生成一个run_idUUID贯穿整个链路。日志里记录四样东西当前使用的prompt版本号、模型名称与参数快照、每次模型返回的原始内容、每次工具调用的输入输出。为什么一定要记prompt版本号因为模型输出如果变差了可能是prompt被改动导致的也可能是模型厂商悄悄升级了底层模型。没有版本号这些问题根本没法定位。我用结构化日志JSON Lines存到一个文件里上线后用ELK或轻量日志系统做检索排查问题时按run_id拉出完整链路就够了。4. 从本地到线上模型部署与测试经验4.1 部署方案选择API、自建、混合策略模型部署是个绕不开的话题。我的选择依据是业务场景和成本约束。如果团队没有专门的GPU运维能力大多数场景直接用大模型API是最稳妥的。OpenAI、Claude、国内几家大模型API都提供了比较完整的接口开发效率最高。缺点也很明显数据要出网对某些行业不友好成本可能随调用量上涨模型版本也由厂商控制。如果项目对数据安全有硬性要求或者调用量大到API费用已经超过自建推理成本再考虑自建开源模型。自建模型我推荐vLLM它对连续批处理做得比较好能把GPU利用率拉高数倍。装好之后它能提供一个兼容OpenAI接口格式的服务所以上层代码几乎不用改只需要把Client的base_url指向本地服务。模型选择上7B到14B参数的开源模型在普通业务场景已经够用比如Qwen系列和Llama系列。硬件方面7B量化模型一张24G显存的卡能跑14B模型建议用两张卡或一块48G显存。GPU资源有限时可以考虑CPU部署但响应速度会明显变慢只能适合内部低频工具。实际项目里我更多用混合策略核心链路调用大模型API稳定且效果有保障高并发或批量离线任务走自建开源模型控制成本两套模型都封装在同一个chat()接口后面通过配置切换。这个接口的切换逻辑我放在了启动加载时而不是每次请求都判断以避免多一层分支复杂度。部署时Docker是必需品模型服务、API服务、向量库各自独立容器用docker-compose统一管理本地能跑通云服务器上也不会环境不一致。4.2 性能调优与成本计算很多人说AI应用贵其实贵不贵要看怎么算。我建过一张成本计算表核心公式是单次请求成本 输入token数 × 输入单价 输出token数 × 输出单价。假设某API定价为输入$0.005/1K token输出$0.015/1K token一个普通问答请求平均输入1.2K token输出0.3K token那单次成本大概是0.006 0.0045 0.0105美元折合人民币约7分钱。看起来不多但一天跑10000次就是700块一个月就是两万。所以成本优化必须从第一天就考虑。我最常用的三个降本手段是缓存、RAG预热、和模型分级。缓存可以缓存重复度高的query比如FAQ类问题命中缓存直接返回结果完全不用调模型。RAG预热是指对于知识库检索结果系统启动时先把热点知识片段准备好减少实时嵌入计算。模型分级是指简单任务用便宜的轻量模型复杂任务才升级到更强的模型。在代码里我还加了一个开关当某段时间调用量突增时自动把非核心流程降级到更便宜的模型保障主链路稳定。性能方面最需要注意的瓶颈往往不在模型推理而在网络或下游服务。一个模型API请求如果经常等上10秒用户体验基本就崩了。我会用流式输出SSE让文字一个字一个字地出来用户感知的延迟会小很多。同时给API设两个超时时间连接超时3秒读取超时30秒避免无谓的等待。对于长任务用异步任务替代同步请求把计算结果通过回调或轮询通知给前端。4.3 AI测试与回归策略我见到的AI项目里很多开发团队的测试还是只测“有没有报错”根本不测“回答质量有没有变差”。这不行。AI工程至少要有一层基于评测集的回归测试。我搭建的测试结构分四层单元测试、集成测试、评测测试、人工抽检。单元测试覆盖工具函数和解析逻辑比如JSON解析函数遇到非法输入能否正确返回错误。集成测试验证完整调用链从API入口到模型调用到工具执行再到响应封装确保没有拼写错误和数据结构错配。评测测试是AI项目最有特色的一层。我维护了一个评测集比如100条真实用户问题每条都标注了理想回答的关键要点。每次修改prompt或切换模型后我会跑一遍这100条数据用LLM-as-judge或者简单的人工对比来打分。这里我推荐先做一个自动打分器使用一个比业务模型更强的模型对比候选回答和标准答案按“准确性”“完整性”“意图对齐”三个维度打1到5分。自动打分能快速筛掉明显下滑的版本最后再人工确认少量边界case。这个流程看似有点重但能防止“改一个prompt修好了A问题结果B问题大面积恶化”的悲剧。5. 常见问题排查与避坑指南5.1 模型输出不稳定怎么排查遇到模型输出不稳定第一件事不是改prompt而是先复现。我把同样的输入、同样的参数、同样的上下文固定下来连续调用五次观察结果。如果五次结果差异很大多半是temperature设置太高或者模型上下文里缺少关键约束。这时候我会把temperature降到0并加强输出格式约束。如果降低温度后依然不稳定问题就出在上下文中的示例或指令本身有歧义。你让模型“总结一下”它可能理解为“提取要点”也可能理解为“用一句话概括”这时要在prompt里明确“总结”的定义和字数范围。排查不稳定问题时务必把每次请求的完整参数和响应都记录到日志里。我之前排查一个客服机器人时发现模型偶尔会在回答末尾多出一句“祝你生活愉快”有人认为是prompt问题但后来看日志发现是用户历史消息里出现过这句话模型模仿了用户风格。这种case靠肉眼猜是猜不出来的只有日志才能暴露因果。5.2 上下文爆炸与幻觉问题上下文一旦超过模型的实际处理能力最典型的表现就是对话变慢、逻辑开始混乱、甚至出现幻觉。我处理上下文爆炸的办法在2.3里已经提过这里补充一个实际案例。我有一个项目需要长期记忆用户偏好一开始把用户所有历史记录都塞进上下文结果token占用越来越多模型回答质量明显下降。后来我改为只保留最近5轮对话原文更早的偏好信息则存成结构化的用户画像对象每次请求时通过检索把最相关的几条偏好注入prompt。效果立竿见影上下文占用降了一半回答准确率反而提升了。幻觉问题的根源本质上是模型在自由生成时“编造”。我的对策是给模型划定回答边界如果知识库或工具返回结果里没有的答案必须明确说“我不知道”而不是猜测。同时把知识片段附上来源ID要求模型在回答时引用来源编号这样即使结果错误我至少能追踪到是哪条知识引起的。对于涉及计算或事实核对的场景更稳妥的做法是先让模型调用工具去查而不是直接让它凭记忆回答。5.3 部署后响应速度慢怎么办先定位瓶颈再优化这是排查响应慢问题的铁律。我的第一反应是看日志里的耗时分布模型调用耗时多少、工具执行耗时多少、网络传输耗时多少。如果90%的时间都花在模型调用上那就考虑换更快的模型参数量、使用量化的版本或者升级推理框架。如果时间花在下游数据库查询上说明工具实现需要加索引或缓存而不是跑到模型那边瞎调。另一个常见坑是同步调用模型导致API服务线程被占满。高峰期每个请求占一个工作线程每个线程要等模型返回好几秒整个服务很快就不可用了。解决方法是把模型调用改成异步模式并使用并发上限控制。此外vLLM这类框架支持Streaming在适当场景用流式响应对感知延迟帮助很大。最后别忘了对API入口做压测我常用的方法是并发50个请求持续3分钟看P95耗时和报错率如果在预期范围内再扩大流量上线。最后再分享一个小技巧所有线上日志一定要记录prompt版本号和模型版本号否则出了幻觉你根本不知道是prompt改坏了还是模型升级导致的。这个习惯帮我省了很多排查时间也让我在团队里被同事追问“最近为什么回答质量下降了”的时候能直接甩出一条日志链路而不是含糊其辞。AI工程就是个不断与不确定性博弈的过程把这些细节管住了系统才能慢慢变得可靠起来。
