AI Application Foundations

这一页用来补齐学习 AI 应用开发前最容易缺失的基础知识。你不需要先把所有底层原理学完，但需要建立一套稳定的“工程地基”：知道一次请求怎么流动、模型在系统里扮演什么角色、数据怎么进入上下文、结果怎么被校验。

如果你已经熟悉后端开发，可以快速浏览；如果你是刚开始转向 AI 应用开发，建议先读完这一页，再进入 LLM Basics。

先理解 AI 应用不是只有模型

一个 AI 应用通常不是“用户直接问模型”这么简单，而是一条完整链路：

用户输入
  -> 前端收集问题
  -> 后端校验权限和参数
  -> 组织 Prompt 和上下文
  -> 调用模型或工具
  -> 解析和校验输出
  -> 返回结果并记录日志

模型只是链路中的一个能力节点。真正的应用还需要处理数据、权限、错误、延迟、成本、评测和用户反馈。

最小前置知识地图

基础知识	你需要理解什么	为什么重要
HTTP API	请求、响应、状态码、Header、Body	大多数模型能力通过 API 调用
JSON	结构化数据、字段、数组、对象	Prompt 输入、模型输出和工具参数常用 JSON
环境变量	把 API Key、数据库地址等配置放在代码外	避免泄露密钥，方便部署
后端服务	路由、参数校验、错误处理、日志	AI 应用通常需要服务端包一层
数据库	保存用户、文档、对话、反馈和评测结果	让应用从 demo 变成可持续系统
异步任务	文档解析、批量评测、长任务处理	避免用户一直等待
文件处理	读取 PDF、Markdown、网页和 Office 文档	RAG 和知识库系统的入口
权限控制	用户能访问哪些数据、能调用哪些工具	防止数据泄露和危险操作

这些知识不要求一开始很深入，但至少要知道它们在系统里出现在哪里。

HTTP API 基础

大多数模型调用都是一次 HTTP 请求。你至少要理解：

Method：常见是 GET、POST。
URL：请求的接口地址。
Header：放认证信息、内容类型等。
Body：请求正文，通常是 JSON。
Status Code：例如 200 表示成功，401 表示未授权，429 表示限流。

调用模型 API 时，常见结构是：

{
  "model": "model-name",
  "messages": [
    {
      "role": "user",
      "content": "请总结这段文本"
    }
  ]
}

如果请求失败，不要只看“报错了”，要先看状态码、错误信息、请求参数和鉴权配置。

JSON 和 Schema

JSON 是 AI 应用里最常见的数据格式。你会在这些地方用到它：

模型请求参数。
结构化输出。
工具调用参数。
评测数据集。
日志和配置。

Schema 是对 JSON 结构的约束，例如字段名、类型、是否必填、枚举值范围。模型输出 JSON 后，代码应该用 schema 校验，而不是直接相信它。

环境变量和密钥

API Key、数据库连接串、第三方服务 token 不应该写在代码里。它们应该通过环境变量或密钥管理系统注入。

基本原则：

.env 不提交到 Git。
日志中不打印完整密钥。
前端代码不保存服务端 API Key。
不把密钥放进 Prompt 或发给模型。
不同环境使用不同密钥，例如 development、staging、production。

密钥泄露是 AI 应用很常见的安全事故，尤其是在让模型读代码、日志或配置文件时。

后端服务为什么重要

很多新手会直接在前端调用模型 API，这通常不适合生产。后端服务至少负责：

保存 API Key。
校验用户身份和权限。
组装 Prompt 和上下文。
调用模型、检索系统和工具。
记录日志、成本和错误。
对输出做解析和安全检查。

前端负责交互，后端负责边界。这个分工能让系统更安全，也更容易维护。

一次模型调用发生了什么

当你调用一个大模型 API 时，通常会经历这些步骤：

选择模型，例如通用对话模型、Embedding 模型或语音模型。
准备输入，包括 system prompt、用户问题、历史对话和外部上下文。
设置参数，例如 temperature、最大输出长度和输出格式。
发送 HTTP 请求到模型服务。
接收模型返回的文本、JSON 或工具调用请求。
在代码里解析结果，处理失败、重试和日志。

新手最容易忽略的是第 5 步和第 6 步：模型输出不是天然可靠数据，必须经过解析、校验和兜底。

数据流比模型名字更重要

学习 AI 应用时，不要只问“用哪个模型更强”，还要问：

用户输入从哪里来？
哪些内容会进入模型上下文？
私有数据是否经过权限过滤？
模型输出会不会直接触发外部操作？
错误结果怎么发现和回滚？
成本、延迟和失败率在哪里记录？

