AI¶

AI Agent 层级¶

Tool Call / Function Calling¶

LLM 擅长语义理解与意图识别，但存在知识时效截止、缺乏确定性计算能力、无法直接操作外部系统等局限。

核心机制：LLM 本身并不直接执行外部代码，而是根据工具定义（Schema）判断调用时机并生成结构化参数（JSON），由宿主程序实际执行工具，再将执行结果（Observation）返回给 LLM 组织最终回答。常见工具如：实时搜索、计算器、数据库查询、业务 API 等。

RAG¶

RAG 的完整流程可分为离线索引与在线推理两个阶段：

离线索引：解析、清洗文档 → 分块（Chunking） → 通过 Embedding 模型向量化 → 存入向量数据库。

在线推理：

1. 检索 (Retrieval)：根据用户问题，从向量数据库中检索语义最相关的 top-K 候选文档片段。
2. 增强 (Augmentation)：将检索到的文档片段与用户问题组合，构建扩展上下文（Context），作为 Prompt 一并送入 LLM。
3. 生成 (Generation)：LLM 基于扩展上下文进行回答，确保答案的准确性和可追溯性。

向量数据库¶

ANN（近似最邻近）算法：

• HNSW（分层导航小世界图）：图索引，查询延迟低，内存占用偏高；高召回常用
• IVF（倒排文件）：聚类划分桶，查询只搜索部分桶；需训练，适合大规模
• PQ（乘积量化）：向量压缩，节省内存、加速距离计算；有损，精度略降

图数据库与知识图谱¶

在 RAG 中，纯向量检索仅关注局部语义相似度，难以捕捉实体间的结构化关联——例如"某人创立了某公司"或"某项目依赖某技术"这类显式关系。图数据库通过构建知识图谱（Knowledge Graph），将离散的文档信息组织为结构化的实体-关系网络，从而帮助 Agent 实现跨文档关联与多跳关系推理。

Neo4j¶

Neo4j 是目前最主流的原生图数据库，采用 LPG（Labeled Property Graph，标签属性图）模型，其核心由四个基本元素构成：

1. 节点 (Node)：表示实体或概念（如 Person、Company、Project）。
2. 标签 (Label)：对节点进行分组分类（类似关系型数据库中"表"的概念，且一个节点可拥有多个标签，如 (:Person:Founder)）。
3. 关系 (Relationship)：连接两个节点的有向边，具有明确的方向和类型（如 -[:FOUNDED]->、-[:DEPENDS_ON]->）。
4. 属性 (Property)：附加在节点或关系上的键值对（Key-Value），用于存储结构化数据（如节点属性 {name: "乔布斯", birth: 1955}，关系属性 {since: 1976}）。

graph LR
    A["(:Person {name: 'Steve Jobs'})"] -->|"[:FOUNDED {since: 1976}]"| B["(:Company {name: 'Apple'})"]
    B -->|"[:PRODUCED]"| C["(:Product {name: 'iPhone'})"]

Cypher 查询语言¶

Cypher 是 Neo4j 原生的声明式图查询语言，采用直观的 ASCII 艺术箭头语法 (节点)-[关系]->(节点) 来描述图模式，使查询逻辑贴近人类对关系的自然表达：

// 查询创立了 Apple 公司的所有人姓名
MATCH (p:Person)-[:FOUNDED]->(c:Company {name: 'Apple'})
RETURN p.name;

// 查找两度关系以内的所有上下游（多跳推理）
MATCH (c:Company {name: 'Apple'})-[*1..2]-(related)
RETURN related;

检索策略¶

                   ┌─────────────┐
                   │    Query    │
                   └──────┬──────┘
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
   向量检索(Vector)   BM25 检索      图谱检索(Graph)
   语义相似度          精确词元匹配    多跳关系遍历
          └───────────────┼───────────────┘
                          ▼
                   RRF 融合排序
                   score = Σ 1/(k + rank)
                          ▼
                   最终排序结果

