说实话，这两年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( model="gpt-4o-mini", messages=messages, tools=TOOLS, tool_choice="auto", temperature=0.2, max_tokens=1024 ) 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_ascii=False) }) else: return msg.content return "处理超时，请稍后再试"这段代码里我最想强调的参数是max_iterations。它防止Agent陷入死循环，是一个保险丝。我把这个值设为5，原因很简单：一个日程查询任务最多经历“查表-确认-回复”三步就够了，如果5步还搞不定，多半是模型思路跑偏了，继续循环只会浪费token和用户时间。temperature=0.2也是有意为之，Agent环境下需要的是稳定决策，不是发散创意。max_tokens=1024则是避免模型单次输出过长，毕竟工具调用场景下它一次只需要生成一小段结构化内容。
实际项目中，工具函数千万不要用eval来调用。这里为了示例简短才这么写，正规做法是用一个字典做名称到函数的映射，比如注册器模式，既安全又方便日志记录。另一个容易被忽略的是tool_call_id，这个字段必须原样返回给API，否则模型会认为工具结果对不上号，导致对话状态错乱。我第一次写的时候漏过这个字段，结果模型每次都说“没有收到工具返回结果”，排查了很久。
3.3 异常处理与日志追踪：工程化的第一步
代码能跑只是起点，真正工程化要做的是让每一次失败都可追踪。我在Agent循环外围加了一层统一异常处理：调用API超时最多重试两次，如果还是失败，返回一个降级话术并记录告警。工具内部抛出的异常被我统一包装成{"error": "tool timeout", "detail": ...}，这样模型看到的是一个正常的工具返回，可以自行决定是重试还是告诉用户处理失败，而不是让整个Agent崩溃。
日志是我觉得最值得投入精力的地方。每次Agent运行，我会生成一个run_id（UUID），贯穿整个链路。日志里记录四样东西：当前使用的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工程就是个不断与不确定性博弈的过程，把这些细节管住了，系统才能慢慢变得可靠起来。
