AI 工程基础入门到精通

这篇笔记解决什么

这篇是 AI Agent 目录的基础总论。它回答三个问题:

1. AI 工程和传统 Java 后端工程到底差在哪。
2. LLM、Prompt、Embedding、RAG、Tool Calling、MCP、Agent、Memory、Eval 这些概念在工程里各自负责什么。
3. 怎么把这些概念串成一个可部署、可评测、可维护的 Personal Knowledge Agent。

主线:

模型调用 -> 上下文构造 -> 知识检索 -> 工具执行 -> 状态机 -> 记忆 -> 观测评测 -> 产品化

总览图

AI 工程和传统后端的区别

传统后端的核心是“输入确定,代码决定输出”。AI 工程的核心是“模型参与决策,但系统必须控制边界”。

大模型 LLM

LLM 在工程里不是“智能大脑”,而是一个高成本、非确定、可被提示影响的文本/结构生成器。

基本调用结构

sequenceDiagram
    participant API as Backend API
    participant G as Model Gateway
    participant M as LLM Provider
    API->>G: messages + tools + config
    G->>M: normalized request
    M-->>G: stream / tool_call / final text
    G-->>API: normalized response

final class ModelRequest {
    List<Message> messages;      // system / user / assistant / tool
    List<ToolSchema> tools;      // 可选：模型能看到的工具定义
    ModelConfig config;          // model、temperature、maxTokens 等
    String traceId;              // 串起一次完整任务
}

final class ModelResponse {
    String text;                 // 最终文本，可能为空
    List<ToolCall> toolCalls;    // 模型请求执行的工具
    Usage usage;                 // input/output token 和成本
    StopReason stopReason;       // stop / length / tool_call / error
}

常用参数

失败模式

Token 和上下文窗口

Token 是模型处理文本的基本单位。上下文窗口是模型一次能看到的最大 token 数。

flowchart LR
    S[System Prompt] --> C[Context Window]
    H[History] --> C
    R[RAG Evidence] --> C
    T[Tool Results] --> C
    U[User Input] --> C
    C --> M[LLM]

上下文预算

final class ContextPart {
    String type;        // system / user / evidence / tool_result / memory
    String content;     // 实际放入 prompt 的内容
    int tokenEstimate;  // 预算估算
    int priority;       // 数字越大越重要
    String sourceId;    // 来自哪条笔记、工具或记忆
}

Prompt 工程

Prompt 不是玄学,它是“给模型的运行时配置 + 任务说明 + 输出协议”。

Prompt 结构

角色边界
-> 任务目标
-> 可用资料
-> 可用工具
-> 输出格式
-> 禁止行为
-> 失败时怎么说

模板示例

你是一个学习型 AI Agent。
只能基于给定资料回答；资料不足时必须说“不确定”。
回答必须包含：
1. 结论
2. 依据
3. 下一步建议
4. 来源

Prompt 版本管理

Prompt 改动必须能回滚,否则 eval 结果无法解释。

Embedding

Embedding 是把文本变成向量,用于相似度检索。

flowchart TD
    Text["文本"] --> Model["Embedding Model"]
    Model --> Vector["向量"]
    Vector --> Store[("Vector Store")]
    Query["问题"] --> QModel["Embedding Model"]
    QModel --> QVector["问题向量"]
    QVector --> Search["相似度搜索"]
    Store --> Search

关键理解

向量数据库

向量库保存的是“可检索索引”,不是完整知识治理系统。

final class VectorRecord {
    String chunkId;       // 对应原文 chunk
    float[] embedding;    // 向量
    String sourcePath;    // 原始文件路径
    String titlePath;     // 标题层级
    String hash;          // 内容 hash，用于增量更新
    long updatedAt;       // 原文更新时间
}

RAG

RAG 是私有知识问答的核心链路。

好 RAG 的标准

Tool Calling

Tool Calling 让模型请求调用外部工具,但执行权必须在服务端。

