1. 项目设计与整体思路拆解1.1 先想清楚你做的到底是“调模型”还是“做工程”这两年“AI工程”这个词快被说烂了但说实话大部分人做的东西离“工程”两个字还有距离。你调通了一个大模型接口写了几行 prompt能跑出看起来不错的结果那叫“调模型”。真正叫 AI 工程的项目是从需求定义、数据准备、模型选型、提示词设计、Agent 编排、推理部署到效果评估形成完整闭环的一件事。我当初做“ai-engineering-from-scratch”这个项目就是想验证一个朴素的想法能不能不依赖任何重型平台完全靠开源组件和标准代码从零搭出一条可维护、可扩展、可观测的 AI 应用链路。这个项目非常适合四类人参考一是刚入门大模型应用开发、想搞懂全链路而不是只写 prompt 的开发者二是团队里需要从原型走向生产、却被各种概念绕晕的技术负责人三是想给非技术背景同事讲清楚“AI 工程到底在做什么”的布道者四是自己折腾过几个 Demo、但始终觉得缺一张全景图的自学者。看完这篇博客你能得到一条完整的技术路线以及我在实际搭建中踩过的坑和验证过的方案。1.2 AI 工程的最小闭环五层结构我在动手之前画过一张概念图后来实践证明这张图基本不用改。任何 AI 工程项目拆到底都是五层结构数据层、模型层、逻辑层、服务层、观测层。数据层负责把散落的文档、数据库、用户输入统一成模型能消费的格式模型层决定用闭源 API 还是开源权重、用对话模型还是嵌入模型逻辑层承载 prompt 模板、工具调用、Agent 编排这些业务规则服务层解决并发、鉴权、限流、部署这些问题观测层则记录每一次请求的输入输出、耗时、成本、效果评估结果。这五层不是线性的而是相互咬合的。比如你在逻辑层设计了一个多步骤 Agent它可能要动态调用数据层的检索接口而检索结果的质量又反过来影响你该选哪个模型。我最早犯的错就是把每一层单独优化结果联调的时候发现模型输出格式不稳定把整个链路拖垮了。后来我才意识到AI 工程的核心不是某一层多强而是层与层之间的契约设计得够不够清晰。1.3 为什么“从零开始”比“直接套框架”更值得这里要说一个反直觉的结论如果你是想快速出活直接套 LangChain、LlamaIndex 这类框架没问题但如果你想真正掌握 AI 工程的能力“从零开始”反而是更快的路径。原因很简单框架帮你屏蔽掉的恰恰是最值得学的部分——消息封装、上下文截断策略、工具调用的协议设计、多步推理的状态管理。这些细节在框架里往往是一个参数的事出了问题你却不知道从哪查起。我并不是鼓励所有场景都手写底层代码而是建议你在职业生涯里至少做一次“不依赖重框架”的完整实践。做完之后你再看框架的文档理解完全不一样——你会知道 LangChain 的某个模块在背后替你做了什么也知道哪些地方它做得并不好、需要自己替换。这套认知才是 AI 工程的核心竞争力。2. 环境搭建与工具选型少走弯路的组合方案2.1 语言与基础依赖栈为什么绕不开 Python选型这件事我在项目启动前纠结了很久。最终确定的是 Python 3.11 FastAPI Pydantic v2 作为基础服务栈模型侧同时接入了 OpenAI 兼容接口和本地开源模型Qwen 系列为主。Python 在这个领域的统治地位短期内不会被撼动原因不是它性能好而是整个 AI 生态的接口、SDK、示例代码几乎都是 Python 优先。你做一个端到端项目最大的成本往往不是代码本身而是集成成本选 Python 就是在降低集成成本。依赖这块我建议用 uv 管理虚拟环境比 pip requirements.txt 快且干净。核心依赖只有这么几个openai兼容各家 API、fastapi、uvicorn、pydantic、httpx、sqlalchemy、redis、qdrant-client。不要一上来就装一堆向量数据库和 Agent 框架先用最小集跑通全链路再按需加。# 创建虚拟环境并安装核心依赖 uv venv .venv --python 3.11 source .venv/bin/activate uv add openai fastapi uvicorn pydantic httpx sqlalchemy redis qdrant-client2.2 模型接入方案本地部署还是 API 调用模型选型直接决定项目的成本结构、响应速度和合规边界。我的建议是双轨并行开发阶段全部走云端 API用统一的 OpenAI 兼容格式写代码部署阶段根据场景决定是否切换本地模型。原因很朴素——开发期最大的变量是 prompt 和逻辑不是推理性能用 API 能最快验证想法上线后如果请求量大了再把高频路径切到本地模型用 vLLM 或者 Ollama 起服务降低单次调用成本。接 OpenAI 兼容接口时有一个细节特别容易踩很多开源模型的 API 服务比如 vLLM、FastChat 启动的服务对response_format这类参数的支持程度不一样你在开发环境能正常跑的结构化输出代码切到本地模型可能直接报错。教训是抽象层一定要自己写不要直接散落地调用 SDK。我封装了一个LLMClient类所有模型调用走同一个接口超时、重试、错误码统一处理这样后期切换模型只改配置不改业务代码。2.3 向量数据库与检索组件不要盲目上重型组件检索增强生成RAG几乎是 AI 工程的标配但向量数据库这一层的选型被严重高估了。如果你的数据量在百万级以下用 Qdrant 的嵌入式模式就够了不需要单独部署服务更不需要上 Milvus 这种重量级方案。我这边的经验是先跑通再扩容初期用 JSON 文件存向量都行当你确认检索确实是瓶颈了再迁移到独立向量库也不迟。我自己最终选了 Qdrant 的 Docker 模式理由有四个一是 API 设计简洁REST 和 gRPC 都支持调试方便二是支持过滤条件与向量检索混合查询这在做权限控制和多租户场景时是刚需三是资源占用比 Milvus 小一个量级单机跑起来毫无压力四是 Python 客户端类型标注完善配合 Pydantic 模型做数据校验很顺畅。2.4 开发环境配置的细节清单把这些细节列成一个清单看起来琐碎但每一条都是真实踩出来的所有外部服务的连接配置API Key、数据库地址一律走.env文件用 Pydantic Settings 读取绝不硬编码在代码里。Redis 在这里的用途不是缓存这么简单Agent 运行时的状态暂存、消息队列、限流计数器都可以复用它部署时用 Docker Compose 统一起服务最省心。FastAPI 的文档虽然是自动生成的但你要主动补充请求/响应示例因为后续调试 Agent 链路时你需要在 Swagger UI 里反复手工触发接口没有示例就只能靠记忆拼参数。日志格式从一开始就统一成 JSON并且带上request_id后续排查问题如果日志格式不统一你会被逼疯。提示AI 工程里的绝大部分问题最终都是通过日志和数据查出来的不是靠“感觉”猜出来的。日志结构化这件事的重要性怎么强调都不为过。3. 核心链路实现Prompt 工程、Agent 编排与模型部署3.1 Prompt 工程的三层结构指令、上下文、约束Prompt 是 AI 工程里最容易被低估的组件。很多人以为写 prompt 就是把需求说清楚实际上工程化的 prompt 必须拆成三层来设计缺一层都会出问题。第一层是指令层明确告诉模型你要它扮演什么角色、完成什么任务、输出什么格式第二层是上下文层把所有与任务相关的背景信息、参考资料、历史消息组织好第三层是约束层定义清晰的成功标准、禁区、兜底方案。举个例子我项目里有一个“需求拆解助手”它的 prompt 模板大致是这个结构【指令】你是一个资深产品经理请将用户的原始需求拆解为目标、用户场景、功能列表、验收标准。 【上下文】以下是当前项目的背景信息{project_context}以下是用户的新需求{user_requirement}以下是历史相关需求的处理记录{history_records}。 【约束】1. 功能列表必须编号且每个功能必须标注优先级P0/P1/P22. 验收标准必须可量化禁止出现良好快速这类模糊词3. 如果需求信息不足先输出需要补充的问题清单不要强行拆解。这里的关键不是说教式地让模型“好好干”而是用结构把模型的输出空间约束住。我的实测结论是同样的模型和知识库prompt 从“一段话”改造成“三层结构”之后输出可用率从约 60% 提升到了 85% 以上。这 25 个百分点的提升不花一分钱推理成本纯粹靠工程优化换来的。3.2 从单一 Prompt 到多步骤 Agent 工作流单一 Prompt 的天花板很明显一次推理能处理的上下文有限复杂任务容易顾此失彼。所以要升级成多步骤的 Agent 工作流。我不想用“Agent”这个词来唬人说白了就是把一个大任务拆成几个小步骤每一步用一个专门化的 Prompt 处理步骤之间通过代码逻辑做判断和衔接。我在项目里实现了一个“竞品调研 Agent”完整流程是这样的第一步入参是竞品名称和企业背景调用搜索工具或者知识库检索拿到原始资料第二步用“信息抽取” Prompt 从原始资料中提炼出产品功能、定价策略、目标用户三个维度的半结构化数据第三步用一个“分析决策” Prompt 结合抽取结果生成差异化建议。每一步的输出都会经过 Pydantic 模型做格式校验校验失败就走重试逻辑重试仍然失败就降级返回部分结果。这个设计的核心思路是“让每一步模型都做擅长的事”。大模型做单点任务抽取、分类、总结的稳定性远高于做端到端的复杂任务这是工程上的基本盘外面各种炫酷的 Agent 框架本质上也没有跳出这个套路。3.3 记忆与上下文管理的工程化处理多步骤 Agent 跑起来之后你很快会遇到一个绕不开的问题上下文管理。模型有 Token 上限每一步产生的中间结果不能无限往对话里塞。工程上一般有三种处理策略我项目里都试过分别说下效果。第一种是滑动窗口只保留最近 N 轮对话简单粗暴但会丢失早期关键信息第二种是摘要压缩每一步结束后让模型把对话压缩成摘要信息密度高但会引入新的推理误差和成本第三种是外部记忆关键信息抽出来存到向量库或 Redis在需要的时候再检索回填。最终我的方案是三者的混合。每个 Agent 步骤开始时先从外部记忆载入与当前任务相关的信息作为“显式上下文”对话过程用滑动窗口控制 Token 消耗每完成一个子任务把结论和关键数据固化到 Redis 和向量库而不是留在对话历史里。这套机制保证了长期运行的稳定性和可追溯性代价是要多写不少胶水代码但绝对值。3.4 模型部署与推理服务化从开发到上线的关键一跳本地模型部署是 AI 工程绕不开的最后一环。我选的是 vLLM 作为推理引擎因为它对 Qwen 系列的支持很成熟而且 PagedAttention 机制能显著降低显存占用并发吞吐量高。部署配置文件我直接复用了一套标准模板核心就两条模型路径和 GPU 显存控制。# 用 vLLM 启动一个 OpenAI 兼容的推理服务 vllm serve Qwen/Qwen2.5-7B-Instruct \ --host 0.0.0.0 \ --port 8000 \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.9 \ --max-model-len 32768 \ --enforce-eager部署过程有几步很重要启动之后一定要用真实业务 prompt 做一轮冒烟测试而不是光看“服务起来了”用vllm serve的--served-model-name参数定义对外模型名这样客户端代码可以不感知实际模型是谁压测工具建议用hey或者locust先摸清楚并发能力和 P99 延迟再决定要不要上多个 worker 或者配负载均衡。不要跳过这一步因为只在小流量下验证过就从开发环境切生产大概率会出事故。部署完了没有监控等于白部署。我用 Prometheus Grafana 记录了每个模型的请求量、平均延迟、Token 吞吐量和错误数配合日志里的request_id用户抱怨“回答慢”或者“答得不对”时我能快速定位是哪一层出问题。这种可观测性的建设刚开始很枯燥但它决定了你后期迭代的速度上限。4. 常见问题与调试实录新手必踩的坑4.1 输出不稳定温度参数与结构化输出的组合拳AI 工程第一坑就是“模型偶尔抽风”。明明同样的输入上次输出格式工整这次就给你来一段废话或者乱码。治本的办法是双向约束一方面把温度参数调低我这边常规任务是temperature0.2创意类任务最高给到0.7从不开放到 1.0另一方面一定要强制模型输出 JSON并配合 Pydantic 做运行时校验。这里贴一个我实际用的输出约束方法比单纯“请输出 JSON”的 prompt 要稳得多from openai import OpenAI from pydantic import BaseModel # 定义结构化输出模型 class RequirementBreakdown(BaseModel): goals: list[str] user_scenarios: list[str] features: list[dict] # [{name, priority}] acceptance_criteria: list[str] client OpenAI(base_urlhttp://localhost:8000/v1, api_keyEMPTY) response client.chat.completions.create( modelQwen/Qwen2.5-7B-Instruct, messages[{role: user, content: prompt_text}], temperature0.2, max_tokens2048, response_format{type: json_object}, ) # 即使走了 response_format也要做运行时校验 parsed RequirementBreakdown.model_validate_json(response.choices[0].message.content)注意response_format是 OpenAI 兼容服务里的参数vLLM 和部分国产模型服务支持度不同如果服务端不认这个参数就必须靠 Pydantic 在代码侧做最后一道防线。我的原则是永远假设模型会犯错误然后用工程手段把错误挡在业务逻辑外面。4.2 上下文爆炸Token 上限引发的连锁问题开发 Agent 工作流时最隐蔽的问题是上下文爆炸。它不会立刻报错但会让模型的回答越来越偏、越来越慢、成本越来越高。我遇到过一个典型案例一个调研 Agent 在一次任务中把中间几次检索回来的网页全文都塞进了上下文导致单轮请求的 token 数超过 3 万结果模型后半段的输出质量明显下降逻辑混乱。排查之后发现是代码里把“检索命中内容”直接拼接进上下文没有做截断和去重。解决这个问题需要设定清晰的上下文预算体系。我的做法是为每个 Agent 步骤设置 token 预算上限参考值如下表上下文组成预算占比说明系统指令 Prompt 模板20%必须保留的固定逻辑用户输入15%原始需求不能压缩外部检索资料40%按相关性截断单条资料不超过 800 token历史对话摘要15%只保留摘要和关键结论当前步骤的中间输出10%仅供后续步骤引用不重复拼接每条内容进入上下文之前都要过一道“门卫”检查它是否已经被拼接过、是否超出预算上限。宁可让模型少一点参考材料也不能让它淹没在噪声里。4.3 成本失控一次请求烧掉几张卡的教训成本问题在开发期最容易忽略因为量小看不出差异一上线立刻现形。我这里记录过一个真实的教训某次写分析报告的任务原本可以用一个 7B 模型加一次调用搞定但我在 prompt 里放了大量背景材料加上模型本身就大单次请求消耗了近 6 万 token。如果这个请求每天跑 1000 次光这一条链路的成本就是每天几百万 token换算成 API 调用费不是小数目。控制成本的手段有四个层次模型选型上能用小模型解决的不用大模型这需要提前对任务难度做分级Prompt 设计上把不必要的信息挡在上下文之外减少每次请求的 token 量缓存策略上相同或近似的请求直接命中缓存结果降低重复计算部署策略上高频平坦路径切到自部署的本地模型彻底摆脱按 token 计费的枷锁。这些手段叠加起来项目的单次请求成本可以压到原来的十分之一以下。4.4 非技术陷阱测试、监控与迭代节奏AI 工程和维护传统软件工程有一个重大差异你没法靠“测试用例全过”来判断上线是安全的。模型输出的不确定性决定了必须有新的测试范式。我的做法是准备一套固定的评估集大约 60 到 100 条覆盖各种边界场景的输入每次改 prompt 或者换模型之后都跑一遍回归。评估标准不全是自动化的复杂任务我会上人工抽样打分用“可用率”和“无效输出率”两个指标来量化变化。迭代节奏也值得单独提一下。AI 应用的优化空间高度非线性并非每轮修改都能带来正收益。我的经验是每次只改动一个变量要么改 prompt要么换模型要么调参数不要一次性动多个。改完之后必须用评估集跑回归记录结果。这样迭代 20 轮之后你能非常清晰地知道哪个变量对结果的影响最大这段宝贵的手感是任何教科书都给不了的。5. 一些个人体会做这个项目最大的收获不是输出了一套多漂亮的代码而是真正理解了 AI 工程的全貌。我见过太多人把大量时间花在“调出一个好用的 prompt”上却忽略了后面的服务化、观测、评估和成本治理。事实上prompt 只是冰山一角水面下的工程问题才是决定项目能不能长期转起来的关键。如果你也想做类似的完整实践我的建议是别一上来就追求“完美架构”先写一个最朴素的端到端链路一个模型接口、一段 prompt 模板、一个 FastAPI 服务、一份 JSON 日志。跑通之后再一层一层把向量检索、Agent 工作流、评估体系加进去。每加一层你会更清楚它的必要性也更能理解那些重量级框架为什么存在。最后分享一个实操中的小技巧在本地跑 Agent 链路时同时开着一个自部署的小模型和一个云端大模型 API遇到逻辑复杂、容易翻车的任务就切到大模型日常任务走小模型。这既能压住成本又能保证最关键的体验不掉线。这种“双轨切换”的思路是我在这个项目里最不舍得删掉的设计之一。希望这篇分享对你的 AI 工程之路有点帮助哪怕只在某一个决策点上让你少踩一个坑就算值得了。