LLM App 开发资料地图：从 API 调用到生产系统

LLM App 从 Demo 到生产，不是把同一个聊天框不断加功能，而是依次建立调用契约、交互状态、数据链、评估、观测和成本控制。每一层都对应不同资料，也有不同的退出条件。

第一层：先把调用变成契约

OpenAI API 文档适合学习请求、结构化输出、工具调用、错误处理和当前接口边界。第一份产物不是聊天页面，而是一个能处理超时、空结果、schema 不匹配和取消的服务端函数。

一句话解读：API 层学的不是“如何问模型”，而是如何把不稳定输出关进可验证的程序契约。

第二层：交互不是打字机动画

Vercel AI SDK适合 TypeScript/Next.js 团队研究流式消息、工具状态与模型适配。仓库代码许可为 Apache-2.0。学习时要实现取消、重试、部分结果和工具确认；若产品没有实时交互，这一层可以暂缓。

一句话解读：流式输出的工程价值是让用户看见状态并能中止，而不是让文字显得更像人在输入。

第三层：数据进入模型前要可追踪

Unstructured用于观察复杂文档解析，Ragas用于组织 RAG 评估。先保留解析失败样本，再建立带依据的问题集；如果数据始终是干净结构化字段，不必为了路线完整而引入文档管线。

第四层：评估先于优化

至少保存输入、期望约束、模型输出、人工判断和版本信息。Ragas 的指标是辅助信号，不是业务正确性的替代。这里的学习难点是写标准，而不是调用 evaluator。

第五层：网关只在多模型问题出现后加入

LiteLLM可用于统一接口、路由、预算与日志。其开源部分采用 MIT，同时存在 enterprise 目录和商业能力边界；部署、修改或分发时要核对具体文件，不能把整个产品简单写成 MIT。单模型、小流量应用直接调用供应商通常更简单。

六层地图如何串成项目

以“合同条款提取”为例：先输出固定 schema；再做可取消的上传与处理状态；保留解析失败页；用一组人工标注条款做回归；记录延迟、token、错误和人工修正；只有业务要求跨模型切换时才加网关。每层都有一个可观察失败，学习才不会变成组件收集。

难点会从代码转向运营

前置知识是 HTTP、JSON、一种服务端语言，以及最基本的日志和测试能力。

Demo 阶段最难的是让模型按格式返回；数据阶段最难的是输入质量；上线阶段则要同时回答成本、权限、回滚和人工接管。能写出一次失败属于哪一层，比掌握更多 SDK 更重要。

把学习曲线拆成三段：第一段要求 HTTP、JSON 和一种服务端语言，交付结构化接口与错误样本；第二段要求基本数据处理和测试能力，交付解析记录、引用与评估集；第三段要求日志、鉴权和部署经验，交付预算、告警、回滚与人工接管说明。前一段产物无法复现，就不要靠增加框架跨入下一段。

一句话解读：LLM App 的进阶标志，是失败逐渐从一段文本变成一条能定位、能回滚的运行记录。

24 小时最小路线

先用原生 SDK 完成结构化任务；加入一组真实输入和十几个边界样本；为结果建立人工验收表；记录每次调用的延迟、错误和成本字段；最后只选择一个暴露最明显的缺口继续学习。Vercel AI、Unstructured、Ragas、LiteLLM 不要求在同一轮全部安装。

为了控制范围，可以把它收成四步：先做固定 schema 的条款提取；再加入十五条正常、缺失和冲突样本；第三步把人工判断与版本一起保存并重复运行；第四步只针对最大失败补一层，例如复杂 PDF 才引入解析。每步都应有可提交产物，不能用“读完文档”代替。

资料边界

维护本文时要重新核对在线文档更新、仓库版本与许可证，不能沿用旧日期推断当前接口。

以上链接在 2026-07-15 核验可访问。官方文档和仓库页面能证明公开接口、目录与许可声明，不能证明你的业务数据质量、生产稳定性或实际成本。版本变化快，文章引用必须带日期，示例运行结果则必须来自单独实测。

常见失败是第一天同时接入流式 UI、向量库、评估框架和网关，最后调用报错时无法判断是哪层改变了行为。正确做法是保留一条原生 SDK 基线，每加一层都用同一组输入复跑。涉及医疗、法律或自动执行高风险动作时，这条学习路线也不能替代专业审核与权限设计。

合同提取项目怎样逐层长出来

第一版只接受纯文本，返回条款类型、原文位置和“不确定”字段；这时只需要调用契约。第二版允许上传 PDF，界面显示排队、解析、生成和失败状态，解析错误页要单独保存。第三版加入十五份人工标注合同，用同一组样本比较版本；如果业务要求多个模型兜底，再讨论网关和预算，而不是预先部署。

每层只设置一个新增验收：契约层看 schema 和拒绝，交互层看取消与恢复，数据层看页码和版本，评估层看依据与人工分歧，运营层看延迟、成本和回滚。某一层失败时，先回到该层资料，不把错误统称为“模型效果不好”。这也是资料地图比“推荐技术栈”更有用的地方：它给阅读设置了触发条件。

结论

一张好地图不是告诉你“全部都要学”，而是让你在某层失败时知道该打开哪份资料。先用最小项目把六层画出来，再按失败补课，这比复制一套生产架构更可靠。

启动检查步骤

先把当前项目写成一行输入、一行输出和三类失败；再为每类失败标注所属层。只有某层已经出现真实问题，才从地图中选择对应资料。这样能避免在没有多模型、复杂文档或稳定样本时提前安装网关、解析和评估组件。

下一步就用“合同条款提取”或自己的等价场景建十五行样本表，先跑原生接口；第一轮最大的失败属于哪层，下一次阅读才打开哪份资料。