flowchart TD
    M["LLM 输出 tool_call"] --> R["Runtime 接收"]
    R --> V["Schema + Permission"]
    V --> T["Tool 执行"]
    T --> Result["tool_result"]
    Result --> M

interface Tool {
    String name();                         // 稳定工具名
    JsonSchema inputSchema();              // 参数 schema
    ToolRiskLevel riskLevel();             // READ / WRITE / DANGEROUS
    ToolResult execute(ToolArgs args);     // 服务端执行，不信任模型
}

安全规则

MCP

MCP 是把工具、资源、提示模板标准化暴露给 Agent 的协议层。

flowchart LR
    Agent[MCP Client / Agent] --> Server[MCP Server]
    Server --> Tools[Tools]
    Server --> Resources[Resources]
    Server --> Prompts[Prompts]

MCP 不是业务系统本身,而是 Agent 生态的适配层。

Agent

Agent 是“模型 + 工具 + 状态 + 控制循环”。

Agent 和普通 Chat 的区别

Memory

Memory 是 Agent 的长期状态,不等于 RAG。

mindmap
  root((Agent Memory))
    用户画像
      偏好
      背景
      禁忌
    项目状态
      当前目标
      已完成
      待办
    事件记忆
      对话
      工具结果
      决策
    反思记忆
      失败原因
      下次策略
    技能记忆
      成功流程
      可复用脚本

记忆操作

错误记忆比没有记忆更危险,所以 memory 必须可审计、可撤销。

AI Gateway

AI Gateway 是模型供应商之上的统一网关。

interface ModelGateway {
    ModelResponse call(ModelRequest request);              // 普通调用
    Stream<ModelEvent> stream(ModelRequest request);        // 流式调用
}

结构化输出

让模型输出 JSON 不等于结构化可靠。必须校验。

flowchart TD
    LLM["LLM Output"] --> Parse["JSON Parse"]
    Parse --> Schema["Schema Validate"]
    Schema --> Business["Business Validate"]
    Business --> Use["Use Result"]
    Parse --> Repair["Ask Repair / Fallback"]

Eval

Eval 是 AI 工程的测试系统。

quadrantChart
    title AI 功能质量象限
    x-axis 低可控 --> 高可控
    y-axis 低正确 --> 高正确
    quadrant-1 可上线
    quadrant-2 答得对但难维护
    quadrant-3 不可用
    quadrant-4 稳定但没价值
    "RAG with citation": [0.82, 0.88]
    "纯 prompt": [0.35, 0.55]
    "无 trace Agent": [0.45, 0.7]
    "带 eval workflow": [0.86, 0.84]

Eval 类型

Observability

Observability 是让 Agent 可复盘。

final class TraceEvent {
    String traceId;       // 一次任务 ID
    String stage;         // retrieve / model / tool / memory / final
    Object input;         // 当前阶段输入
    Object output;        // 当前阶段输出
    long latencyMs;       // 耗时
    String error;         // 错误信息
}

安全

AI 安全不是单独一层,而是贯穿上下文、工具、记忆、输出。

成本和性能

pie title Agent 成本来源
    "LLM 输入 token" : 35
    "LLM 输出 token" : 20
    "Embedding" : 10
    "Rerank" : 10
    "Tool latency" : 15
    "Trace/Eval" : 10

优化手段

部署

生产运维闭环

Agent 上线后最怕两种假象:一是“能回答”被误当成“稳定可用”;二是“eval 通过”被误当成“线上不会退化”。生产运维要把质量、成本、延迟、安全和回滚放到同一个闭环里看。

最小线上配置不要只有 API key,至少要有这些边界:

# agent-runtime.yml = 生产 Agent 的核心运行边界。
model:
  primary: "fast-reasoner"        # 主模型，用于常规任务。
  fallback: "small-safe-model"    # 降级模型，只处理低风险任务。
  timeoutMs: 30000                # 单次模型请求超时。

budget:
  maxInputTokens: 24000           # 单次请求最大输入上下文。
  maxOutputTokens: 4000           # 单次回答最大输出。
  maxCostPerTask: 0.20            # 单任务成本上限，超过要降级或拒绝。