RRF（Reciprocal Rank Fusion）¶

RRF 是一种无参数的排名融合算法，将多路检索器的排名列表合并为一份最终排序，只依赖排名、不依赖原始分数，因此无需对不同检索器的分数做归一化。

• \(R\)：所有检索器的结果列表集合
• \(k\)：平滑常数（默认 60），用于抑制头部排名过度主导，使排名靠后的文档也能贡献有效分数
• \(\text{rank}_r(d)\)：文档 \(d\) 在检索器 \(r\) 中的排名（从 1 开始）

核心优势： - 无需分数归一化——向量/BM25/Graph 三路分数尺度不同也能直接合并 - 只关心排名——对各检索器的打分分布无假设 - 多路投票效应——被多个检索器同时召回的文档会获得更高的综合分

MMR（Maximal Marginal Relevance）¶

MMR 在保证相关性的同时引入多样性约束，防止检索结果中出现大量语义重复的文档片段：

• \(\text{Sim}(q, d_i)\)：文档 \(d_i\) 与查询 \(q\) 的相关性（如余弦相似度）
• \(\max_{d_j \in S} \text{Sim}(d_i, d_j)\)：文档 \(d_i\) 与已选集合 \(S\) 中最相似文档的相似度
• \(\lambda\)：权衡参数（0~1），\(\lambda\) 越大越偏向相关性，越小越偏向多样性

典型用途：当 top-K 检索结果存在大量近似重复片段时，使用 MMR 重排序可以显著提升上下文覆盖度，让 LLM 获得更全面的参考信息。

Cross-Encoder Rerank¶

Cross-Encoder 是一种精排模型，将 (query, document) 拼接为一个序列送入 Transformer，直接输出相关性得分。相比检索阶段使用的 Bi-Encoder（分别编码 query 和 document 再算相似度），Cross-Encoder 能捕捉更细粒度的交互语义，但计算成本更高。

工业实践：先用向量检索 + BM25 粗排召回 top-K 候选（如 50~100 篇），再用 Cross-Encoder 对候选集精排，取 top-N（如 5~10 篇）送入 LLM，在精度与延迟间取得平衡。

综合以上策略，工业级 RAG 系统的典型架构为：Vector + BM25 + Graph 三路并行召回 → RRF 融合 → MMR 去重 → Cross-Encoder 精排，逐层筛选出最终送入 LLM 的高质量上下文。

记忆¶

LLM 本身是无状态的——每次请求都是独立的。Agent 的"记忆"系统负责在多轮对话和跨会话之间持久化关键信息，让 Agent 具备上下文连贯性和个性化能力。

记忆类型¶

记忆检索与打分¶

当记忆条目积累到一定规模后，需要对召回的记忆进行综合打分排序，决定哪些记忆注入当前上下文：

检索策略选型：

BM25/关键词检索的优势在于精确性和高性能，但缺乏语义理解能力；向量检索擅长语义匹配但精确匹配差。两者互补使用效果最佳。

记忆生命周期管理¶

记忆不是只增不减的——需要冷热分离与分层压缩：高价值信息沉淀为长期记忆，低价值和过时信息逐步遗忘，避免噪音记忆污染召回质量。

当新记忆与已有记忆冲突时，需要选择合适的更新策略：

Mem0¶

Mem0 是一个开源的 Agent 记忆管理框架，提供开箱即用的记忆提取、存储、检索和更新能力，支持自动从对话中识别并持久化关键信息。

核心流程：

用户对话 → LLM 提取记忆事实 → 去重/冲突检测 → 存储（向量库 + 图谱）→ 下次对话时语义检索召回

关键特性：

代码示例：

from mem0 import Memory

m = Memory()

# 添加对话，Mem0 自动提取并存储记忆
m.add("我喜欢用 Python，偏好 FastAPI 做后端", user_id="alice")
m.add("我的项目用的是 PostgreSQL 数据库", user_id="alice")

