上周帮一个朋友排查一个 AI Agent 项目他邮件里强调了三遍“原型已经做出来了你帮我看看”。打开他的演示地址页面转了三十秒最后给了一条 504。他在语音里很笃定“我本地跑完全没问题上了服务器就不行。”这种对话在我经手 AI 工程项目的这些年里几乎年年重演。很多人把“Notebook 能出结果”当成“原型已可运行”等真正要拿给团队评审、合作伙伴试用甚至先跑一轮小范围验证时才发现根本站不住。一个 AI 项目的可运行原型不是“AI 能回答我的问题”的程度而是换成另一个人按着你留下的说明和代码在没有你现场指导的情况下依然能把核心流程跑通、看到结果、判断出哪里正常哪里异常。这个标准听起来低能做到的 AI 项目却意外地少。下面的内容不聊算法创新专门聊“原型怎么才算真正能跑起来”“用什么标准去验收它”以及我在实际项目里踩过的那些让原型见光死的暗坑。1. “能出结果”不等于“原型可运行”三个层级先对齐很多项目周报里出现“原型已完成”的时候实际状态千差万别。我见过最多的三种状态对应的工程质量差距非常大如果不对齐后续所有讨论都在空转。1.1 能跑的脚本严谨说是“半成品”不是原型Jupyter Notebook 能从上到下执行命令行能返回一段结果这种状态我一般叫“能出结果的脚本”。它的特点是作者本人知道每一个变量的来龙去脉模型 API Key 直接写在环境变量里数据集用的是绝对路径Prompt 写了十几版但只有最新版留在 cell 里。换一个人来运行不知道先跑哪个 cell、不知道哪一段是为了调试临时加的、不知道某个警告是不是致命的。不是说要批判 Notebook它做探索和实验很好。但“能跑”只是原型的必要不充分条件。一个 AI 项目真正能被称为“可运行原型”至少要做到另一条链路成立别人拿代码、拿配置、拿说明可以把这个过程重跑一遍。1.2 Remember: 可运行原型和产品 Demo 也不是一回事有时候团队会把“完成度很高、交互很精致”当成原型验收标准加了一堆登录、权限、后台管理页面模型的部分却只在测试集上手动测过三次。这个方向偏了。第一个可运行原型的目标应该是在可控范围和资源预算内把项目中风险最高的几个未知点验证掉模型在真实场景输入下能不能稳定产生期望类型的输出核心用户流程跑通需要多少延迟、多少成本出错时系统能不能给出可理解、可恢复的反应和其他系统、工具、数据源的接缝是否真的通比如做一个 RAG 问答原型最该验证的未知点是召回质量、回答忠实度、长文档下的耗时。如果一个原型把这些都测清楚了哪怕前台页面素面朝天它都是合格的可运行原型。反之用 Streamlit 搭得再漂亮一追问“换了十篇你不熟悉的文档它还能不能答得靠谱”答不上来那也只是好看的壳。1.3 我用来判断“可运行原型”的一条总原则这是我评审时经常在心里过的那句话把原型交给一个没参与开发的同事他只看 README 和启动脚本能不能在半小时内跑通端到端流程并明确知道哪些现象属于正常、哪些属于异常。这条原则包含四层意思。第一代码和环境要能复现不能只活在作者的电脑里。第二入口路径要清晰启动、配置、依赖都不能靠猜。第三核心流程必须是真的可操作、可观察而不是靠作者在旁边手把手补环境变量。第四边界要明确记录什么输入能做、什么要求超出了原型范围文档里写清楚也是一种负责任。这一条对齐之后接下来才有资格谈大模型选型、Agent 架构、评测指标这些更深的东西。这条没对齐后面所有优化都是在沙地上盖楼。2. 验收一个 AI 原型我通常连环追问六个问题“做成什么样才算做了可运行原型”如果要落到一套可操作的判断框架我的习惯是走到演示机器前不急着操作先像聊天一样问项目负责人六个问题。这六个问题每一个背后都有一次真实项目翻车当教训放给读者的价值远大于一句“原型完成”。2.1 换一台干净机器能不能把项目跑起来这是整个验收清单里的第一道门槛也是绝大多数 AI 原型过不去的一关。我见过太多项目依赖是“当时装的时候试出来的”模型文件散落在 /tmpPython 环境用的是系统解释器还把本地下载好的 embedding 模型路径写在代码里。可运行原型的底线是至少有一个 requirements 文件或 pyproject 锁定文件配置项外置到 .env 或 config 文件并给出模板启动入口收敛成一个 run.sh 或一条 Makefile 命令。我不会苛求一个原型做到持续集成、容器编排但“在干净机器上重建环境并运行”最低要求总要满足。做不到这点说明作者交付的不是项目只是自己的个人记忆。2.2 用户输入边界能被模型“听明白”并得到约束吗AI 原型最容易做成“你问什么它都答答成什么样随缘”。严格说这不是可运行是不可预测。可运行原型要能回答两个问题系统处理什么范围内的输入以及输入越界时会怎样。比如做一个会议纪要点提取工具输入是中文音频转写文本那么输入法默认应该是纯文本超长文档做成截断或分块空文本直接走参数校验错误而不是硬塞给大模型。问“帮我写一封辞职信”的人不是这个工具的目标用户模型会答但产品流程不该承载这种越界请求因为会让结果不可控。2.3 模型的输出质量到底拿什么代表是“感觉不错”还是固定样例集这个问题的典型反例是负责人现场随便问了两三个问题回答还算像样然后说“看挺好的”。这种验证样本量小到连安慰剂效应都不如。判断原型是否可运行至少准备十到二十条覆盖正常、边界、异常场景的固定测试输入每条输入对应一个期望的“结构要求”或“质量底线”。比如让模型抽取结构化字段那至少要跑二十条样本统计字段完整率只要有一到两条给出的 JSON 都不合法系统又没有修正机制它就是一个未达到可用门槛的原型。2.4 模型失败、超时、被限流的时候程序什么表现大模型的不可靠不只体现在回答质量还会体现在服务可用性上。API 超时、限流、敏感内容拦截、返回空内容这些不是小概率事件而是运行中必然轮番出现的事件。原型的评价标准不是“模型尽量不失败”而是“失败能不能被程序感知并且不崩掉”。我见过最简单也最让人头疼的例子代码写着response openai.ChatCompletion.create(...)没设 timeout模型服务卡住整个服务端进程被拖死。客户端一直转圈日志里什么都没留下。这谈不上错误处理只算“裸奔”。原型的正确姿态是调用模型时设置合理超时捕获到异常后返回一个可理解的状态信息给调用方调用失败不要无脑重试十次至少要设重试上限失败日志里要记得记录用到的模型、参数、输入长度哪怕只是一个粗略的 token 级别信息。2.5 性能与成本有没有一个粗略的估算AI 项目原型的延迟和成本常常被忽视到了真实环境中才爆雷。做一个包含三篇长文档的问答工具如果平均响应要一分半钟一次问答烧掉好几万 token这个原型的结论就不应该是“效果不错”而应该是“效果不错但当前形态不可行”。可运行原型建议至少测量三类数据端到端延迟、模型调用 token 消耗、外部依赖调用的耗时占比。不需要精细到做性能剖析但要有一份能写进演示备注的粗算一个用户完成一次核心任务大概几秒、成本大概几厘钱这决定了后面能不能放大到真实用户场景。2.6 项目的“可运行证据”是不是留在仓库里了最后一个问题比代码更像验收这个项目除了源码之外有没有一份 README 说清楚“这是什么”“怎么启动”“有哪些已知边界”有没有留下最近一次成功运行的日志或输出样例有没有一个可以重复运行的 smoke test很多项目源码完好但换个环境就是跑不通。因为能从 head 到产出全部串起来的那份“情景记忆”留在作者脑子里没沉淀到仓库里。可运行原型的本质是把个人经验物化成可复现过程这个动作必须发生在仓库里而不是只发生在作者脑子里。这六个问题像一张网前两个管可复现和输入输出约束中间两个管可靠性和质量证据最后两个管工程代价与知识沉淀。问完这一轮原型是骡子是马基本就现形了。3. 让一个 Notebook 变成可运行原型还差哪些工程动作知道标准之后就得聊补差距。从能出结果的脚本进化到一个撑得住演示和验证的原型通常不需要太重的基础设施但有几件轻量工程动作一定绕不开。3.1 先把交互形态定下来再去铺模型逻辑很多 AI 项目跑偏是因为一开始就在 Notebook 里直接炼 Prompt完全没想好交付给用户“点哪里、输入什么、看到什么”。可运行原型的交互载体无非三类。第一类是最常见也最快的验证 UI用 Gradio 或 Streamlit 做成一个网页对话框适合被人拿来做主观体验评测和产品反馈收集。第二类是 API 形态用 FastAPI 暴露一个接口适合要对接网页、IM、内部系统做集成验证的场景。第三类是 Agent / 自动化任务形态需要定义任务输入、工具调用列表和最终结果格式这时候核心往往不是界面而是任务状态机。交互形态决定代码怎么写。我有一个经验写模型调用之前先把接口签名和请求/响应字段定下来。哪怕是伪代码级别的def run(input_text, context) - AnswerResult也比把全部逻辑塞进一个 prompt 字符串里强得多。定好契约后面评估和测试才好落。3.2 锁依赖、锁配置、锁 Prompt 版本AI 项目里依赖变化导致原型失败往往不是 Python 库升级这种常规问题而是模型本身被“悄悄改变”。比如调用外部大模型没有指定版本号某一天供应商把默认模型切换成新版本输出风格大变原型的表现立刻不一样。所以要在代码里显式写明模型名和版本而不只是写gpt-4o这种没有日期的模糊字符串Prompt 文本建议抽到单独目录管理至少以文件形式按版本保存并记录“某版本 Prompt 在某次评测里的效果”。用配置管理版本比在代码注释里写“上一次效果好别动”可靠得多。依赖层面Python 项目推荐把精确版本导出成 requirements.lockNode 项目要提交 package-lock.json再用安装脚本统一处理。能在容器里跑当然好但对原型来说不是必须能有锁定文件加一键启动脚本已经能堵住大半“环境不一致”的问题。3.3 模型调用的外层要包上“超时、重试、降级”三道保险写 AI 应用和写普通后端应用最大的差异在于你调用的组件不完全受你控制。模型服务可能慢、可能抖动、可能拒绝请求。可靠工具的做法是给模型调用层包一个客户端而不是在业务代码里满天飞地直接调 SDK。一个比较顺手的模式是这样。所有模型访问收敛到一个model_client.py内部统一处理认证、超时、重试和日志。对外只暴露chat()、embed()这类业务语义方法。超时时间根据场景设置普通对话给 30 到 60 秒长文档摘要如果经常跑满明显提示到产品层“这件事做不了”或“请稍后重试”比让用户对着加载状态发呆负责得多。对于 Agent 类项目还要额外控制循环次数和工具调用步数。Agent 一旦进入“模型反复调用工具、每次都失败、还不断重试”的死循环会瞬间消耗掉大量成本和时间。我看过一个赔偿额度评估 Agent因为上游工具返回格式变化Agent 在一个节点上连续调用同一工具 6 次都没成功既不退出也不上报白白烧掉了一批 token。这就是缺少最大迭代步数和异常上报机制的结果。3.4 可观测性不需要上平台但至少留一条“看现场”的路原型阶段不要求上 Prometheus、Grafana 这些监控全家桶但至少要能看到每一次模型调用的输入、输出、耗时和错误。最简单的方式是写一个结构化的 log 工具把关键信息按行打印时间、请求 ID、用户问题摘要模型名称、参数、token 用量调用是否成功、失败原因、耗时多少。这套日志最大的价值在于复现问题。用户说某个输入结果不对如果没有日志只能靠猜有日志可以先看实际发给模型的 Prompt 是什么再看模型返回的原始内容是什么定位到偏差发生在 Prompt 构造、模型生成还是后处理解析。另一个轻量动作是保存最近的输入输出缓存。真实运行时的样本远比手工编的测试样例更有价值它能帮你持续完善评测集。我会把这些原始样本输出到data/debug/目录按日期打一个标记后面想优化时随时回去翻。3.5 一个能跑通核心流程的冒烟测试胜过长篇文档对 AI 原型来说最靠谱的“可运行证据”不是一个大声说“本地可以”而是一段别人能直接执行的冒烟测试。测试不需要写得很全但一定要覆盖一条正常路径和一条最明显的错误路径。test_core_flow 里可以只有三到五个断言。正常输入会检查是否返回成功状态越界输入会检查是否返回可理解的错误码必要时要验证输出里面确实包含关键字段。这样做还有一个额外好处如果模型 API 的返回结构发生破坏性变化冒烟测试会在发布前先把问题暴露出来而不是等演示到一半才现原形。我不建议在原型阶段套很重的测试金字塔。把冒烟测试做成python -m pytest test_smoke.py -x一条命令每个人都能执行这份代码本身就是最生动的“使用说明”。4. 原型看着在跑、一碰就散五个反复出现的“隐藏故障点”这节专门说说那些表面光鲜的 AI 原型都会在哪些地方被拆穿。这些故障点我在评审和帮人抢救项目时反反复复遇到每次原因都类似值得单独写一整节提个醒。4.1 Prompt 看起来周到实则把输入场景假设窄了很多原型在作者设计的几个输入上表现很好是因为 Prompt 暗含了非常强的假设。比如有个合同信息提取原型系统 Prompt 里默认合同至少包含“甲方、乙方、签署日期、金额”四要素。遇到只有一页的简易订单模型为了填结构硬是编造出并不存在的签署日期。上游流程也不知道校验把“模型生成结果”默认当成“事实正确答案”整个演示结果看上去格式工整细看却是胡编。解法是给 Prompt 明确写清楚信息缺失时输出“未找到”不要猜测后处理环节对关键字段做规则校验。合同里没有日期要么留空要么标记异常总之不能让模型替用户“填空”。一个可运行原型的边界确认必须放在程序逻辑里不能寄希望于模型自行理解。4.2 高随机性设置让演示表现时好时坏有的人为了对话“更自然”把 temperature 设到 0.9抽样式任务随机性也会变大。同一个问题上午跑和下午跑风格可能完全不同。演示的时候刚好遇到高质量生成于是一锤子定音“效果很好”。做可运行原型在需要稳定抽取和评测的场景里建议把 temperature 设到 0 或接近 0即使要做创意生成也至少固定随机种子让结果在可接受范围内波动。评测集里的结果要全部留档要能说清楚当前 Prompt 在什么参数下的表现是好的。工程讲究可复现模型生成也不能例外。4.3 没有对“系统提示词被用户内容污染”做防护AI Agent 聊天类原型特别容易踩这个坑用户输入里夹带“忽略之前所有指令”这类注入系统 Prompt 马上被覆盖模型跟着用户节奏跑偏。看起来像是模型的“理解能力问题”其实是应用层没做隔离。原型阶段至少要意识到用户输入永远不可信。系统 Prompt 和用户输入之间要有边界标识长文本要做分段隔离重要的提取或判断任务需要对模型的原始输出做规则校验不能被“模型自称满足要求”蒙混过关。对安全要求高一点的话用户内容不能直接拼进用于工具调用的 Prompt要走单独的角色路径并过滤敏感指令。这个习惯从原型阶段开始培养后面做正式产品会省掉大量返工。4.4 单机可用但部署拓扑不同接口连接就断这是我前面那个 504 朋友的故事的后续。问题根源不是他的代码逻辑而是他的原型调用的外部 Embedding 服务部署在本地网络的一台机器上部署到服务器之后网络访问策略变了外部接口从服务器根本连不通。AI 原型最常见的一个误区是只在本地网络验证所有依赖没考虑换网络后的连通性。即使不上生产至少要把“外网可访问、内网地址、本地 localhost”之间的访问差异写清楚。部署文档里要写明哪些服务是运行在宿主机外的、哪些需要额外的访问授权。若是纯离线场景就要在启动检查中直接探测模型服务地址是否可达并给出明确提示。4.5 把“演示专用路径”当成完整流程隐藏问题积压到评审现场不少人为了演示效果专门设计了几个漂亮的演示引导问题跑起来体验非常顺。等到评审前几天某个真实用户输入路径没走通于是又给系统塞了无数针对性补丁。最后系统变成了两个版本演示版本、实际版本只有作者自己知道区别。这就不是可运行原型是行为艺术。可运行原型的演示数据可以有但演示路径和真实路径应该是同一条代码路径只是数据不同。所有真实输入都必须走同一套入口、同一个 Prompt、同一套兜底逻辑评审时让对方自己从输入框发问而不是点你准备好的快捷按钮。只有这样评审通过才有真实意义。4.6 密钥和敏感数据随手留在仓库里属于隐形事故这个问题和技术不太相关但破坏力最大。原型阶段的仓库存放真实数据库连接串、供应商 API Key、甚至客户脱敏数据在分享链接一多之后基本等于公开泄密。Git 是记历史的哪怕后一次提交把 .env 删了前面的提交里仍然找得到。原型的底线是强制使用 .env 或密钥管理仓库里只放.env.example。如果已经误提交过密钥要用工具遍历历史并将密钥作废再轮换而不是只删一次。它虽然不会让原型“跑不起来”但一定让项目“不敢见人”在可运行这个课题里同样要纳入检查。5. 我给可运行原型做“最后一公里”收尾一份沿用至今的验收清单框架性的问题问完之后真正到发布可运行原型前我会按一套固定动作做收尾。它不是测试金字塔那么重更像上飞机前检查单逐项确认确认完就放行。5.1 先做一次“零知识冷启动”找一个不熟悉项目的同事或者干脆在自己电脑上把代码克隆到全新目录删掉虚拟环境只保留 README 和启动脚本从头执行。执行中不许向原开发者提问。冷启动最容易暴露的问题依次是文档缺依赖、缺少环境变量说明、启动脚本顺序错乱、外部服务依赖没有被正确检查。做完这一步并完成一次完整运行后留存启动日志输出样例作为“可运行证据”放到仓库的 README 里。如果有人质疑“能不能跑”直接丢这份样例过去比解释百句都管用。5.2 用一个固定评测集做一次重复运行整理十五条左右的输入十条常见覆盖主场景三条边界输入两条异常输入存成evaluation/inputs.jsonl。跑一遍把输出结果落盘到evaluation/results.yyyymmdd.jsonl。这个动作同时检验三件事系统能否在无人干预下连续处理所有用例结果结构是否符合约定以及作者能否指认哪些输出质量达标、哪些不达标。这一步如果执行顺利就可以很大方地宣称“原型可运行”因为它有了明确证据和可重复的过程。如果某条输出明显质量崩坏那说明此原型仍停留在“单独看都能用合起来不成立”的幻觉阶段。5.3 用最少的外部协作者做一次“黑盒验证”如果条件允许请一两名不懂技术但了解业务背景的人来做黑盒测试。只给他们一句话这个系统能做什么你的任务是什么请自由使用。他们大概率会输入语法不完整的句子、粘贴大段含特殊符号的文本、上传格式不太符合规范的文件。这些看似“不乖”的用法恰恰能把原型的鲁棒性试出来。完成的标志不是“系统像内部人一样回答正确”而是系统面对这些不完美输入时没有崩溃、没有卡死能给出清晰的边界提示。这个反馈对打磨原型的输入输出设计非常关键往往比问技术专家更容易暴露真实使用问题。5.4 把“带病运行”的已知问题列成清单没有原型的缺陷是零诚实说明缺陷反而比假装完美更专业。我会在仓库里放一个KNOWN_LIMITATIONS.md逐条写明当前不能处理的输入类型、可能产生不可靠结果的场景、外部依赖被强约束在哪个版本、哪些功能只是占位而未落地。这份清单的受益者不只是审阅者。两周后的自己回去看靠它恢复上下文比翻聊天记录快得多其他协作成员也清楚哪些缺陷是已知可接受的哪些是必须在进入下一阶段前修掉的。它让整个项目变得比代码更透明、更好衔接。5.5 打一个可追溯的“原型冻结点”上述动作全部做完就是真正值得打标签的时候。比如prototype-v0.1.0。打标签范围不局限于代码我可以记录这个标签对应的大模型版本、Prompt 文件版本、评测结果文件。即使以后重装电脑、大模型迭代、库升级把行为改变到无法对比拿这个冻结点也能还原出原型当时的真实状态。这一步从形式上看很简单却是从“个人作品”转向“项目资产”的一个小仪式。没有它AI 项目的效果评价就一直停留在“今天调了一下好像变好了”的奇怪状态没法稳定地迈向下一步。我的长期体会是一个 AI 项目做到“可运行原型”衡量的从来不是模型选得有多新而是系统能不能稳定地交付出预期行为以及别人能不能接手续跑。把这个概念用工程手段固定下来它就不再是一句口号而是团队沟通和迭代决策的可靠底座。