rateLimit:
  perUserPerMinute: 20            # 单用户限流。
  toolCallsPerTask: 12            # 防止 Agent 无限调工具。
  concurrentTasks: 8              # 防止并发把模型/工具打爆。

privacy:
  redactSecrets: true             # trace 落盘前脱敏密钥。
  redactPrivatePaths: true        # 对公开日志隐藏本地私有路径。
  storeRawPrompt: false           # 默认不长期保存完整原始 prompt。

rollback:
  promptVersion: "agent-base-2026-07-06" # 当前 prompt 版本。
  indexVersion: "notes-index-v3"         # 当前检索索引版本。
  toolSchemaVersion: "tools-v2"          # 当前工具 schema 版本。

生产事故排查顺序:

真正能上线的 Agent,必须能回答三个问题:

1. 这次回答为什么贵、慢或错?
2. 哪个版本的 prompt / 模型 / 索引 / 工具 schema 导致变化?
3. 出问题时系统如何降级、拒答、回滚,而不是继续编?

AI 工程分层架构

flowchart TD
    UI["UI / CLI"] --> App["Application Service"]
    App --> Agent["Agent Runtime"]
    Agent --> Context["Context / RAG"]
    Context --> Data["Data Stores"]
    Agent --> Tool["Tool / MCP"]
    Tool --> Data
    Agent --> Model["Model Gateway"]
    Agent --> Trace["Trace / Eval"]

生产级 Agent 请求生命周期

一次 Agent 请求不是“用户问题 -> 调模型 -> 回答”。生产级系统要把它当成一条受控事务:每一层都有输入、输出、失败模式和证据。这样做的价值是:回答错了以后能定位,不会只剩一句“模型不稳定”。

调试时按下面顺序查,不要一上来改 prompt:

从入门到精通路线

核心概念速查

最容易混的概念

RAG 和 Fine-tuning

Tool Calling 和 MCP

Agent 和 Workflow

最小知识闭环

flowchart TD
    Learn["学概念"] --> Draw["画流程图"]
    Draw --> Object["写工程对象"]
    Object --> Demo["做 demo"]
    Demo --> Eval["写 eval"]
    Eval --> Note["整理笔记"]
    Note --> Learn

每学一个概念,都要问:

基础能力验收题库

学完这一篇,不要用“我好像懂了”判断。用下面这张表逐项自测:能画出对象、能说出失败、能写出最小实现,才算进入工程层面。

每个模块至少做一个最小证明:

综合验收案例

用一个问题把基础能力串起来:

“根据我的 Obsidian 笔记,给我生成下一周 Agent 学习计划,并说明依据。”

合格系统不应该直接把问题扔给模型,而应该走下面这条链:

这个案例能同时检验:RAG 是否有引用、Tool 是否受控、Memory 是否克制、Agent 是否有状态、Eval 是否能回归、Trace 是否能定位。做不出这条链,就说明还停留在“会调模型”,没有进入 AI 工程。

精通判断标准

你真正掌握 AI 工程,不是能说出很多框架名,而是能做到:

1. 设计一个 Agent 系统的分层架构。
2. 写出每层核心对象和字段。
3. 知道每层怎么失败。
4. 能为失败设计 trace。
5. 能写固定 eval cases。
6. 能限制工具权限。
7. 能让回答带来源。
8. 能处理资料不足。
9. 能记录和更新长期记忆。
10. 能把系统部署成可维护项目。

建议先记住的主线

LLM 负责生成，不负责事实可靠。
RAG 负责给证据，不负责自动正确。
Tool 负责行动，但必须由服务端控制。
MCP 负责标准化暴露能力，不替代业务系统。
Agent 负责多步任务，但必须由状态机约束。
Memory 负责长期状态，但必须可审计和可撤销。
Eval 负责判断质量，不要凭感觉。
Trace 负责复盘，不要只保存最终答案。

把这条主线吃透,再学任何 Agent 框架都不会跑偏。