# 语义检索相关记忆
results = m.search("帮我选一个 ORM 框架", user_id="alice")
# → 召回: "喜欢 Python"、"使用 PostgreSQL"

# 查看用户所有记忆
m.get_all(user_id="alice")

# 记忆更新（自动检测冲突并覆盖）
m.add("我们已经从 PostgreSQL 迁移到 MySQL 了", user_id="alice")
# → 旧记忆 "PostgreSQL" 被更新为 "MySQL"

适用场景：需要快速为 Agent 集成记忆能力、且不想从零搭建记忆管线（提取→去重→存储→召回）的项目。

Agent 规划模式¶

规划模式决定了 Agent 如何把复杂目标拆解为具体行动。常见的主流模式如下：

ReAct (Reasoning + Acting) - 动态循环规划¶

• 核心机制：Thought → Action → Observation 闭环循环。LLM 走一步看一步，根据上一步的执行结果（Observation）动态决定下一步是继续调用工具还是给出最终答复。
• 适用场景：探索性、结果不确定、依赖外部反馈的任务（如查阅多层关联资料、排查报错日志）。
• 工程痛点与解法：
• 容易死循环或早退：仅靠 LLM 自身判断容易陷入重复调用或幻觉提前终止。
• 工程实践：通常在外部宿主程序中增加 最大步数限制（Max Steps），或引入**状态机/校验器（Validator）**强制进行状态流转判断。

Plan-and-Execute - 显式拆解规划¶

• 核心机制：两阶段分离。由 Planner 先完整拆解出子任务列表（Step 1...N），再交由 Executor 逐个执行，最后由 Summarizer 汇总。
• 适用场景：步骤明确的长链路任务（如“编写某主题的行业调研报告并导出为 PDF”）。
• 优缺点：
• 优点：执行成本可控，全局结构清晰，便于展示步骤进度条。
• 缺点：前期规划容易跟不上现实变化。若前置步骤失败，容易引起连锁雪崩（通常需配合 Plan-and-Solve / 动态重规划 Replanner）。

Reflection (Self-Refine) - 反馈式自我演进¶

• 核心机制：Action → Evaluation → Reflection → Retry。Agent 产出初步结果后，由专门的 Evaluator/Critic 检查打分，若不合格则输出修改意见，LLM 据此反思并迭代。
• 适用场景：有明确评价标准、对准确率要求高的任务（如代码生成、SQL 编写、长文本润色）。
• 优缺点：大幅提升单次输出质量，但会带来多倍的延迟（Latency）与 Token 成本消耗。

Tree of Thoughts (ToT) - 搜索式树状规划¶

• 核心机制：将思考过程建模为树结构，每一步生成多个潜在候选思路（分支），借助 BFS（广度优先）/ DFS（深度优先）或评分机制评估各分支价值，并支持回溯（Backtracking）。
• 适用场景：需要全局试错与多步博弈的复杂决策（如 24点游戏、数独、策略制定、算法设计）。
• 优缺点：推理能力上限最高，但调用次数指数级膨胀，通常限于离线高价值场景。

模式对比与选型指南¶

Multi Agent¶

3种模式¶

请求
│
▼
[Retriever] ──▶ [Reranker] ──▶ [Generator] ──▶ [Verifier] ──▶ 响应

                ┌─── Retriever ──┐
                │                │
用户 ──▶ Orchestrator ─── Reranker ───▶ 合成回复
                │                │
                └─── Generator ──┘

        写入              读取
Agent A ──────▶ Blackboard ◀────── Agent C
Agent B ──────▶     │     ◀────── Agent D
                    │
            变更通知（事件）

3 种模式的对比：

通信机制¶

优雅降级¶

场景：Reranker 服务不可用时，系统不应整体崩溃，而应降级继续提供服务。

正常路径：  retrieve → rerank → generate  ✅
降级路径1： retrieve → (skip rerank) → generate  ⚠️ 质量略降
降级路径2： (retrieve timeout) → return cached snippets  ⚠️ 更大降级
兜底路径：  return static fallback message  🆘

