AI工程从零到实战：环境搭建、Prompt设计到Agent工作流全复盘

想搞清楚“AI工程从零开始”到底要学什么、做什么光刷教程是不够的。我自己的体验是看别人的AI项目像是看魔术轮到自己动手才发现每个环节都有坑。这篇内容就是我从零搭起一套AI工程能力后的完整复盘从环境准备、Prompt设计到Agent工作流、评估落地再到成本控制把整条路走一遍。适合两类人一是刚接触AI开发、想系统建立工程认知的新手二是已经能调通API接口、却一提到“工程化”就头大的开发者。1. 先搞清楚AI工程到底在学什么1.1 破除“会调接口等于会AI工程”的误区我第一次用大模型API跑通代码的时候那种成就感是真的。几行Python把用户消息发给模型拿到一段像模像样的回答感觉已经“掌握AI开发”了。但真正开始做项目后我才意识到这只是最表层的调用。打个比方会用微波炉热剩饭和能开一家后厨是两码事。接口调用只是把原料放进去、把成品端出来而工程化要考虑的是怎么保证成品口味稳定客人一多怎么不排队原料涨价了怎么调菜单落到实际场景中你会发现几个真正的问题。输入换个说法输出还稳不稳定模型偶尔犯迷糊怎么拦截上线之后每次接口调用花多少钱心里有没有数Prompt改了一版又一版到底哪版更好靠什么来判断这一连串问题才是“AI工程”的核心。如果只停留在“跑通demo”的水平你做的依然是脚本不是工程。1.2 AI工程师的能力地图我把自己走过的路整理成一张能力地图分五个层次每一层都有对应的技能和工具缺哪块补哪块层次核心能力常见工具与技能典型误区模型层理解模型特性上下文窗口、推理能力、价格差异只用最强模型不看成本和延迟交互层与大模型高效对话Prompt Engineering、JSON输出、Function Calling把Prompt当“聊天”不当作规格说明编排层让模型参与多步决策Agent循环、工作流、记忆检索一上来就堆框架不懂底层逻辑工程层保障质量与稳定评估集、日志追踪、回归测试、CI只靠“肉眼判断”模型输出好坏基础设施搭好运行底座环境隔离、依赖管理、模型部署全局环境一把梭升级即翻车这张表并不是随便写的。我发现很多教程都只聚焦“交互层”教你怎么写一个更花的Prompt却对工程层和基础设施层闭口不谈。但恰恰是后面这两层决定了你的项目到底是“课设作品”还是“可以用的产品”。1.3 一条清晰的四步学习主线只列知识点还是太散我给自己的规划是一条递进的主线。第一步用API跑通一个极小的垂直场景比如让模型帮忙写周报先跑通再说。第二步把输入输出固化成结构化格式让这个场景能被反复调用。第三步加入多步推理和工具调用让程序自己决定“先查数据、再写结论”。第四步为这个场景建立评估集把每次改动纳入回归测试。这条线走完你才算真正把一个AI需求做成了工程闭环。后面每一章基本就是这条线每一步的展开。2. 从零搭建一个能跑的最小环境2.1 Python环境与项目骨架先别急着写代码做AI工程我强烈建议从第一天就用虚拟环境不要图省事直接装在全局环境里。第一次搞坏全局Python环境之后我就老实了——装某个依赖的时候它偷偷把系统里另一个包升级了结果其他项目全部启动失败。那种排错体验一次就够了。现在我的习惯是用venv或uv给每个项目建独立环境Python版本固定在3.11以上项目根目录放一个requirements.txt锁住依赖。我一般新建项目时会搭一个最小但完整的目录骨架大概长这样my-ai-app/ ├── .env # 存放API Key等敏感配置不进Git ├── .gitignore # 忽略 .env、__pycache__ 等 ├── config.py # 统一读取环境配置 ├── main.py # 入口程序 ├── prompts.py # 集中管理提示词 ├── services/ │ └── llm.py # 所有大模型调用都走这一层封装 └── tests/ └── eval_cases.py # 评估用例这个结构看起来简单但我实际用下来收益比想象中更大。.env和config.py把API Key和模型名全部参数化换模型、换服务商不用改业务代码。services/llm.py这个封装层更是关键它把“底层调谁”和“上层业务”隔离了后面所有项目都可以复用。2.2 接入大模型的正确姿势以OpenAI兼容接口为例现在绝大多数大模型供应商都提供这种兼容格式代码写起来非常统一。一个最朴素但够用的调用封装长这样from openai import OpenAI from dotenv import load_dotenv import os load_dotenv() client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL), # 指向你的服务商兼容接口 ) def chat(messages, modelgpt-4o-mini, temperature0.7): resp client.chat.completions.create( modelmodel, messagesmessages, temperaturetemperature, ) return resp.choices[0].message.content这段代码里最值得说两句的是base_url这个参数。把它用环境变量接管之后换一个服务商就只需要改.env文件里的地址和Key业务代码一行不动。这个习惯让我后面在多种模型之间切换时省了不少事。另外temperature这个参数我通常不会轻易给到1.0。做创造性任务可以高一点但凡是需要稳定输出的场景0到0.3之间的表现更可控。2.3 API调用和本地部署怎么选本地部署这个词最近很热但我的建议是如果你只是学工程能力优先用API别折腾本地模型。API的优势是省心、稳定、能力上限高不需要管显卡驱动、显存溢出、量化精度这些事。本地部署适合三类场景数据敏感不能出内网、完全离线运行、或者请求量大到API成本失控。如果真要本地部署我用Ollama这类工具跑过几个开源小模型用来做实验和验证Prompt是可以的但别指望7B和13B的模型在复杂推理上跟大厂旗舰模型打得有来有回。我的选型决策很简单模型能力要求高的用云端API能力要求不高的、或者纯粹想省钱的、又或者对延迟敏感的任务才考虑本地小模型。记住一条原则能用API解决问题就不自己造运维的轮子。3. Prompt EngineeringAI工程里最被低估的基本功3.1 为什么Prompt值得当成工程问题对待有一种流行说法是“Prompt Engineering已经过时了”我完全不认同。在实际项目里模型输出不稳定、答非所问、格式混乱很多时候根因都在Prompt设计上。它就像你跟外包同事交代任务你只说“帮我写个报告”对方交上来的东西能不能用全看运气你要是把背景、受众、结构、字数、范例都给齐了他交付的质量就会稳定很多。更关键的是Prompt是整套AI系统里成本最低、杠杆最高的优化点。改代码要重新部署换模型要评估成本而修改Prompt只花几分钟就能见效。正因为这样我接手任何AI项目的第一件事都是看Prompt写得好不好而不是急着调模型参数。3.2 一个结构化的Prompt设计方法我自己写Prompt不是自由发挥而是套用一个固定模板包含六个要素角色定义、任务描述、输入说明、约束条件、示例输出、输出格式。举个例子一个写日报助手的Prompt我会这么写你是一位熟悉软件开发流程的项目助理。你的任务是根据用户提供的当日工作流水生成一份结构清晰的日报。日报需包含三部分今日完成、存在问题、明日计划。约束条件不得编造流水之外的内容描述每条都要控制在50字以内。示例输出今日完成-完成登录模块接口联调。输出格式使用Markdown无序列表。对比一下最原始的写法“帮我写日报”效果差异非常明显。加了约束和示例后模型基本不会跑偏。我习惯把所以Prompt都放在prompts.py里统一管理每个Prompt对应一个Python常量。这样改版本、做A/B对比都方便很多。3.3 让模型输出结构化数据而不是散文做AI应用时比起让模型输出大段文字更需要的是让它返回结构化的JSON数据这样下游代码才能直接处理。我自己早期吃过这个亏让模型返回“城市名、天气、温度”结果它回了一段自然语言解析正则写了一下午第二天它稍微换个句式我的正则就废了。正确的做法是在API调用里指定JSON输出模式resp client.chat.completions.create( modelgpt-4o-mini, messages[ {role: system, content: 你是一个天气信息解析助手。}, {role: user, content: 北京今天天气怎么样} ], response_format{type: json_object}, )配合response_format参数模型会强制输出合法JSON并且在Prompt里明确要求字段名比如{city: 北京, weather: 晴, temperature: 20}。这样返回结果就能用json.loads()直接吃进来。结构化输出是我认为所有AI工程师必须尽早掌握的习惯它直接决定你的系统是“原型”还是“可集成产品”。4. 从单次调用到AI Agent让程序替你做多步决策4.1 Agent到底解决什么问题以及它凭什么敢叫“工程”单次调用模型就好比请了一位很懂行的顾问但问一句答一句。Agent则更像是雇了个秘书你交代“帮我安排明天的客户拜访”他会自己拆解任务查日历、看路线、订会议室、发通知。在工程上Agent的核心价值就是把过去“写死的if-else业务逻辑”变成“让模型当大脑、让函数当手脚”的自动化流程。一个最小可用的Agent系统我理解它需要四个要素规划也就是把目标拆成步骤记忆记住前面做过什么事工具能调用具体函数执行循环不断走“思考-行动-观察”这条回路。这四个要素缺一个Agent就会变成只会耍嘴皮子的话痨。4.2 一个最小Agent的完整实现用OpenAI的Function Calling写法我实现过一个非常简单的Agent。它可以先识别用户意图再调用一个天气查询函数最后把结果组织成回答import json from openai import OpenAI client OpenAI() TOOLS [{ type: function, function: { name: get_weather, description: 查询指定城市的当前天气, parameters: { type: object, properties: { city: {type: string, description: 城市名} }, required: [city] }, } }] def get_weather(city): # 这里接真实天气API return f{city}当前晴气温20℃ def run_agent(user_input): messages [{role: user, content: user_input}] for _ in range(5): resp client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolsTOOLS, tool_choiceauto, ) msg resp.choices[0].message if msg.tool_calls: messages.append(msg) for tc in msg.tool_calls: args json.loads(tc.function.arguments) result globals()[tc.function.name](**args) messages.append({ role: tool, tool_call_id: tc.id, content: str(result), }) else: return msg.content raise RuntimeError(Agent运行超过最大轮数已终止)这里有个关键细节循环里设置了最大轮数5次这是我刻意加的安全阀。没有这个限制一旦模型陷入工具调用死循环你的账单会以肉眼可见的速度膨胀。这个例子麻雀虽小但规划、工具、执行循环三个要素都齐了理解它之后再去看任何Agent框架都会觉得底层逻辑似曾相识。4.3 框架选型我的结论可能和你想的不一样项目复杂了自然会考虑用框架。我实际比较过LangChain、Spring AI和直接写裸代码三种路线。结论可能出乎意料学习阶段我用裸代码理解原理生产项目我选择尽量少依赖框架只在真正需要现成组件时才引入。原因很简单LangChain这类框架确实功能全面但它把太多细节藏起来了出了问题你很难定位。而裸代码虽然每个循环都要自己写但每一步都清清楚楚出了问题能顺着逻辑逐行排查。Java生态的开发者可以考虑Spring AI它在结构化输出和可测试性上做得不错。框架永远只是加速器不是替代思考的东西。先拿到Walk的底层能力再考虑Run。5. 评测、监控与成本工程落地绕不开的三件事5.1 没有评估体系你的一切优化都是心理安慰这是我踩过最大的坑。有一段时间我反复修改Prompt每次改完都觉得“模型变聪明了”但项目一上线就暴露出各种问题。后来我想明白了一件事没有量化对比的优化全是主观错觉。现在我每个项目都会建一个评估集至少要包含30到50条测试用例覆盖正常场景和边界场景。每次改动Prompt或换模型都跑一遍这套用例然后给输出打分。打分维度我一般看三个相关性回答是不是切题忠实度有没有凭空捏造上下文里没有的东西稳定性同样的输入跑了多次结果有多大波动。评分的办法可以用模型当裁判把几个输出丢给更强的模型打分但也要定期抽样人工复核防止裁判模型自己飘了。没有这套机制你根本不知道每次“改进”到底是改进还是倒退。5.2 日志与追踪看清每一次调用到底发生了什么AI应用的排错思路和传统后端不一样。传统后端报错是明确的异常堆栈而AI应用最常见的失败是“模型胡说八道”程序不报错但结果不能用。这时候如果连日志都没有你根本无从下手。我给自己的系统加了一个最低限度的日志规范每次调用模型记录模型名、Prompt完整内容、模型返回内容、token消耗量、耗时、当时的Prompt版本号。有了这些记录模型出了问题就能拎出来复盘。尤其是Prompt版本号这个字段特别重要。没有它你根本不知道线上跑的Prompt是哪一版出问题都没法回滚。5.3 成本控制Token比你想象中贵本地部署省不省钱见仁见智但API调用多少钱算一笔账就门儿清。我以前用旗舰大模型跑所有任务平均每次请求消耗2000个token一天有1万次调用。旗舰模型差不多每百万token几十美元你要是用最小的模型只要零头。同样是跑一天成本差了将近十倍。我现在用的是金字塔策略简单任务比如关键词提取和格式化用便宜的小模型中等难度的任务比如写周报和摘要用中等档次的模型只有复杂推理、长文本理解这类高难度任务才上旗舰模型。每次调用前先问一句“这个任务真的需要最强的模型吗”。另外命中缓存也能省下大笔钱。对于用户高频重复的请求做一个结果缓存层成本能再降一截。控制成本不是抠门是让钱花在真正有价值的算力上。6. 新手最容易踩的坑附自查清单6.1 六个高频问题的现象与根因说多了方法论最后整理一份踩坑速查表。以下六个都是我在实际项目中遇到、且周围同事也频繁踩中的问题每条都附了排查思路。问题现象根因排查与解决输出格式时好时坏Prompt约束不明确或没开JSON模式补上输出格式要求开启response_format对话越长回答越傻上下文窗口被塞满注意力被稀释引入摘要机制裁剪无关历史消息模型一本正经胡说缺少可靠知识来源又在Prompt中让它“发挥”接入检索增强限定只能基于上下文回答接口时不时超时未做重试与退避并发控制缺失加指数退避重试限制并发上限每次优化全凭感觉没有评估集建测评集改动前后量化对比升级一个包挂一片全局依赖混乱启用虚拟环境锁定依赖版本6.2 我踩过之后的三个独家习惯除了上面这些标准解法我在实践中还沉淀了三个比较个人化的习惯。第一凡是涉及模型输出的业务代码一律做防御性解析。即使开了JSON模式我也会在代码里检查返回内容是否合法、字段是否齐全宁可多写几行校验也好过上线后被脏数据打个措手不及。第二所有Prompt全部版本化存储。用Git管理改Prompt就像改代码一样留下历史记录。前几天我就靠git diff找到了上个月效果不错的一版Prompt一秒回滚省下半天调参时间。第三不要相信“全自动”。无论是Agent还是自动评估我都会预留人工确认和抽检节点。AI越自动化人工审阅的位置就越重要这不是保守而是工程上必须有的锚点。最后说几句实在话AI工程这条路上我学到最值钱的东西不是写多漂亮的Prompt也不是用多时髦的框架而是建立起了一套“快速验证-量化对比-持续迭代”的闭环。以后再看任何AI项目我都会先翻三样东西有没有评估集、日志里有没有Prompt版本号、上线前有没有跑过回归。不满足这三条做得再花哨我都会保持警惕。最后分享一个最实用的小建议从现在开始给你的每个AI小项目都建一个evaluation文件夹哪怕只放20条测试用例。这个习惯会在后面帮你省下至少百倍的时间因为它会让你每一次调整都有据可依而不是盲目地在模型输出里碰运气。