直接上手一个真实项目比看十篇教程有用得多。我这次想聊的就是“ai-engineering-from-scratch”这件事——从零开始把一个AI工程完整落地而不是停留在“调用大模型API”或者“套个聊天框”的层面。这个项目的核心目标是不依赖别人封装好的成品自己动手把模型能力、工具编排、上下文管理、效果评估串成一条可运行的工程链路。如果你是刚转AI方向的开发者或者已经在写Prompt但总觉得不成体系这篇内容会给你一套可复用的思考方式和操作路径。市面上关于AI工程的讨论很多但真正能落到代码里的不多。我这次选择了一个非常具体的场景做一个能读懂代码仓库的AI问答助手。它要能根据仓库里的代码、文档、配置文件回答“这个项目怎么启动”“这个函数在哪里定义”“这个模块的依赖关系是什么”这类问题。听起来不算复杂但真正做的时候会遇到一串经典问题知识怎么灌进模型上下文窗口不够怎么办答案不准确怎么修正Agent调用工具失败了怎么兜底这些恰恰就是AI工程的日常。1. 先想清楚AI工程和调API到底差在哪很多朋友第一次接触AI开发是从“调用一个聊天接口”开始的。输入一段文字拿到一个回答任务就完了。这当然也算AI应用但它不叫工程。工程意味着一件事系统里存在不确定因素而你通过设计让不确定性可控。放在AI里面这个不确定因素就是模型本身——它有时聪明有时犯低级错误有时一本正经地胡说八道。AI工程的核心工作就是把这种不稳定的能力嵌进一个稳定运行的系统里。有人会觉得那我选最强的模型不就行了实际上不行。模型能力是基础但不是全部。我见过团队用顶级模型做出一个体验很差的Demo也见过用普通模型配合精心设计的链路做出非常顺手的工具。差别就在于前者把模型当成了全部后者把模型当成了一个零部件。真正决定项目上限的是你怎么设计任务拆解、怎么管理上下文、怎么让Agent有效地调用工具、怎么评估和修正输出。1.1 大多数失败项目倒在同一个坑里我观察到很多AI项目的失败并不是模型不够聪明而是工程链路没打通。最常见的现象是Demo阶段效果惊艳一接真实场景就露馅。比如做个“企业知识库助手”小范围试的时候还挺好一上线就发现用户问法一变答案质量立刻崩掉。原因是你没有去梳理问题来了之后是走检索走直接问答还是走多轮澄清每种策略的触发条件是什么答错了之后用户反馈怎么回收再一个常见问题是没有评测体系。很多人做AI应用判断效果的方式是“我自己觉得好不好”这在小范围没问题但工程化必须量化。一个Prompt改完到底是变好了还是变差了没有评测数据你就是抓瞎。我在这个项目里一开始就搭了一套最小可用的批量评测脚本后面每个改动都跑一遍效果好了再合入。这套东西才是AI工程和AI Demo的分水岭。1.2 工程化的三个关键环节任务拆解、上下文设计、结果评估这三个环节基本决定了项目的成败。任务拆解是第一步也是最被低估的一步。很多人拿到需求第一反应是“我要写一个超长的Prompt让模型一步到位”结果Prompt写到两千字模型依然执行得稀烂。正确做法是把一个大任务拆成几个小任务每个小任务由一个独立的Prompts或函数完成再通过编排把它们串起来。一个模块只干一件事出错了也方便定位。上下文设计是第二环。模型不是万事通它只知道自己“看到”的内容。你要决定什么信息进上下文、什么信息不进、信息量超出窗口之后怎么压缩。这一步直接决定了回答的准确度。结果评估则是工程闭环没有评估前面两步都是盲人摸象。好在这三环都有成熟的方法论可以套并不需要从零发明。2. 项目立项把“代码库AI助手”变成可执行方案先交代一下这个项目的完整需求用户提供一个Git仓库地址或本地目录AI助手可以回答仓库相关的技术问题。它不是通用聊天机器人而是限定在“代码和工程文档”这个垂直领域。我给它设计了几个核心使用场景包括仓库结构讲解、函数定位与解释、启动步骤梳理、依赖关系说明以及根据现有代码风格生成新模块代码。定义好场景之后很多事情就明朗了。2.1 明确边界能做什么不做什么刚开始做的时候我犯过一个错误想让这个助手什么都干。既能讲业务逻辑又能解释算法细节还能做Code Review甚至想让它直接帮你重构整个项目。结果呢它什么都干不好。后来我把边界收了回来当前版本只处理“文本层面的代码理解问题”。也就是说它回答的是“这段代码做了什么”“这个函数在哪里”“项目该怎么启动”这类可以通过阅读源码和文档得出答案的问题。运行时动态分析、真实环境验证这类事情V1版本不做。这个边界听起来很保守但它有一个巨大的好处你知道模型在什么情况下会成功在什么情况下会失败。工程最怕的就是不可预期的失败。边界越清晰越容易做质量控制。等基础链路稳定了再慢慢扩展到“代码生成”“CI集成”这些方向稳步迭代一次只加一个功能点。2.2 技术选型模型、框架、接口的取舍这个项目我主要考虑了三个选型问题模型用哪家Agent框架要不要用检索索引怎么建。模型方面我优先考虑兼顾中文能力和代码理解能力的通用大模型同时必须支持Function Calling。Function Calling非常关键它是Agent能调用外部工具的前提。如果模型不支持这个能力后面要自己硬写JSON解析来模拟工具调度又麻烦又脆弱。框架方面我做过两种尝试一种是直接用LangChain之类的现成编排框架另一种是纯手写一套调度逻辑。结论是V1阶段手写更扎实。现成框架封装了很多概念学起来也需要成本。不过我确实不是全套框架都否定只是对于这个规模的项目手写一个基于函数循环的Agent调度器反而更清晰。自己写的调度逻辑每一步都能控制出了Bug也好修。框架的抽象在项目变大之后才有价值。索引方面我用的是最基本的“目录树关键文件全文检索”方案。先把仓库里Markdown、TXT、PY、TS、GO等文本类的文件读进来做一个简单的关键词倒排索引再加上一层语义向量检索。两个通道的结果合并去重之后再交给模型分析。这套方案不需要上重型分布式向量数据库单机跑足够。3. 核心机制拆解Prompt、上下文与Agent怎么协同既然标题是“from scratch”那核心机制就不能一笔带过。这一部分我会讲清楚三个东西Prompt到底在解决什么问题、Agent的循环是如何转起来的、以及上下文和Token预算怎么算。这三个概念你搞明白了AI工程的地基就算打好了。3.1 Prompt Engineering不是咒语是任务说明书很多人把Prompt Engineering当成某种魔法咒语觉得一个“魔法Prompt”就能让模型变聪明。我不太认同这个思路。我理解的Prompt Engineering是把一个任务描述清楚让模型能稳定地执行。它更像写需求说明书你要让模型扮演什么角色拿到什么输入遵守哪些约束输出什么格式不确定的时候怎么处理。我有个非常实用的经验一个通用的任务Prompt至少要包含五个部分——角色定义、任务目标、输入数据说明、输出格式要求、兜底行为。拿“函数定位”这个任务举例我会这么写你是一名资深的代码检索专家。你的任务是根据用户的问题在给定的项目文件中查找最可能相关的函数或方法并解释它的作用。 输入是一批代码文件的内容片段每段前面有一个文件名标记。 输出必须遵循以下格式文件名 函数名 三行以内的解释。 如果给定的文件内容中没有找到相关信息必须输出“未找到相关信息”严禁编造。这个Prompt看起来朴素但它每一句都有用。角色定义限制模型的知识边界任务目标明确动作输出格式方便后续程序解析兜底行为禁止幻觉。写Prompt的时候我习惯把“不允许做什么”写得非常具体这个比“请认真回答”有效得多。3.2 Agent循环模型推理与工具执行怎么配合严格来说Agent不是某一个具体的模型而是一种循环执行的架构。流程是这样的模型接收用户消息然后决定是要直接回答还是要调用某个工具。如果决定调用工具它会生成一个结构化的工具调用请求系统根据这个请求去执行真正的函数拿到结果之后再喂回给模型模型继续推理直到它决定直接回答为止。这个循环是整个Agent架构最核心的运转方式。我在实现的时候写了一个很简陋但够用的调度器。核心逻辑就一个while循环里面做三件事把历史消息发给模型判断返回内容是要继续调工具还是直接回复如果要调工具就执行对应的Python函数并把结果追加到消息序列。每条工具调用的结果我都加上了实际函数名和耗时标记方便后面排查性能问题。这里有一个重要细节每轮循环都会额外消耗Token因为工具结果也都进入上下文。如果Agent陷入死循环Token消耗会非常可怕。所以我设了“最大循环次数上限”默认是5次。5次还没把问题处理完就会要求模型放弃并返回一个部分结果至少用户能看到中间发生了什么。3.3 上下文与Token预算算清楚你的窗口够不够用上下文管理是整个AI工程里最容易被忽视、但影响最大的环节。大模型的注意力窗口是有限的比如32K、128K而一份真实代码仓库可能有几万甚至几十万个Token。你不可能全塞进去。解决这个问题有两个方案一是检索二是压缩。我的项目两个都用。检索负责把“可能相关的片段”从海量文件中捞出来。哪些文件可能有用户问到的函数哪里提到了这个名字关键词倒排索引负责精准匹配函数名和变量名向量检索负责语义匹配“项目如何启动”这类模糊问题。匹配到的片段拼接之后我再设置一个“最大进入上下文的字符数”比如8000字。超出部分就做取舍只能优先放得分最高的几段。压缩则是为了减少噪音。注释、空行、无意义的样板代码在进入上下文之前都会被去掉。源码本身信息密度低的部分比如重复的getter/setter我会直接丢弃。这步做完之后Token消耗能省下大概一半左右回答的准确率不会明显下降。Token预算这件事我建议在一开始就算好假设窗口是32K那么系统Prompt占2K检索片段占8K聊天历史占10K模型输出预留8K这样还剩4K浮动。把预算写进代码里做成硬限制比写“尽量压缩控制”靠谱得多。4. 实操从零搭建一个能读代码库的AI助手讲完原理开始动手。我这里的代码示例做了大量简化但保留了完整的技术脉络。如果照这个搭你也能得到一个可运行的骨架后续想丰富功能也只是往里头加函数的问题。4.1 环境准备依赖、密钥、模型接入我先说环境一个最小可跑的清单Python 3.10 openai SDK或你使用的大模型厂商对应SDK 一个支持Function Calling的模型API如gpt-4o-mini、qwen-plus、deepseek-chat等 纯Python实现的向量库numpy 一个Embedding接口就够依赖这块我不建议一开始就引入重型框架。项目还在原型阶段能省则省。我在V1版本里连数据库都没用索引直接跑在内存里重启就重新构建。数据量大了之后再换ES或专门的向量数据库也不迟反正上层接口可以抽象成一个“搜索”函数。模型接入方式很简单关键是Function Calling的定义。我定义了一个叫“search_code”的工具它的作用就是在仓库索引里搜索与关键词相关的文件片段。这个工具函数的定义必须严格写清楚参数名和用途模型才能正确生成调用请求。我记得第一次调试的时候参数名写得太随意模型经常把参数传错后来改成语义明确的命名就好多了。4.2 三步实现索引构建、检索召回、答案生成整个系统就三条主线建立索引检索片段让模型总结回答。第一步是索引构建。我写了一个脚本遍历目录把所有文本类文件读进来。对每个文件做三件事记录路径、生成关键词倒排表、调用Embedding接口把文件内容变成向量存进内存列表。一个小细节是我只做粗粒度的文件级别切块先用简单粗暴的方式跑通再回来优化切块策略。实测下来代码文件其实不需要切得太碎因为函数之间的引用关系经常跨文件切碎了反而丢线索。第二步是检索召回。用户提问之后先做一次关键词倒排表查询再做一次向量相似度查询然后把两路结果合并去重。代码大概长这样def search_relevant_files(query, top_k5): # 1. 关键词倒排提取query中的标识符比如函数名、变量名 keyword_hits [hit for token in extract_identifiers(query) for hit in inverted_index.get(token, [])] # 2. 语义向量召回用embedding算相似度 query_vector embed_fn(query) vector_hits rank_by_similarity(query_vector, file_vectors, top_ktop_k) # 3. 合并去重按得分排序本质上是用多路召回补全单一搜索的盲区 merged merge_and_dedup(keyword_hits, vector_hits) return trim_to_budget(merged, max_chars8000)这里我要解释一下为什么要做两路召回。关键词倒排擅长精确匹配比如“find_user_by_id”这个函数名向量检索往往想不明白。而向量检索擅长语义匹配比如用户问“怎么登录”代码里没有“登录”这个词但有“authenticate”函数关键词倒排就挂了。两路召回取并集准确率会高很多。第三步是答案生成。把检索到的文件片段拼接起来丢给模型让它按照用户的问题组织答案。我这里的生成Prompt也很固定里面必须强调“只能根据给定的片段回答片段没有的信息就承认不知道”。这是对付幻觉枷锁最有效的方法比说一万遍“别乱编”都好使。4.3 评测体系没有评测就没有工程化我见过太多的AI项目死在“自我感觉良好”上所以我从这个项目第一天开始就搭了评测。评测方法不复杂写一个JSON文件里面存20条左右的测试用例每条包含“问题、期望的答案关键词、期望引用的文件路径”。跑完一轮生成评测结果后有两个指标召回率指标即“回答中是否包含期望关键词”定位准确率指标即“回答是否关联了期望文件”。看似简单但实际作用巨大。有一次我调整了切块大小从512字符改成1024字符测试集上的定位准确率从85%降到了70%说明切块太粗导致检索到了错误的文件。如果没有评测我可能根本不会发现这个变化还沉浸在“上下文变长了应该更好”的错觉里。所以我强烈建议任何AI工程上线前先花两天时间搭一个粗糙的评测集后面每一笔改动都有据可依。每次Prompt调整、切换模型、修改检索策略都先在测试集上跑一遍对比分数再决定去留。这个习惯能帮你避免大量无效试错是成本最低的质量保障手段。不要一开始就追求完美评测集粗糙的20条用例就已经能把回退风险挡掉大半。4.4 把AI能力接回日常开发流项目跑通之后我开始盘算怎么把它接入我的日常工作流而不是让它孤零零地躺在脚本库。我做了两个很实用的动作。第一个是做了一个命令行工具。平时开发时遇到不懂的代码我不用切窗口去问通用AI而是直接在当前目录下执行命令工具会自动扫描仓库并回答。单论便捷性这比复制粘贴代码片段高效太多。第二个是接入了当前主流的AI编程工具和IDE插件。这些工具本质上也是走“检索代码片段 模型推理”的路线区别在于它们做了一层更深入的IDE交互。如果我对这套工程链路理解到位了再去使用这类插件就能清楚猜出它们背后的工作原理遇到插件返回错误时也能快速定位。这条路径的价值在于你掌握的是底层能力而不是某个产品按钮。“AI工程”四个字听起来很大拆开了其实就是模型调用、提示词、检索、函数调度、评测这五件事。把它们组合好你会发现不只是做“代码助手”任何垂直领域的AI应用都能套上这套架构。5. 踩坑实录输出不稳定、工具卡死、成本失控最后分享几个我在反复调试中踩过的坑。这些东西不会出现在官方文档里但每一个都真实影响过项目进度。5.1 Prompt输出飘了怎么办项目初期遇到过一种情况同一个问题问两次答案差异非常大。第一次回答很全面第二次答案像是换了一个人。排查之后发现问题出在我把聊天历史全部丢给了模型。历史消息里含有用户之前某个不明确的表达模型被带偏了。解决办法是回答代码问题时不把整段闲聊历史传给模型只传“检索结果 当前问题”。这能大幅提升输出稳定性。其实这就是上下文隔离的思路——关键任务只给它最必要的信息不给它解读错误的机会。5.2 回答太泛、缺少信息量另一个常见的毛病是模型总觉得问题太简单会给出“这一步需要根据项目具体情况来调整”这类废话。原因在于系统Prompt里缺少强制要求。我在系统Prompt里加了一句“回答中必须引用具体的文件名、函数名或代码行。”自此之后输出的信息密度高了很多。想让模型认真干活你得告诉他“拿什么证明你在认真干活”具体的引用就是一种证明。5.3 Agent陷入循环、工具调用停不下来调度器上线第一次测试就出现了Agent连续8次调用同一个搜索函数、参数几乎没变的情况。关键原因是循环里没有“去重记忆”。我修了两处一是在调度逻辑里如果同样的工具调用参数已经出现过一次就不再允许调用二是设置最大循环上限为5次触顶后强制让模型基于现有信息回答禁止再发起新调用。这个限制看起来很粗暴但确实管用。5.4 Token成本失控的排查思路有一段时间我发现账单涨得很快查了日志发现是Embedding调用次数太多了。原因是我把整个文件的每个段落都单独调了一次Embedding接口文件多的时候光这一点就积少成多。优化方案是对文件做合并切块每块保持512个字符左右并且缓存已经算好的向量第二次构建索引直接加载缓存。这项优化让Embedding调用量降低了75%。另外在Agent循环里面每一次函数调用的结果都重新进入模型这块Token消耗也要盯紧。我每次都会打印每条消息的Token数字段丢了心里有数。5.5 一个小技巧日志里永远保留“模型原始返回”这条是我最想强调的经验之一。不管你在上层把逻辑包装得多好日志里一定要保留每个环节模型返回的原始内容尤其是工具调用参数。因为当系统行为诡异的时候绝大多数原因不是逻辑写错了而是模型生成了你意料之外的输出格式。没有原始返回日志你只能猜有了原始返回日志你能一眼看出问题出在哪一层。我在项目里就用这个思路解决了好几个诡异问题算是真正的“低成本排查高收益”技巧。6. 写在最后的一点体会这个项目从头到尾大概花了三周业余时间从零到可用的过程比我想象中顺利也比我想象中琐碎。顺利是因为技术链路已经非常成熟ETS一步到位琐碎是因为每一个环节都需要反复打磨——Prompt改一句评测数据跳几个点又来调检索参数。AI工程其实没有多少神秘之处它就是把“模型能力”这团火用“工程管道”稳下来让火光不至于忽明忽暗。我个人感触最深的一点是不要指望一个全能Prompt解决所有问题也别指望一个最强模型兜住所有场景。AI工程的进步不是靠某一个魔法组件而是靠一个一个小决策——这个任务拆不拆这段上下文怎么给这个工具调用要不要限制这条评测用例该不该加。把这些小决策做对了项目自然就立住了。如果你正在从零做自己的AI项目希望这篇能给你一张足够实的地图少走几段弯路。