三条铁律¶

1. 每条消息带 request_id，处理前先做幂等检查
2. 每个 Agent 暴露 latency + status，不监控等于盲飞
3. 提前设计失败路径，不要等故障发生后再想降级逻辑

常用框架¶

Microsoft Agent Framework/AutoGen 与 CrewAI

LangGraph¶

LangGraph 是 LangChain 团队推出的底层 Agent 编排框架，把 Agent 的执行过程建模为一张有状态的图。与 LangChain 早期的 Chain（线性 DAG）不同，LangGraph 的核心卖点是支持循环——这正是 ReAct 这类「思考 → 调工具 → 观察 → 再思考」模式所需要的。

核心概念¶

最小示例：

from typing import Annotated, TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.checkpoint.memory import InMemorySaver

class State(TypedDict):
    messages: Annotated[list, add_messages]  # 追加而非覆盖

def chatbot(state: State):
    return {"messages": [llm.invoke(state["messages"])]}  # 只返回增量

builder = StateGraph(State)
builder.add_node("chatbot", chatbot)
builder.add_edge(START, "chatbot")
builder.add_edge("chatbot", END)

graph = builder.compile(checkpointer=InMemorySaver())
graph.invoke({"messages": [("user", "hi")]}, {"configurable": {"thread_id": "1"}})

控制流¶

ReAct 循环的典型写法：

from langgraph.prebuilt import ToolNode, tools_condition

builder.add_node("agent", call_model)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", tools_condition)  # 有 tool_calls → "tools"，否则 → END
builder.add_edge("tools", "agent")                       # 形成循环

防止死循环：调用时传 {"recursion_limit": 25}，超过步数会抛出 GraphRecursionError。

中断¶

中断是 LangGraph 实现 Human in the Loop 的机制：图执行到某处暂停，把状态持久化到 Checkpointer，等待人工输入后再从断点继续。必须配置 Checkpointer 和 thread_id，否则无法恢复。

两种方式：

from langgraph.types import interrupt, Command

def human_review(state: State):
    decision = interrupt({"question": "是否执行该操作？", "tool_call": state["tool_call"]})
    if decision == "approve":
        return Command(goto="execute")
    return Command(goto=END)

config = {"configurable": {"thread_id": "order-42"}}
graph.invoke(inputs, config)                 # 执行到 interrupt 处暂停，返回 __interrupt__ 信息
graph.invoke(Command(resume="approve"), config)  # 带着人工决定恢复执行

常见 HITL 模式：

• 审批：高风险工具调用（转账、删库、发邮件）前要求人工确认
• 编辑状态：人工修改模型生成的草稿/参数后再继续
• 补充信息：Agent 缺少关键参数时向用户追问

注意事项：

• 恢复时节点会从头重新执行（而非从 interrupt() 那一行继续），所以 interrupt() 之前的代码要保证幂等，副作用操作放到中断之后
• 同一节点内有多个 interrupt() 时按调用顺序匹配 resume 值，不要把它放在顺序不固定的逻辑里
• 借助 Checkpointer 还能做时间旅行：get_state_history() 查看历史快照，从任意 checkpoint 分叉重跑

编排与持久化¶

Agent 任务是分钟级甚至小时级的，而非毫秒级的普通 RPC 调用，进程重启、模型超时、工具报错都可能发生在任务执行到一半时。因此长链路 Agent 需要一层持久化编排（如 Temporal），提供状态持久化、失败重试、任务队列与定时器等能力，让任务可以从中断处恢复而不是从头重跑。

LangGraph 解决的是单次运行内的流程编排，Temporal 解决的是跨进程、跨重启的任务可靠性，两者互补。

MCP¶

MCP（Model Context Protocol）是 Anthropic 提出的开放协议，用于标准化 LLM 应用与外部工具、数据源之间的连接方式，可以理解为 AI 应用的 "USB-C 接口"。