能画清楚数据流，就已经理解了一半工程问题。

状态、记忆和数据库

AI 应用里的“记忆”通常不是模型自己记住，而是系统保存状态，再在需要时取出来。

常见需要保存的数据：

用户资料和偏好。
历史对话。
上传文档。
文档 chunk 和 embedding。
工具调用记录。
用户反馈和 bad case。
评测结果。

保存不等于每次都塞给模型。正确做法是根据当前任务选择相关部分，放入上下文。

同步任务和异步任务

有些任务可以实时完成，例如一次普通问答。有些任务应该异步处理，例如：

解析大型 PDF。
批量生成 embedding。
跑 1000 条评测。
生成长报告。
扫描整个代码库。

异步任务通常需要队列、任务状态、失败重试和通知机制。否则用户会一直等待，系统也容易超时。

Prompt、上下文和工具的关系

可以把三者这样理解：

名称	作用	例子
Prompt	告诉模型要做什么、按什么规则做	“你是客服质检助手，请按 JSON 输出问题类型”
Context	给模型当前任务所需的信息	用户问题、历史对话、检索到的文档片段
Tool	让模型获取信息或执行动作	搜索文件、查询数据库、创建工单

Prompt 是任务说明，Context 是当前证据，Tool 是外部能力。一个稳定的 AI 应用通常不是靠更长的 Prompt 解决所有问题，而是把三者合理分工。

RAG 需要哪些基础

进入 RAG 之前，先理解下面几个概念会更顺：

文档解析：把 PDF、网页、Markdown 等内容变成可处理文本。
Chunk：把长文档切成适合检索的小片段。
Embedding：把文本转换成向量，方便做语义相似度检索。
Metadata：给每个片段保存来源、标题、页码、权限、时间等信息。
Retrieval：根据用户问题找出相关片段。
Citation：回答时给出引用来源，方便用户验证。

RAG 的本质不是“把资料都塞给模型”，而是“先找到相关资料，再让模型基于资料回答”。

Agent 需要哪些基础

进入 Agent 和 Tool Calling 之前，先理解：

函数参数：工具需要明确的输入字段和类型。
结果回填：工具执行后，要把结果交还给模型继续推理。
操作边界：读操作和写操作风险不同，写操作通常需要确认。
幂等性：重复执行同一个工具调用，不应该造成意外副作用。
审计日志：记录谁在什么时候让模型调用了什么工具。

Agent 的难点不只是“让模型会调用工具”，而是让工具调用可控、可追踪、可回滚。

日志和可观测性

AI 应用的日志不仅要记录“请求成功或失败”，还要能复现一次回答。

建议记录：

用户问题。
Prompt 版本。
模型名称。
检索到的文档片段 id。
工具调用名称和参数摘要。
输出结果。
token、成本、延迟。
错误类型和重试次数。

注意：日志要脱敏，不要保存完整密钥、身份证号、银行卡号等敏感信息。

评测和上线的基础思维

AI 应用上线前至少要回答这些问题：

它在哪些问题上表现好？
它在哪些问题上容易答错？
它答错时会造成什么影响？
如何判断一次修改变好了还是变差了？
用户反馈和 bad case 会存在哪里？
成本和延迟是否在可接受范围内？

没有评测，优化就会变成凭感觉调 Prompt。没有日志，线上问题就很难复现。

建议先做的 5 个小实验

用 Python 或 TypeScript 调一次模型 API，并打印完整请求和响应。
让模型输出 JSON，然后故意制造格式错误，写一个解析失败处理。
把一篇 Markdown 文档切成多个 chunk，并保留标题和来源。
用关键词检索实现一个最小“文档问答前置检索”。
记录 10 次模型调用的输入、输出、耗时和失败原因。

做完这些实验，再学习 Prompt、RAG、Agent 和评测，会明显更平滑。

知识	推荐掌握程度
Git	会分支、提交、查看 diff、回滚自己的改动
SQL	会基本查询、过滤、排序、聚合
Web 后端	会写路由、校验参数、返回 JSON
Docker	会运行服务和管理环境变量
测试	会写单元测试和简单集成测试
日志	会记录请求、错误、耗时和关键业务字段

学习检查点

能画出一个最小 AI 应用的数据流。
能解释 Prompt、Context、Tool 的区别。
能说明为什么模型输出需要代码校验。
能理解 RAG 为什么需要文档切分和检索。
能意识到 Agent 工具调用需要权限、确认和日志。
能说出评测集和 bad case 对迭代的意义。

下一步建议阅读：LLM Basics。