1. 项目定位与核心思路拆解1.1 这个from scratch到底指什么ai-engineering-from-scratch这个标题第一眼看上去平平无奇但拆开看每个词其实都值得琢磨。AI Engineering不是AI Research也不是调包调参的炼丹术而是把大模型当作一个真实的软件组件用工程化的方法去设计、构建、评估、上线和维护整套系统。from scratch则表示我从零开始不依赖某个现成的AI应用模板也没有直接套用LangChain那样的高层框架而是从HTTP请求、Token管理、Prompt结构、数据管道这些最底层的东西一层层往上搭。说实话现在做AI应用最不缺的就是框架和工具。LangChain、LlamaIndex、Semantic Kernel每个都有自己的生态和抽象方式。但我回头看自己早期使用这些框架的经验发现一个问题框架把太多细节藏起来了。出了问题你根本不知道是模型的问题、检索的问题还是Prompt构造的问题因为你根本没看过中间那层到底发生了什么。所以这个项目的核心思路是尽量少用黑盒抽象把AI应用的关键环节都用自己能理解、能修改、能观测的方式重新实现一遍。哪怕一开始写得粗糙一点但每一步都心里有数。等到理解透了再去用工业级框架你会发现自己能很快定位问题甚至能读懂框架的源码逻辑而不是遇到报错就对着GitHub Issue发呆。1.2 工程视角比算法视角更重要还有一个容易被忽视的点AI工程和传统软件工程有大量重叠但又有本质差异。传统工程讲究确定性——同样的输入必然产生同样的输出单元测试可以穷尽所有分支。而AI工程的核心组件是概率模型同样的Prompt两次调用可能给出不同的答案。这个差异决定了一整套工程实践的调整。我见过不少从算法背景转过来的人研究重心放在模型调优和指标提升上对系统设计、错误处理、数据校验、成本控制这些工程琐事不敏感。也见过传统后端背景的人习惯用确定性思维去要求模型一旦模型输出不稳定就无所适从。真正做AI工程恰恰需要这两种视角的融合你要理解模型的行为逻辑也要能设计出足够鲁棒的系统架构来容忍这种不确定性。这个项目要解决的问题就是帮助像我一样从零开始、但目标是构建生产级AI应用的人建立一套完整的方法论和实操工具箱。它适合三类读者第一类是有软件开发经验、但没用过大模型API的工程师第二类是刚入门AI、被各种框架和概念绕晕的初学者第三类是已经在做AI应用、但觉得效果不稳定、想系统化提升的人。后面我会按照自己走过的路径从环境搭建到实战案例逐步展开。2. 技术栈选型与底层原理拆解2.1 模型访问层的选型方案做AI工程第一个要面对的问题就是怎么让代码用上大模型。市面上的方案很多最直接的就是调用API。选择OpenAI、Claude还是国产模型取决于场景、成本和合规要求。我自己一开始用的是最主流的GPT系列API原因很简单文档全、生态成熟、大多数开源工具优先支持。但这里有一个新手容易忽略的点——你要在架构层面把模型访问封装成独立模块而不是在业务代码里到处直接调用。为什么因为模型供应商随时可能调整价格、模型版本甚至接口规范。你把模型访问集中封装成一个LLMClient类切换模型时只需要改一个文件。我见过太多人把OpenAI的调用直接写在业务函数里后来公司要切换到国内某模型光替换调用点就改了三天还出了不少漏网之鱼。底层原理上所有大模型API本质上就是给你一个文本到文本的接口。你发一段包含系统指令、历史对话、用户问题的文本模型返回一段生成的文本。中间涉及tokenizer切词、上下文窗口管理、采样参数控制这些虽然API封装好了但工程师必须理解否则连为什么我的Prompt被截断了这种基础问题都排查不了。一个基本概念Token不是字符也不是单词是模型词汇表里的最小单位。英文一个单词大约1.3个token中文一个字大约0.6到1.5个token取决于分词方式这就导致同样的语义内容中英文消耗的token数完全不同直接影响到成本和上下文窗口的使用策略。2.2 框架选型先用裸代码再谈抽象框架选型上我的建议可能和主流教程不太一样初期别用重型框架。LangChain确实强大但它的抽象层级太高链式调用藏了太多隐式行为。我刚开始接触LangChain时觉得它很酷写几行代码就能实现一个带记忆的对话机器人。但项目一复杂问题就来了检索结果没有按预期方式拼进Prompt、向量库返回的score不知道怎么理解、Agent的工具调用逻辑到了第四步就开始乱套。直觉告诉我先把这些能力全部用原生代码实现一遍哪怕是简化版。用requests库直接调API自己拼Prompt模板自己管理对话历史自己写一个简单的文本切割函数做检索预处理。这个过程虽然多了几百行代码但它逼着你搞清楚每一层的数据格式和流转逻辑。上手框架之后你能直接读懂框架的源码知道它帮你做了什么更重要的是知道它哪些地方做得不够好。实际上LangChain新版本已经重写成了LangGraph从链式抽象转向了图式状态机抽象这个变化本身就说明了一个问题——过于灵活的链式调用在生产环境中根本不可控图式的节点和边反而更符合真实工程需求。所以我的建议是框架可以选但要选那种让你能看清中间状态的框架不要选把所有逻辑打包成黑盒的框架。2.3 工程化基础设施评估、日志与监控如果只写调用代码那AI应用和普通脚本没有区别。真正让它变成工程的是评估、日志、监控这一整套基础设施。评估是AI工程里最重要也最容易被忽略的部分。传统软件有明确的单元测试但你没法用assert来断言这段话说得对不对。AI工程的评估体系需要分层设计底层是事实性检查答案是否包含幻觉信息中层是格式合规检查是否按照要求输出JSON上层是语义质量评估回答是否完整、是否相关、是否符合用户意图。日志和监控也很关键。传统应用的日志记录的是请求参数和响应状态AI应用的日志还需要记录Prompt全文、模型返回的原始内容、Token消耗、延迟时间、检索命中的文档片段。这些信息是后期排查为什么某个用户问题回答得很差的唯一线索。这个项目的技术选型就是在理解这一整套体系的基础上用最低成本的方式把链路串起来。核心是OpenAI兼容的API接口配合Python的FastAPI做服务封装向量检索先用本地的轻量方案评估先手工构造测试集加上规则校验。等到链路跑通再逐层替换成更工业化的组件。这种循序渐进的搭建方式比一上来就铺全套微服务架构要务实得多。3. 从0到1构建AI应用的核心链路3.1 Prompt Engineering一切效果的源头Prompt是整个AI应用效果的第一决定因素也是新手最常犯错的地方。花了很多时间调模型、调参数最后发现换个Prompt写法效果立刻提升一个档次。Prompt Engineering不是玄学它背后是有逻辑的大模型通过海量文本学习到了一个概率分布你的Prompt本质上是把这个分布引导到特定方向上。什么样的Prompt效果好我的经验是四个关键词角色、任务、约束、示例。角色给模型一个定位比如你是一名资深数据分析师这句话会在语义空间中把模型的行为往专业、严谨的方向拉动。任务描述要具体不要说分析这份数据要说针对给定的销售数据按月份统计增长率并指出异常波动点。约束条件要明确包括输出格式JSON、Markdown表格、长度限制、禁止事项不要猜测数据中没有的信息。示例则是最有效的引导方式对于复杂任务给一个输入输出的样例模型就有了模仿的基础。我见过很多失败的Prompt通病是含糊和冗长。比如让模型写一份报告既不说明读者是谁也不说明报告长度更不说明需要包含哪些关键信息。模型只能靠猜猜的结果自然不稳定。另一个极端是把所有约束都堆在一起没有优先级模型只能按照字面顺序机械执行很容易顾此失彼。我自己维护了一套Prompt版本管理习惯每次修改都记录版本号和改动原因。这看起来笨拙但效果极好——你可以清楚地看到哪些改动提升了效果哪些反而让效果变差。很多AI团队到现在还在用临时改一下、跑一次看结果的方式迭代Prompt这本质上和没有版本管理的代码一样可怕。3.2 RAG链路让模型学会查资料大模型的知识截止时间和幻觉问题注定它不能直接作为生产级知识问答系统的核心。RAGRetrieval-Augmented Generation是目前最常见的解决方案先从知识库中检索与问题相关的文档片段把片段拼进Prompt再让模型基于这些片段生成答案。这样做的好处有两个一是答案有了事实依据幻觉大幅减少二是知识可以随时更新不需要重新训练模型。RAG链路的核心环节是文档解析、文本分块、向量化、建索引、检索、重排、生成。文档解析看起来简单做起来坑很多。PDF有扫描版和文字版之分Word和Markdown的格式也不一样解析出来经常带乱码或多余的页眉页脚。处理这些要先清洗文本去掉无关信息。文本分块是RAG里最容易被忽视的参数块太大检索精度下降块太小上下文信息不完整。我的经验是通用文档用300到500字的块大小配合50字左右的overlap能有效保证语义完整性。向量化负责把文本转化成数学向量让意思相近的文本在向量空间中距离更近。选嵌入模型时要注意上下文长度和维度bge、text-embedding-ada-002这些都是常用选择。检索阶段最基础的是余弦相似度计算找到和用户问题最接近的若干文本块。但这里有个坑有时候相关文本并不在某个块里集中出现而是分散在多个块中这时就需要重排——也就是对检索结果做二次排序让真正有用的信息排到前面。我初始的RAG实现比较简单直接用一个轻量级的本地向量存储自己写余弦相似度计算连专门的向量数据库都没用。数据量在几万条文本以下这种方案完全够用而且排查问题非常直观。后面等数据量上来了再迁移到专门的向量数据库。3.3 Agent与工具调用从问答到做事RAG解决了让模型知道更多知识的问题但模型仍然只能说话不能做事。Agent智能体的概念就是把大模型作为大脑让它能调用外部工具——查数据库、发请求、执行代码、操作API——从而实现真正的自动化任务。从一个简单的例子看用户说帮我查一下上个月北京的气温趋势并画一张图传统问答模型只能给出文字描述而Agent可以拆解这个任务先调用天气API查询数据再用代码生成趋势图最后把图片作为结果返回。这个过程中模型承担的是任务规划和工具选择的角色。实现Agent的基础能力是函数调用。大模型经过针对性训练后能够从用户输入中识别出应该调用哪个函数并提取出所需参数。你需要在调用API时把可用函数的结构化描述函数名、参数列表、功能说明传给模型模型会在合适时机返回一个工具调用指令你的代码再去实际执行对应函数并把结果传回模型生成最终回复。真正的难点在于多步任务的编排。Agent在完成一个任务时可能需要调用五六次工具而且中间某次调用的结果可能和预期不符需要模型自行调整策略。我踩过很多坑比如模型在工具调用中陷入死循环——不断重复调用同一个失败的工具或者在参数提取时反复追问用户同一个问题。解决这类问题需要设置最大迭代次数上限、工具调用容错机制调用失败时把错误信息喂回给模型让它换一种方案以及引入反思环节——让模型在关键节点回顾自己已经做了什么、还需要做什么。从我实际做过的项目来看纯Prompt驱动的Agent在复杂任务上的成功率不够稳定需要配合规则引擎或者微调来兜底。但这并不妨碍Agent本身成为当前AI应用最有想象力的方向——哪怕只是能用它已经能解放大量重复劳动。做这类系统我建议一开始就设计好状态管理记录每一步的输入输出方便排查是模型判断错了还是工具执行出错了。4. 实战搭建一个AI知识助手全流程4.1 场景定义与技术方案这一部分我用自己最近实际完成的一个项目作为案例给一个中小型团队搭建内部知识库问答助手。目标很明确——团队成员上传各种文档助手能基于这些文档的内容回答日常问题比如服务器部署步骤是什么报销流程的线上填写入口在哪里。这个场景非常典型几乎每家公司的内部知识都是碎片化存在的而大模型加上RAG天然适合做这件事。技术方案定了四层结构文档处理层、检索层、生成层、服务层。文档处理层负责接收上传的PDF、Word、Markdown文件解析成纯文本后做清洗和分块检索层把文本块向量化并存入向量存储用户提问时计算相似度召回相关片段生成层把召回的片段和用户问题构造Prompt调用大模型生成答案服务层用FastAPI暴露HTTP接口前端用简单的Web页面接进来。这个方案没有用复杂的微服务架构整个项目就是一个Python进程。原因很简单初期用户量就几十个人高并发不是需求可维护性和可排查性才是。我宁可把精力花在做好日志和评估上而不是搭一套Kubernetes集群来给自己找麻烦。4.2 核心实现与关键代码拆解先从最核心的RAG链路代码开始拆解。文档分块的部分我推荐用递归字符分割器。基本逻辑是先用段落分隔符换行符分割如果某个块还是太大再用句号、逗号逐级切割。这样能最大程度保证语义完整避免一个完整的句子被拦腰截断。from typing import List def recursive_split(text: str, chunk_size: int 500, overlap: int 50) - List[str]: # 按段落粗分割 paragraphs [p.strip() for p in text.split(\n) if p.strip()] chunks [] current_chunk for para in paragraphs: # 如果单段就超长则继续细切 if len(para) chunk_size: if current_chunk: chunks.append(current_chunk) current_chunk # 按句子切分长段落 sentences para.replace(。, 。\n).split(\n) temp for sent in sentences: if len(temp) len(sent) chunk_size: chunks.append(temp) temp sent else: temp sent if temp: chunks.append(temp) elif len(current_chunk) len(para) chunk_size: chunks.append(current_chunk) current_chunk para else: current_chunk para \n if current_chunk: chunks.append(current_chunk) # 处理overlap从每个非首个chunk开头补充前一个chunk末尾的内容 result [] for i, chunk in enumerate(chunks): if i 0: result.append(chunk) else: prev_tail chunks[i - 1][-overlap:] if len(chunks[i - 1]) overlap else chunks[i - 1] result.append(prev_tail chunk) return result这段代码的核心思路很简单优先保证语义完整性再控制块大小。接下来是检索部分。很多人一上来就用向量数据库其实对于少量文本一个简单的类就够用了。核心是计算出每段文本的向量然后用余弦相似度找最近的k个块。import numpy as np class MemoryVectorStore: def __init__(self): self.vectors [] self.texts [] def add(self, text: str, vector: List[float]): self.texts.append(text) self.vectors.append(np.array(vector, dtypenp.float32)) def search(self, query_vector: List[float], top_k: int 5) - List[dict]: qv np.array(query_vector, dtypenp.float32) scores [] for i, vec in enumerate(self.vectors): # 余弦相似度向量点积 / 模长乘积 norm_q np.linalg.norm(qv) norm_d np.linalg.norm(vec) if norm_q 0 or norm_d 0: scores.append(0.0) else: scores.append(np.dot(qv, vec) / (norm_q * norm_d)) # 取top_k top_indices np.argsort(scores)[-top_k:][::-1] return [{text: self.texts[i], score: scores[i]} for i in top_indices]我之前犯过一个错误就是没有做向量归一化就直接比较原始分数。余弦相似度的范围是-1到1但如果向量不对齐不同向量库的score没有可比性。后面我统一在add和search时都做归一化分数才稳定在0.7到0.95这个区间也好设定阈值做下一步截断。Prompt构造是整个链路中另一个容易忽略的环节。检索到多个文本块不能一股脑全拼接进去要设计清晰的格式让模型知道哪些是参考资料、哪些是用户问题。SYSTEM_PROMPT 你是一名企业内部知识助手。 请基于给定的参考资料回答用户问题如果参考资料中没有相关信息请直接回答知识库中暂未找到相关信息不要编造。 参考资料用ref/ref标签包裹多个片段按顺序排列。 ref {context} /ref def build_prompt(query: str, context: str) - str: user_content f用户问题{query}\n请给出准确、简洁的回答。 return [ {role: system, content: SYSTEM_PROMPT.format(contextcontext)}, {role: user, content: user_content} ]这个Prompt看起来简单踩的坑其实不少。最大的问题是模型非常容易被检索片段中的无关内容带偏产生答非所问的回答。解决方式是在Prompt中显著强调只依据参考资料并明确拒绝编造。初始版本我写的是请回答用户问题效果明显差很多——模型如果在检索片段中看到了相似但不直接相关的内容就会顺着那个方向自由发挥。改成如果没有相关资料就明确说明之后幻觉率下降了大半。生成层直接调用OpenAI兼容接口具体的代码就不完整展开了。重点说一下参数设置温度设置为0.1到0.3。做知识问答这种事实性任务我要的是稳定输出不是创意发挥。temperature过高会让同一个问题每次回答的措辞都不一样这在企业内部场景非常减分。4.3 工程落地接口封装与服务化代码跑通之后要按照工程标准做封装和服务化。我用了FastAPI做Web层接口设计为两个一个是文档上传接口POST /documents一个是问答接口POST /query。文档上传接口并非上传完就结束了后台要做完整的数据处理流水线解析文档、清洗文本、分块、向量化、写入向量库。文件格式不同处理路径也不同。PDF文件用pypdf库解析Word用python-docxMarkdown直接读文本。解析完成之后统一走清洗流程去掉无意义行比如只有页码的内容、重复的页眉。问答接口的完整调用链是接收用户问题→生成问题向量→向量库检索→拼装Prompt→调用大模型→返回答案。这里有一点值得注意问题本身的性质会影响检索效果。用户问报销流程直接向量化检索的效果通常还行但如果用户用口语化表达比如我想知道那个住院费用怎么走报销检索效果就会差一些。处理方式有两种一种是做查询改写先用大模型把用户问题改写成更适合检索的关键词组合另一种是直接把原始问题向量化和改写后的问题向量化同时检索然后合并结果。第一种效果好但会增加一次模型调用延时第二种成本低一些。我的项目里先用了第二种效果提升明显而且只多一次嵌入计算的时间基本可忽略。服务层之外我单独写了一层简单的评估脚本。每次Prompt或检索参数的修改都会运行一遍内置的测试集测试集里有几十个标准问题和对应的期望答案要点然后让大模型做裁判判断当前答案是否覆盖了期望要点。这算是AI工程领域常说的LLM-as-judge虽然简略但非常有效至少比这次改动感觉效果还行要靠谱得多。5. 常见问题与排查技巧实录5.1 高频问题的现象、原因与解法我在做这个项目的过程中记录了大量排查笔记这里整理成一张速查表每个问题都是实际遇到过的。现象可能原因排查步骤解决方案答案明显错误且不在知识库范围Prompt中没有强约束只依据参考资料检查Prompt原文是否有明确的拒绝编造指令查看检索片段是否已注入像上面那样加强约束并声明没有就直说用户问题相关的文档内容没有召回分块太大或overlap太小导致语义割裂打印检索命中的top5文本块肉眼查看文章相关性调整块大小至300-500字加入overlap或做查询改写多轮对话中模型忘记了上文没有维护上下文消息历史检查会话消息是否每次完整传递使用消息列表保存历史超出窗口时裁剪中间轮次而非截断末尾接口偶发超时大模型API响应慢或网络不稳定观察延迟监控、查看Token数量、检查重试逻辑设置合理的timeout和重试指数退避对长任务做超时熔断用户上传的PDF内容乱码扫描版PDF无法直接解析检查PDF是否包含文本层接入OCR模块或提示用户提供文字版文档同一问题隔5分钟回答不一样temperature过高或Prompt不稳定查看日志比较前后两次的输入是否一致降低temperature至0.1-0.2如已使用流式排查处理流式输出的拼接逻辑向量检索总是返回不相关的内容嵌入模型和领域不匹配检查测试问题的top1命中条目的相似度分数更换领域匹配的中文嵌入模型或在检索后添加基于关键词的过滤层每一条背后的逻辑都值得展开一下。以模型忘记上文为例很多新手以为是模型记忆容量有限导致但实际上你用的是无状态API每次请求的上下文完全由调用方拼接。问题往往出在对话历史裁剪策略上——中间轮次删得太狠导致模型丢失了关键信息。正确的做法是优先保留最近的N轮对话如果超长就做摘要压缩早期对话而不是简单粗暴截断尾部。接口超时这个问题的坑也很多。默认的requests调用没有设置超时时间一旦模型API服务不稳定线程就会一直挂着极易拖垮整个服务。加上重试机制之后还要注意一个问题不要无脑重试否则每次请求都让模型重新生成一遍成本瞬间翻倍。我的经验是连接超时设5秒读取超时设60秒因为大模型生成速度慢重试最多两次且采用指数退避1秒、2秒、4秒。5.2 独家避坑经验除了上面的表格我还想单独说几条常规文档里不会写的经验。第一日志里一定要记录完整Prompt。很多人以为日志只需要记录调用成功/失败和token数但在AI应用里Prompt是系统的核心状态。如果某一天用户反馈回答质量突然下降你查看日志时发现引用的是旧版本Prompt能立刻定位是版本发布的问题还是模型API行为漂移的问题。模型行为漂移是真实存在的——上游供应商更新模型后同一个Prompt的输出可能悄悄变化。没有Prompt日志这类问题根本无从追踪。第二评估测试集要持续积累。别想着一次性做完评估就不管了。每次发现一个模型回答不好的case就把这个问题加进测试集。这个项目运行三个月后我的测试集从最初的20个问题涨到了80多个每个问题代表一类用户实际遇到的场景。用这个测试集去回归每次Prompt改动能有效防止修一个问题、引出三个新问题的情况。第三不要迷信向量检索的智能。向量检索在语义相似度上确实强大但在专有名词、精确代码、版本号这些场景下往往不如传统的关键词匹配。比如用户问D-2024-038号工单的处理流程向量检索很难精准命中这个编号而一个简单的Elasticsearch精确匹配就能解决。我的做法是混合检索先做关键词过滤让包含特定编号的文档优先再做向量排序。两者结合效果比单独用向量检索稳定很多。6. 扩展方向与个人实践总结6.1 功能扩展的多条路径这个项目跑通之后下一步的方向其实很多。最常见的扩展是加入对话记忆和用户画像。现在的实现是每次问答独立没有上下文关联。加上对话历史存储之后用户就能追问我刚问的那个流程具体怎么操作体验立刻提升一个档次。实现方式是用Redis或数据库保存会话消息请求时加载最近的对话轮次作为上下文Context传入Prompt。另一个扩展方向是引入人工反馈闭环。当用户对某个答案点击不满意时把这个用户问题、模型答案、检索到的文档片段一起记录下来定期人工标注筛选出失败场景加入测试集。这样系统的效果会随着时间推移持续改进而不是上线后逐渐劣化。更进阶的方向包括多Agent协作和任务自动化。比如做一个竞品分析助手由一个规划Agent拆解任务分别调用市场数据检索Agent、文档分析Agent和报告撰写Agent最后汇总生成完整分析报告。这类系统对工程能力要求更高但本质上仍然是状态管理 工具调用 任务编排的组合核心方法论并没有变。6.2 复盘我踩过的坑和最终心得回顾整个项目如果要挑出最重要的几个认知我会这样总结。第一AI工程的第一原则是可观测性优先。不要先追求效果多好先保证每一步都能被看到、被记录、被追溯。一个你能看懂中间过程的系统有100种方法去优化一个黑盒系统出了问题除了重新调一下毫无办法。第二Prompt写得好不好比选哪个模型更重要。我在项目中后期做过一个实验把同一个任务用精心设计的Prompt放在一个相对小的模型上和用随手写的Prompt放在大模型上对比前者在很多场景下效果反而更稳定。Prompt不是写几句话的事它本质上是在引导模型的条件概率分布值得用对待代码的态度去对待它——版本管理、单元测试、持续优化缺一不可。第三工程化的核心不是追求最先进而是追求最可控。一个简单的、完全能被你掌控的系统比一个复杂的、多个环节自己都没弄懂的架构要可靠得多。很多AI项目失败不是模型能力不够而是工程体系太脆弱——改一个参数牵一发动全身出问题找不到原因最终让整个团队疲于奔命。这个项目从零开始我用了大概三周时间跑通核心链路又花了一个多月打磨稳定性和评估体系。如果用一句话总结就是AI应用开发和传统软件开发一样决定项目成败的往往不是某个单点的技术亮点而是整体工程体系的完整度。Prompt、RAG、Agent都是工具真正让你把AI用好的是你对每一个环节的理解和控制能力。最后再分享一个小技巧在做AI应用开发时养成每次改动先记录、再实验、后对比的习惯。很多人拿到大模型API第一反应是想直接写代码希望一口气跑通所有功能。但真正高效的做法是从最小闭环开始——一个最简单的Prompt、一个最小的数据样本、一次最简单的结果对比——然后一点点把复杂度加进去。这样做最大的好处是出了问题能快速定位到究竟是哪一层引入的错误而不是面对一个庞大而无法拆解的系统无从下手。