解决的问题：没有统一协议时，M 个 AI 应用对接 N 个工具需要 M×N 份适配代码；有了 MCP，工具只需实现一次 MCP Server，就能被所有支持 MCP 的应用复用，复杂度降为 M+N。

Tool Call 是模型层面"如何调用工具"的能力，MCP 是工程层面"工具如何被发现和接入"的协议，MCP 底层仍然依赖模型的 Tool Call 能力

架构¶

┌──────────────── Host（Claude Desktop / IDE / Agent）────────────────┐
│   MCP Client ①          MCP Client ②          MCP Client ③          │
└───────┬──────────────────────┬─────────────────────┬────────────────┘
        │ 1:1                  │ 1:1                 │ 1:1
   MCP Server             MCP Server            MCP Server
   (GitHub)               (数据库)               (文件系统)

• Host：用户直接使用的 AI 应用，管理多个 Client
• Client：Host 内部与某个 Server 保持 1:1 连接的组件
• Server：对外暴露能力的轻量服务，封装具体的工具或数据源

通信基于 JSON-RPC 2.0，传输方式有两种：

核心能力¶

注意事项¶

• 上下文膨胀：每个 Tool 的定义都会占用上下文，接入过多 Server 会挤占 Token 并降低工具选择的准确率，应按需加载
• 安全风险：第三方 Server 可能在工具描述或返回结果中植入恶意指令（工具投毒 / 间接 Prompt 注入），接入前需审查来源并控制权限（参见护栏）

Harness¶

Agent = Model + Harness。Harness 指模型之外的整套运行时"脚手架"，负责把一个只会生成文本的 LLM 变成能持续完成任务的 Agent。同一个模型放在不同的 Harness 里，实际效果可能差距很大。

Harness 通常包含：

与 LangGraph 这类框架的区别：框架提供搭建 Agent 的积木，需要自己组装流程；Harness 是开箱即用的完整运行时，典型代表有 Claude Code、Codex CLI、Hermes Agent

Hermes Agent¶

Nous Research 于 2026 年 2 月开源的 Agent Harness，与该团队的 Hermes 系列模型同名但不是一回事。它与模型无关，可接入各类闭源和开源模型，定位是长期运行的个人助手。

主要特点：

• 自我进化的 Skills：从成功完成的任务轨迹中自动沉淀 Skill，并在后续使用中持续改进
• 持久记忆：跨会话记住用户相关的事实，并可检索自己过去的对话
• 多平台接入：通过消息网关连接 Telegram、Discord、Slack 等
• 对开源模型友好：官方主打的卖点之一是更适合搭配开源模型使用

护栏¶

护栏（Guardrails）是在 Agent 执行链路上设置的检查点，用于拦截不安全的输入、输出和操作。按所处位置可分为三层：

输入护栏（Before Agent）¶

• Prompt 注入检测：识别"忽略之前的指令"等越狱话术。除了用户直接输入，更要警惕间接注入——RAG 检索到的文档、网页、工具返回结果中夹带的恶意指令
• 有害内容过滤：暴力、恐怖、违法等内容
• PII 检测：避免敏感信息进入模型或被写入日志、记忆

输出护栏（After Agent）¶

• 有害内容 / PII 过滤：防止模型输出违规内容或泄露敏感信息
• 格式与事实校验：结构化输出校验、幻觉检测（参见评估中的 Faithfulness）

工具调用护栏¶

• 最小权限：只暴露完成任务所需的工具，只读/写权限分开
• 参数校验：校验调用参数是否在白名单或合法范围内
• 人工审批：转账、删除、发邮件等高风险操作前走 Human in the Loop（参见中断）

PII 处理策略¶

检测身份证号、手机号、邮箱、信用卡号等敏感信息后，常见处理方式（以 LangChain PIIMiddleware 为例）：

手机号、身份证号取值空间小，普通哈希可被穷举还原，hash 策略应使用带密钥的 HMAC

实现方式¶

实践中通常分层组合：规则先行拦截明显违规且成本低，模型兜底处理语义层面的风险

评估¶

RAG 系统的评估需要同时衡量检索质量和生成质量两个维度。当前主流方案采用 LLM-as-Judge——用一个 LLM 对另一个 LLM 的输出进行自动化评分，替代人工标注。

核心指标¶

检索质量（评估检索器是否找到了正确且精准的上下文）：

Precision 与 Recall 是此消彼长的关系

生成质量（评估 LLM 是否基于上下文给出了准确且切题的回答）：

调优优先级：Recall → Faithfulness → Precision → Relevancy 检索召回是一切的基础——如果相关文档根本没被检索到，后续的精排和生成都无法挽救。

评估框架：Ragas & DeepEval¶

DeepEval 额外支持 HallucinationMetric 幻觉检测

生产可观测性：Langfuse¶

Langfuse 是开源的 LLM 可观测性平台，专注于生产环境的追踪与监控，与 Ragas/DeepEval 的离线评估形成互补：

与 Ragas/DeepEval 的协作模式：

开发阶段                          生产阶段
┌──────────────────┐            ┌──────────────────┐
│  Ragas/DeepEval  │            │     Langfuse     │
│  离线跑评测集      │            │  追踪生产流量      │
│  验证指标达标      │───上线──→   │  在线评估打分      │
│                  │            │  发现 bad case    │
└──────────────────┘            └────────┬─────────┘
        ▲                                │
        └────── 提取 case 反哺评测集 ──────┘

一句话总结：Ragas/DeepEval 管"上线前够不够好"，Langfuse 管"上线后跑得怎么样"，两者结合形成评估闭环。

成本优化¶

Agent 的 Token 消耗随调用轮数和上下文长度快速放大，常见的降本手段：

• 模型路由：简单任务交给便宜的小模型，只有复杂任务才用大模型
• Prompt Cache：复用重复的前缀，避免每轮都按原价重新计算
• 上下文压缩：对历史对话做摘要、裁剪无关的工具返回结果（参见记忆）
• 限制输出长度：设置 max_tokens，要求结构化的简洁输出
• Batch API：离线、非实时任务走批处理接口，价格通常有较大折扣

模型路由¶

切换模型会导致 Prompt Cache 失效，同一会话内应尽量固定模型

Prompt Cache¶

原理是前缀匹配：只有从头开始完全一致的部分才能命中缓存，中间任何一个字符不同，其后的内容全部失效。这一点类似 MySQL 联合索引的最左前缀原则。

提高命中率的做法：

• 静态内容在前，动态内容在后：按 工具定义 → System Prompt → 固定示例 → 历史对话 → 本轮输入 的顺序组织
• 不要在前缀中放入易变内容：比如 System Prompt 里的当前时间、请求 ID、随机排序的工具列表、键顺序不固定的 JSON
• 对话历史只追加不修改：中途改写或删除早期消息会让后续缓存全部失效
• 注意 TTL：缓存有过期时间（如 Anthropic 默认 5 分钟，每次命中会刷新）。间隔较长的场景可以定时发送轻量请求保活，或者选用更长的 TTL，前提是保活成本低于缓存重建成本

各厂商实现不同：OpenAI 自动缓存，Anthropic 需要通过 cache_control 显式标记缓存断点，且都有最小缓存长度限制。命中情况可通过响应中的 usage 字段（如 cached_tokens / cache_read_input_tokens）观察

Gateway¶

LLM Gateway 位于应用和模型供应商之间，用统一接口屏蔽不同厂商 API 的差异，并集中处理横切关注点：

• 统一接口：以 OpenAI 兼容格式调用各家模型，切换供应商无需改业务代码
• 路由与容灾：负载均衡、失败重试、跨模型/跨供应商 fallback
• 成本管控：虚拟 Key、按团队/项目设置预算与限流、跨供应商成本统计
• 可观测性：统一记录请求日志、延迟、Token 用量
• 附加能力：响应缓存、护栏（参见护栏）

常用方案：

评论