OwEn

Docker 学习路线图：镜像到 Compose 的一条主线

Mon, 06 Apr 2026 00:00:00 GMT

Docker 的命令很多，但理解它其实只需要一条主线：

镜像 -> 容器 -> 数据卷 -> 网络 -> Dockerfile -> Compose

这套顺序能解释 80% 的 Docker 使用场景。后续不管是部署、迁移、或者改造容器化流程，都可以沿着这条主线倒推回去。

目前已经整理了第一篇完整入门笔记，后面会继续补更细的实战与排错。

LangGraph 学习路线图：先建图，再进入持久化与中断

Sun, 05 Apr 2026 00:00:00 GMT

LangGraph 的官方材料很强，但也有一个和 LangChain 类似的问题：它更像“能力文档”和“特性索引”，不完全像一条平滑的学习路线。

如果直接按功能点跳着看，很容易出现这几种感觉：

刚理解 StateGraph，后面就已经在谈 interrupt、checkpoint、task。
Memory / Persistence / Time-travel / Durable execution 这几块彼此高度相关，但常常被拆着读。
一些概念第一次出现时只是“先拿来用”，真正的边界要到后面几节才清楚。

所以这组文集我按“先搭一个图，再逐步让它变得像真正能上线的工作流”的顺序整理成下面这条主线：

LangGraph 入门：StateGraph、节点、边、工具与记忆初探 先把最小可运行图搭出来，搞清楚节点、边、状态和工具调用是怎么衔接的。
Persistence：线程、检查点、状态历史与 Store 理解 LangGraph 为什么能回放、恢复、分叉，以及线程和检查点到底保存了什么。
Durable Execution：为什么副作用最好放进 task 把“能保存状态”和“能安全恢复执行”区分开，建立 durable execution 的基本直觉。
Streaming：图为什么能流式吐 token、状态和调试事件 把 stream()/astream() 的几种模式看清楚，理解 LangGraph 的运行时可观测性。
Interrupts：人类介入、审批流与恢复执行 把中断真正放回工作流里看，理解它为什么是 LangGraph 里最重要的能力之一。
Time-travel：重放与分叉 用检查点回溯历史，做调试、回放与分叉试验。
Memory：短期与长期记忆 搞清楚短期 checkpoint 和记忆 Store 的职责边界，以及如何管理上下文膨胀。
Subgraphs：子图复用与持久化策略 让复杂图变成可组合的模块，同时掌握子图的命名空间与持久化模式。
从流程到 Agent：建图思路 先画流程，再拆节点与 state，最后才落到可运行的图。
典型工作模式：Prompt Chaining / Parallel / Routing / Orchestrator / Evaluator 把常见结构收成模板，方便以后按需套用或组合。

如果是第一次系统学 LangGraph，建议按这里的顺序一路往下读：先学“怎么建图”，再学“怎么让图能恢复、能暂停、能观测”，最后再补齐 time-travel、memory 与 agent 模式，理解会顺很多。

Fine Tuning 学习路线图：从微调基础到多模态实战复盘

Sat, 04 Apr 2026 00:00:00 GMT

这组内容来自我在 Obsidian 里连续整理的「微调模型」笔记。原笔记本身覆盖面已经很完整了，但阅读顺序更像“边学边补”，因此会同时出现基础概念、数据集格式、LoRA 原理、LLaMA-Factory 参数和一次实际训练复盘。

整理进博客时，我把它改成了更适合连续学习的 6 篇：

微调入门：为什么需要微调、学习范式与参数更新范围 先建立最小心智：为什么仅靠长上下文或知识库有时不够，微调到底在解决什么问题，以及全参数微调、冻结微调、PEFT 之间的差别。
量化入门：为什么要量化、量化怎么做、常见方法有哪些 这一篇把原笔记里混在一起的量化部分单独抽出来，方便把“微调”和“量化”分开理解，再在后面重新合流到 QLoRA。
微调数据集：Alpaca、ShareGPT、多模态格式与 LLaMA-Factory 接入 如果说微调的上限由模型决定，那下限很大程度上就由数据决定。这一篇重点是数据格式、切分方式，以及 LLaMA-Factory 的 dataset_info 怎么配。
LoRA、QLoRA 与 Qwen2.5-VL：从理论到参数选择 这一篇先回答“LoRA 为什么可行”，再把 LoRA / QLoRA / Qwen2.5-VL 放在一条线上理解，最后落到几个最常调的参数。
小样本多模态微调实战：可视化标注、训练参数与第一次训练 这一篇开始进入真正的实践：数据怎么标、第一轮参数怎么选、Loss 曲线怎么看、为什么模型虽然学到了一点，但还远远不够。
失败复盘与二次优化：system、描述重写与 agent 配合 最后一篇不是“完美收官”，而是一次更像真实项目的复盘：先承认第一次微调不理想，再重构数据、改 system 思路、引入 agent，把问题拆清楚。

这条路线的目的不是把 Fine Tuning 讲成一堆分散名词，而是尽量把它还原成一条真实工作流：

先判断为什么要微调
再理解量化和参数高效微调的约束
然后进入数据、格式和工具链
最后落到一次真实的训练与复盘

如果是第一次系统学这块，建议按这里的顺序读下去。

FastAPI 学习路线图：把教程式切分重新排成一条主线

Fri, 03 Apr 2026 00:00:00 GMT

FastAPI 官方教程本身没有问题，问题更多出在它的组织目标。

它一方面是教程，另一方面又明显承担了“查询手册”的角色，所以经常会出现几种体验：

先抛出一个高级概念，再在后面单独解释
一个功能点单独拆成一章，连续阅读时会显得碎
明明属于同一条请求流的内容，被拆散到不同页面

拿它查资料很舒服，拿它从头系统学，就会有一点“章节非常细、跳跃又频繁”的感觉。

这组文集就是按“构建一个服务时，脑子里会经历的顺序”重新排的。顺序不是跟着目录走，而是跟着一条请求真正流过应用时会经过的层次走。

1. 应用入口、`fastapi dev`、`uvicorn`

先把最小应用跑起来，理解：

app = FastAPI() 到底是什么
fastapi dev 在开发阶段帮了什么
uvicorn 为什么是 FastAPI 常见搭档
pyproject.toml 里的 entrypoint 是什么

2. URL 输入：路径参数与查询参数

把最常见、也最容易混在一起的两类输入先分清：

路径参数负责定位资源
查询参数负责附加过滤和控制条件

3. 请求体与 Pydantic 模型

当输入不再只是 URL 上的几个值，而是一整个 JSON 结构时，就进入请求体和模型层。

这一步会把下面几件事连起来：

请求体建模
多个 body 参数
嵌套模型
示例数据和文档展示

4. 参数来源与校验

把 Query / Path / Body / Cookie / Header 统一成一个心智模型：

参数从哪里来
规则放在哪里
复杂校验怎样接进来

5. 输出层：响应模型、状态码与更新语义

前面主要都在看“请求怎么进来”，这一块开始看“响应怎么出去”：

response_model
返回值过滤
常见类型系统
status_code / tags / description
jsonable_encoder
PUT / PATCH 的更新思路

6. 请求编码切换：表单与文件上传

这一层会把“不是 JSON 的请求”补完整：

Form
File
UploadFile
为什么上传文件一定会牵涉到 multipart/form-data

7. 依赖注入、`yield`、错误处理与安全起步

这一层开始接近“真正可维护的服务”：

Depends
类依赖、子依赖、全局依赖
yield 依赖和资源释放
HTTPException
自定义异常处理器
OAuth2PasswordBearer

8. Bigger Applications：`APIRouter`、多文件结构、生命周期

当单文件应用开始变大，问题就不再是“写不写得出来”，而是“怎么组织”：

APIRouter
include_router
模块划分
lifespan

9. 中间件、CORS、后台任务

这是“路由之外还有什么东西会围绕请求工作”的一层：

中间件的请求/响应包裹关系
CORS 为什么是浏览器问题，不是 FastAPI 特有问题
BackgroundTasks 什么时候合适

10. 测试、CLI、手动运行与 Workers

最后把“怎么运行”和“怎么验证”补齐：

TestClient
pytest
fastapi dev
fastapi run
uvicorn main:app
--reload
--workers

这条顺序跟官方目录不一样，但更接近第一次系统学 FastAPI 时真正需要的顺序：

先把服务跑起来
再理解请求从哪里进来
再理解响应怎么出去
再补依赖、错误、安全
最后进入工程化和部署

claude-code的源码拆解学习

Fri, 03 Apr 2026 00:00:00 GMT

一、总介绍

Claude Code 的意外泄露，给了广大 AI 学习者一个非常好的借鉴蓝本。这里，我们按照项目 learn-claude-code（shareAI Lab, MIT 协议）的顺序，一步一步看怎么从简单到复杂，搭建一个 Claude Code 风格的 Agent。

这个项目的核心论点是：

智能来自模型（model），但让智能变成现实的是 harness（线束/运行环境）。

模型能推理能编码，但它只能产出文本——碰不到文件系统、不能跑命令、不能读报错。harness 负责把模型产出的文本变成真实世界的动作，再把结果喂回去。二者配合，才是完整的 AI Agent。

项目把 Claude Code 拆成 12 个递进 session（s01 到 s12），每个 session 都是一个独立可运行的 Python 脚本，代码量从 ~4KB 增长到 ~36KB。

二、s01–s12

1. s01：最小 Agent 循环——"一个循环 + 一个 Bash，就是一个 Agent"

s01 是整个项目的起点。它演示了一个事实：不到 30 行核心代码，就能跑起一个可以操作你文件的 AI Agent。

(1) 依赖与环境

from anthropic import Anthropic
from dotenv import load_dotenv

load_dotenv(override=True)

if os.getenv("ANTHROPIC_BASE_URL"):
    os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)

client = Anthropic(base_url=os.getenv("ANTHROPIC_BASE_URL"))
MODEL = os.environ["MODEL_ID"]

只需要 3 个第三方包：anthropic（调用 Claude API）、python-dotenv（加载 .env 里的 API key）、pyyaml（后续 session 用到）。

注意第 47 行的 os.environ.pop("ANTHROPIC_AUTH_TOKEN", None)：当设置了 ANTHROPIC_BASE_URL（使用第三方兼容 API）时，删除从环境继承的 auth token，避免认证冲突。

这里需要补充一下 claude 请求格式与 oepnai 的不同。先看一下相同点吧，底层通信都是基于 HTTP 的RESTful API；数据交换格式都是 JSON；都抽象了基于 role（角色）和 content（内容）的对话历史数组模式（而不是文本补全）；都支持SSE协议来最大程度降低TTFB；原生支持函数调用（Function Calling / Tool Use）和多模态（视觉）输入。

关键区别就在一下几个点：

O将system放在对话的第一个位置作为一个特殊角色，而C将system剥离数组，当成了一个顶级参数，与model、message同级。
C严格遵循user和assistant交替出现的规则，O则相对宽容允许连续出现。
比较重要的一点，O在有工具调用的时候在 assistant 消息中返回 tool_calls 数组，提交工具执行结果时，需要新增一条角色为 tool 的消息，并通过 tool_call_id 与之前的调用关联；C调用工具时，内容（content）会变成一个数组，其中包含类型为 tool_use 的对象，提交工具结果时，需要新增一条角色为 user（注意是 user，而不是单独的 tool 角色）的消息，其内容为类型为 tool_result 的对象，并附带 tool_use_id。
鉴权模式，O是Bearer Token，C是自定义的，强制要求声明 API 版本。

来看一下标准带工具调用情况下两者的JSON差距，前面为O后面为C。首先是工具声明，前者嵌套更深严格区分function，后者结构更扁平，参数叫 input_schema：

"tools": [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "获取指定城市的天气",
      "parameters": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        }
      }
    }
  }
]

"tools": [
  {
    "name": "get_weather",
    "description": "获取指定城市的天气",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": { "type": "string" }
      }
    }
  }
]

然后是模型决定工具，这里有巨大差异，OpenAI 传回的是字符串格式的 JSON，需要你自己 json.loads()；而 Claude 直接传回了解析好的 JSON 对象：

{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_abc123",
      "type": "function",
      "function": {
        "name": "get_weather",
        "arguments": "{\"location\": \"Wuhan\"}" 
      }
    }
  ]
}

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "好的，我来帮你查一下。"
    },
    {
      "type": "tool_use",
      "id": "toolu_xyz789",
      "name": "get_weather",
      "input": {
        "location": "Wuhan"
      }
    }
  ]
}

最终将工具执行结果返回模型的时候，前者必须新增一个专属的 role: "tool"，后者则是必须作为 role: "user" 消息发送，并在 content 数组里标记 tool_result（这也是两者要互相转化最麻烦的一点）：

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "{\"temperature\": 25, \"condition\": \"Sunny\"}"
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_xyz789",
      "content": "{\"temperature\": 25, \"condition\": \"Sunny\"}"
    }
  ]
}

如果要在底层打通两套接口，路由层需要重点处理：OpenAI 的 role: "tool" 必须被强制映射为 Claude 的 role: "user" + type: "tool_result" 结构。

(2) 系统提示词——赋予模型"身份"

SYSTEM = f"You are a coding agent at {os.getcwd()}. Use bash to solve tasks. Act, don't explain."

这行是整个 harness 的入口。os.getcwd() 被直接拼进字符串——模型收到的不是函数调用，而是当前目录的真实路径（如 /home/ubuntu/owen）。模型不知道自己在哪台机器上，它只知道 prompt 里写了这个路径，然后基于此"推理"应该执行什么命令。

权限从哪来？ 权限来自你运行 python agents/s01_agent_loop.py 时你自己的 shell。Python 进程继承了你的所有权限——能读写的文件、能执行的命令，和你在终端敲命令是一样的。

(3) 工具定义——模型唯一能"调用"的东西

TOOLS = [{
    "name": "bash",
    "description": "Run a shell command.",
    "input_schema": {
        "type": "object",
        "properties": {"command": {"type": "string"}},
        "required": ["command"],
    },
}]

工具定义不是 Python 函数，只是一段 JSON Schema 描述。发给模型后，模型会输出类似这样的 JSON：

{
  "type": "tool_use",
  "name": "bash",
  "id": "toolu_01xxx",
  "input": {"command": "ls"}
}

模型只负责"说要做什么"。真正执行的是 harness。 模型产生意图，harness 赋予能力。

(4) 工具执行——`run_bash`

def run_bash(command: str) -> str:
    dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
    if any(d in command for d in dangerous):
        return "Error: Dangerous command blocked"
    try:
        r = subprocess.run(
            command, shell=True, cwd=os.getcwd(),
            capture_output=True, text=True, timeout=120
        )
        out = (r.stdout + r.stderr).strip()
        return out[:50000] if out else "(no output)"
    except subprocess.TimeoutExpired:
        return "Error: Timeout (120s)"
    except (FileNotFoundError, OSError) as e:
        return f"Error: {e}"

关键点：

subprocess.run(command, shell=True, cwd=os.getcwd()) — 模型输出的字符串被直接交给 shell 执行。这就是为什么 AI 可以操作文件：本质上和你自己在终端敲命令一样。
危险命令拦截 — 硬编码了 5 条关键词，在命令到达 subprocess 之前做简单过滤。这非常粗糙（比如 rm -rf ~/* 就绕过去了），真实的 Claude Code 有完整的权限系统和 hooks 机制。
输出截断 — out[:50000] 防止大量输出撑爆 token 预算（后面 s06 会专门处理上下文压缩）。
超时保护 — timeout=120，防止命令卡死。

(5) 核心循环——整个 s01 的灵魂

def agent_loop(messages: list):
    while True:
        # 1. 将消息和工具定义一起发给 LLM
        response = client.messages.create(
            model=MODEL, system=SYSTEM, messages=messages,
            tools=TOOLS, max_tokens=8000,
        )

        # 2. 追加 assistant 消息
        messages.append({"role": "assistant", "content": response.content})

        # 3. 如果模型没有调用工具，结束循环
        if response.stop_reason != "tool_use":
            return

        # 4. 执行每个工具调用，收集结果
        results = []
        for block in response.content:
            if block.type == "tool_use":
                print(f"\033[33m$ {block.input['command']}\033[0m")
                output = run_bash(block.input["command"])
                print(output[:200])
                results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": output,
                })

        # 5. 把工具结果作为 user 消息追加，回到步骤 1
        messages.append({"role": "user", "content": results})

流程图：

+--------+      +-------+      +---------+
|  User  | ---> |  LLM  | ---> |  Tool   |
| prompt |      |       |      | execute |
+--------+      +---+---+      +----+----+
                    ^                |
                    |   tool_result  |
                    +----------------+
                    (loop until stop_reason != "tool_use")

循环不变式：模型只要还在返回 stop_reason == "tool_use"，就把工具结果塞回 messages 再问一次；一旦返回 stop_reason == "end_turn"，循环终止。

一个设计细节：工具执行结果用 role: "user" 而不是 role: "tool" 返回。这是 Anthropic 消息协议的约定——工具结果被追加为 user role 的消息（因为它是"外部输入"，不是模型自己生成的）。

(6) 交互循环——REPL 外壳

if __name__ == "__main__":
    history = []
    while True:
        try:
            query = input("\033[36ms01 >> \033[0m")
        except (EOFError, KeyboardInterrupt):
            break
        if query.strip().lower() in ("q", "exit", ""):
            break
        history.append({"role": "user", "content": query})
        agent_loop(history)
        # 打印最终响应
        response_content = history[-1]["content"]
        if isinstance(response_content, list):
            for block in response_content:
                if hasattr(block, "text"):
                    print(block.text)

外层是一个简单的 while True REPL（Read-Eval-Print Loop）。history 在所有轮次中持续增长——上一次问题和模型的回答（含所有工具调用）都在里面，所以模型能"记住"上下文。

(7) macOS UTF-8 输入补丁

try:
    import readline
    # #143 UTF-8 backspace fix for macOS libedit
    readline.parse_and_bind('set bind-tty-special-chars off')
    readline.parse_and_bind('set input-meta on')
    readline.parse_and_bind('set output-meta on')
    readline.parse_and_bind('set convert-meta off')
    readline.parse_and_bind('set enable-meta-keybindings on')
except ImportError:
    pass

macOS 默认用 libedit（而非 GNU readline），处理中文、日文等多字节字符时退格键可能只删半个字符导致乱码。这 6 行配置切换 libedit 的字符处理模式，让 UTF-8 输入正常。#143 引用对应的 GitHub issue/PR 编号。Linux 上 Python 自带 GNU readline，这段代码无害但不起作用。

(8) 运行

cd learn-claude-code
python agents/s01_agent_loop.py

内置的测试 prompt：

Create a file called hello.py that prints "Hello, World!"
List all Python files in this directory
What is the current git branch?
Create a directory called test_output and write 3 files in it

关键洞察

s01 暴露了 AI Agent 的本质结构：

模型 = 产生意图（"我想执行 ls"）
harness = 赋予能力（Python 调用 subprocess.run）
权限 = 在 harness 层控制（危险命令拦截、用户确认）

模型完全不知道自己在哪台机器上，它只是收到了一段带有当前目录路径的 system prompt，然后基于这段文本进行"推理"。它说的所有话都是文本——是 harness 把文本变成了真实世界的动作。

这就是整个项目的核心论点：智能来自模型，但让智能变成现实的是 harness。后面 11 个章节都在这个循环上叠加机制（任务规划、子 Agent、技能系统、上下文压缩、后台任务、团队协作……），但 while True 这层循环本身始终不变。

2. s02：工具分发——"加工具不改循环"

s02 的核心变化就一句话：工具从 1 个变成 4 个，循环代码一行没动。

+--------+      +-------+      +------------------+
|  User  | ---> |  LLM  | ---> | Tool Dispatch    |
| prompt |      |       |      | {                |
+--------+      +---+---+      |   bash: run_bash |
                    ^           |   read: run_read |
                    |           |   write: run_wr  |
                    +-----------+   edit: run_edit |
                    tool_result | }                |
                                +------------------+

(1) 路径沙箱——`safe_path`

这是 s02 最重要的新增基础设施。s01 的 bash 对文件系统没有边界，cat ~/.ssh/id_rsa 也能执行。s02 给文件工具加了一道门：

WORKDIR = Path.cwd()

def safe_path(p: str) -> Path:
    path = (WORKDIR / p).resolve()
    if not path.is_relative_to(WORKDIR):
        raise ValueError(f"Path escapes workspace: {p}")
    return path

三步检查：

WORKDIR / p — 把输入路径拼到工作目录下
.resolve() — 解析掉所有 .. 和符号链接，得到绝对路径
is_relative_to(WORKDIR) — 检查解析后的路径是否还在工作目录内

../../etc/passwd → resolve 后变成 /etc/passwd → 不在 /home/ubuntu/owen 下 → 抛异常。

但这个沙箱有一个大漏洞：它只保护了 read_file / write_file / edit_file，不保护 bash。 bash 工具直接走 subprocess.run(command, shell=True)，模型说 cat ~/.ssh/id_rsa.pub 就能读，说 cat /etc/passwd 也行。实际测试中，模型通过 bash 读到了 ~/.ssh/ 下的公钥——safe_path 在这里完全被绕过了。

这是故意留的设计张力：bash 给了模型最大灵活性，但也给了最大攻击面。后面 s06（权限系统）和 s12（worktree 隔离）会逐步解决这个问题。这里先记住一个原则：只要有不受限的 bash，任何文件级沙箱都有后门。

(2) 三个新工具的函数实现

read_file — 读文件，支持行数限制：

def run_read(path: str, limit: int = None) -> str:
    text = safe_path(path).read_text()
    lines = text.splitlines()
    if limit and limit < len(lines):
        lines = lines[:limit] + [f"... ({len(lines) - limit} more lines)"]
    return "\n".join(lines)[:50000]

比 cat 好在：可控行数、不会截断半个 UTF-8 字符、告知被截掉的行数。

write_file — 写文件，自动创建父目录：

def run_write(path: str, content: str) -> str:
    fp = safe_path(path)
    fp.parent.mkdir(parents=True, exist_ok=True)
    fp.write_text(content)
    return f"Wrote {len(content)} bytes to {path}"

mkdir(parents=True, exist_ok=True) 省去了先 mkdir -p 再写的两步操作。返回值直接给 LLM 看写入结果，形成闭环。

edit_file — 精确文本替换（这是 Claude Code 实际使用的方式，而非 sed/awk）：

def run_edit(path: str, old_text: str, new_text: str) -> str:
    fp = safe_path(path)
    content = fp.read_text()
    if old_text not in content:
        return f"Error: Text not found in {path}"
    fp.write_text(content.replace(old_text, new_text, 1))
    return f"Edited {path}"

注意 replace(old_text, new_text, 1) 中的 1——只替换第一次出现。因为如果 LLM 传了一个太短的 old_text（比如单个变量名），全量替换会改掉不该改的地方。真正的 Claude Code 的 Edit 工具也做单次替换，且要求 old_string 在文件中唯一，否则报错。

(3) 分发映射——Dispatch Map

这是 s02 的架构亮点。工具名到处理函数的映射不用 if/elif 链，而用字典：

TOOL_HANDLERS = {
    "bash":       lambda **kw: run_bash(kw["command"]),
    "read_file":  lambda **kw: run_read(kw["path"], kw.get("limit")),
    "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
    "edit_file":  lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
}

每个 lambda 做了同一件事：从模型返回的 kwargs 中提取自己需要的参数，传给具体函数。这是一种适配器模式——模型返回的是扁平的 {"path": "x", "content": "y"}，而每个函数要的参数名和数量不同。lambda 完成了"模型输出 → 函数签名"的映射。

后续 session 加新工具就是在这个字典里加一行，循环完全不用动。

一个容易忽略的点：TOOL_HANDLERS 和 TOOLS 是两个不同的东西。

TOOL_HANDLERS = {          # 执行层 — 留在 harness 本地，Python dict
    "bash":  lambda **kw: run_bash(kw["command"]),
    ...
}

TOOLS = [{...}, {...}]     # 定义层 — 发给模型，JSON Schema 数组

	TOOLS	TOOL_HANDLERS
是什么	JSON Schema 数组	Python dict
发到哪里	发给模型（API 的 `tools` 参数）	留在本地，模型永远看不到
作用	告诉模型"你可以调什么"	告诉 Python"调了之后执行哪个函数"
内容的性质	文本描述 + 参数 schema	lambda / 函数引用

s01 没有这个分离——只有一个 TOOLS，执行是硬编码的。s02 引入 dispatch map 时就把二者拆开了，s03 只是照惯例各加了一行。这个分离是 harness 设计的核心模式：给模型看的和本地执行的是两套东西，用名字做桥接。

(4) 循环中的分发调用

对比 s01 和 s02 的循环体变化：

# s01 — 硬编码只调 bash
for block in response.content:
    if block.type == "tool_use":
        output = run_bash(block.input["command"])

# s02 — 字典分发，任意工具
for block in response.content:
    if block.type == "tool_use":
        handler = TOOL_HANDLERS.get(block.name)
        output = handler(**block.input) if handler else f"Unknown tool: {block.name}"

TOOL_HANDLERS.get(block.name) 一次查找替代了 s01 的硬编码。如果模型幻觉了一个不存在的工具名，返回 "Unknown tool" 让模型自行纠正。

(5) 工具定义——JSON Schema 数组

TOOLS = [
    {"name": "bash", "description": "Run a shell command.",
     "input_schema": {...}},
    {"name": "read_file", "description": "Read file contents.",
     "input_schema": {"type": "object",
         "properties": {"path": {"type": "string"}, "limit": {"type": "integer"}},
         "required": ["path"]}},
    {"name": "write_file", "description": "Write content to file.",
     "input_schema": {"type": "object",
         "properties": {"path": {"type": "string"}, "content": {"type": "string"}},
         "required": ["path", "content"]}},
    {"name": "edit_file", "description": "Replace exact text in file.",
     "input_schema": {"type": "object",
         "properties": {"path": {"type": "string"}, "old_text": {"type": "string"}, "new_text": {"type": "string"}},
         "required": ["path", "old_text", "new_text"]}},
]

每个工具都是自描述的——模型看 description 知道什么时候用它，看 input_schema 知道它需要什么参数。这个数组就是模型和真实世界的唯一接口。

(6) s01 → s02 变化总结

组件	s01	s02
工具数量	1 (bash)	4 (bash + read/write/edit)
工具调用方式	硬编码 `run_bash()`	`TOOL_HANDLERS` 字典分发
路径安全	无（bash 任意路径）	`safe_path()` 沙箱
Agent loop	`while True` + `stop_reason`	完全相同

(7) 运行

python agents/s02_tool_use.py

推荐测试 prompt：

Read the file requirements.txt
Create a file called greet.py with a greet(name) function
Edit greet.py to add a docstring to the function
Read greet.py to verify the edit worked

关键洞察

s02 证明了 harness 设计中最重要的一条原则：工具系统和循环是正交的。 循环只负责"调 API → 看 stop_reason → 执行工具 → 塞回结果"，它不关心有多少工具、每个工具做什么。加工具 = 加 handler + 加 schema，别碰循环。

另外，safe_path 这种工具层沙箱比 bash 层的字符串过滤可靠得多——在代码层面精确控制边界，而不是靠关键词匹配去猜攻击。后续 session 的安全机制都遵循这个思路：权限控制在 harness 层，不在 prompt 里。

3. s03：TodoWrite——"没有计划的 Agent 走哪算哪"

s03 解决一个问题：GPT/Claude 做多步任务时，做到一半就忘了自己要干什么。对话越长越严重——前面列的计划被后续工具输出淹没了，模型开始即兴发挥。

解决方案：让模型自己写待办清单，harness 负责两件事：(1) 记录状态 (2) 忘了就催。

(1) TodoManager——有状态的待办管理器

这是 s03 的核心数据结构。之前的工具函数都是无状态的（读就是读、写就是写），而 TodoManager 是一个 Python 对象，在会话期间保持状态：

class TodoManager:
    def __init__(self):
        self.items = []           # 内存中的 todo 列表，整个会话存活

    def update(self, items: list) -> str:
        if len(items) > 20:
            raise ValueError("Max 20 todos allowed")
        validated = []
        in_progress_count = 0
        for i, item in enumerate(items):
            text = str(item.get("text", "")).strip()
            status = str(item.get("status", "pending")).lower()
            item_id = str(item.get("id", str(i + 1)))
            if not text:
                raise ValueError(f"Item {item_id}: text required")
            if status not in ("pending", "in_progress", "completed"):
                raise ValueError(f"Item {item_id}: invalid status '{status}'")
            if status == "in_progress":
                in_progress_count += 1
            validated.append({"id": item_id, "text": text, "status": status})
        if in_progress_count > 1:
            raise ValueError("Only one task can be in_progress at a time")
        self.items = validated
        return self.render()

    def render(self) -> str:
        if not self.items:
            return "No todos."
        lines = []
        for item in self.items:
            marker = {"pending": "[ ]", "in_progress": "[>]", "completed": "[x]"}[item["status"]]
            lines.append(f"{marker} #{item['id']}: {item['text']}")
        done = sum(1 for t in self.items if t["status"] == "completed")
        lines.append(f"\n({done}/{len(self.items)} completed)")
        return "\n".join(lines)

update() 做了严格的输入校验：

数量限制 — 最多 20 条，防止模型滥写
状态白名单 — 只能是 pending / in_progress / completed 三选一
唯一 in_progress — 同时只能有一个任务在做。这条规则很关键——它强制模型保持顺序聚焦，不能同时开三个坑
必填 text — 空任务没有意义

render() 把结构化数据转成模型能读懂的文本：

[ ] #1: Fix authentication bug
[>] #2: Add dark mode toggle        ← 当前正在做
[ ] #3: Write tests
[x] #4: Update README

(1/4 completed)

模型通过工具结果看到这段渲染文本，就跟自己写了一张便签一样。

(2) todo 工具——模型自己写、自己更新

TOOL_HANDLERS = {
    "bash":       lambda **kw: run_bash(kw["command"]),
    "read_file":  lambda **kw: run_read(kw["path"], kw.get("limit")),
    "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
    "edit_file":  lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
    "todo":       lambda **kw: TODO.update(kw["items"]),   # ← 新增
}

todo 工具的定义：

{"name": "todo",
 "description": "Update task list. Track progress on multi-step tasks.",
 "input_schema": {
     "type": "object",
     "properties": {"items": {"type": "array", "items": {"type": "object",
         "properties": {
             "id": {"type": "string"},
             "text": {"type": "string"},
             "status": {"type": "string", "enum": ["pending", "in_progress", "completed"]}
         }, "required": ["id", "text", "status"]}}},
     "required": ["items"]}}

值得注意的是：这个工具 没有读能力。模型不能查询"我现在的 todos 是什么"，它只能写。那模型怎么知道当前状态？看上次 todo 工具返回的 render 结果。这引出了一个设计取舍——这里的 todo 状态在 harness（Python 内存），模型只能通过工具返回值"看到"它。真正的 Claude Code 会把状态持久化到文件（s07 会做）。

(3) Nag Reminder——harness 的催促机制

模型有时会忘了更新 todo。s03 的解法很粗暴也很有效：数轮次，到阈值就催。

def agent_loop(messages: list):
    rounds_since_todo = 0         # ← 新增计数器
    while True:
        response = client.messages.create(...)
        messages.append({"role": "assistant", "content": response.content})
        if response.stop_reason != "tool_use":
            return
        results = []
        used_todo = False
        for block in response.content:
            if block.type == "tool_use":
                handler = TOOL_HANDLERS.get(block.name)
                output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
                results.append({"type": "tool_result", "tool_use_id": block.id, "content": str(output)})
                if block.name == "todo":
                    used_todo = True

        # 计数器更新
        rounds_since_todo = 0 if used_todo else rounds_since_todo + 1

        # 连续 3 轮没调 todo → 注入提醒
        if rounds_since_todo >= 3:
            results.append({
                "type": "text",
                "text": "<reminder>Update your todos.</reminder>"
            })

        messages.append({"role": "user", "content": results})

逻辑很清晰：

本轮调了 todo → rounds_since_todo = 0
本轮没调    → rounds_since_todo += 1
≥ 3         → 在 tool_results 中追加一条文本提醒

<reminder> 被作为 type: "text" 注入到 user 消息的 content 数组里。模型看到这条消息，就相当于 harness 拍了拍它的肩膀说"你该更新计划了"。

这和真实的 Claude Code 一致——你有时会看到系统注入的 <system-reminder> 标签，做的就是同样的事情。

(4) 为什么这个设计有效

核心在于三点：

状态在 harness，不在 prompt — 如果让模型"在脑子里记"，对话一长就忘。而 todo 列表是 Python 对象，render 结果每次作为工具返回值重新注入，模型相当于不停地看便签。
唯一 in_progress — 物理上不可并行，模型一次只干一件事。
Nag 是压力，不是命令 — harness 不规定模型做哪一步、怎么做，它只提醒"你该更新计划了"。规划权还在模型手里。

这也是 harness 哲学的体现：harness 提供结构（todo 状态机），模型填充内容（具体做什么）。

(5) s02 → s03 变化总结

组件	s02	s03
工具数量	4	5 (+todo)
规划	无	TodoManager 有状态管理
loop 变化	无	+ rounds_since_todo 计数器
模型催促	无	3 轮后注入 `<reminder>`
约束	无	最多 20 条、唯一 in_progress

(6) 运行

python agents/s03_todo_write.py

推荐测试 prompt（故意给多步任务，观察它是否先列 todo 再动手）：

Refactor the file hello.py: add type hints, docstrings, and a main guard
Create a Python package with __init__.py, utils.py, and tests/test_utils.py
Review all Python files and fix any style issues

关键洞察

s03 引入了一种新的 harness 能力：不替模型做决定，但给模型提供"别忘事"的结构。 TodoManager 是一个最简单的状态机——只有 3 个状态、1 条约束（唯一 in_progress）——却大幅提升了多步任务的完成率。

这也回答了一个常见问题：要不要给 agent 写详细的 prompt 步骤？s03 的答案是 不要——给结构就够了。别在 prompt 里写"第一步做 X、第二步做 Y"，那是固定脚本。给一个 todo 工具 + nag 机制，让模型自己生成和更新计划，灵活得多。

4. s04：Subagent——"上下文隔离就是思维隔离"

s04 解决的是 LLM Agent 的核心瓶颈：上下文膨胀。

Agent 工作越久，messages 数组越臃肿。主对话里已经积压了 50 轮工具调用和结果，然后模型被问到"这个项目用了什么测试框架？"——它读了 5 个文件才找到答案，而这 5 个文件的内容永久污染了主上下文。其实你只需要一个词：pytest。

解决方案：派"子 Agent"去查，只带回一句话摘要。

Parent agent                     Subagent
+------------------+             +------------------+
| messages=[...]   |             | messages=[]      |  ← 空白上下文
|                  |  dispatch   |                  |
| tool: task       | ──────────→ | while tool_use:  |
|   prompt="..."   |             |   read files     |
|                  |  summary    |   search, grep   |
|   result="pytest"| ←────────── | return last text |
+------------------+             +------------------+
              |
Parent context stays clean.
Subagent context is discarded.

(1) 两套工具、两套身份

s04 首次出现了工具的分级——父和子看到的工具不同：

# 子 Agent 只有基础工具（没有 task，防止无限递归）
CHILD_TOOLS = [
    {"name": "bash", ...},
    {"name": "read_file", ...},
    {"name": "write_file", ...},
    {"name": "edit_file", ...},
]

# 父 Agent = 基础工具 + task 派遣工具
PARENT_TOOLS = CHILD_TOOLS + [
    {"name": "task",
     "description": "Spawn a subagent with fresh context. It shares the filesystem but not conversation history.",
     "input_schema": {
         "type": "object",
         "properties": {
             "prompt": {"type": "string"},
             "description": {"type": "string", "description": "Short description of the task"}
         },
         "required": ["prompt"]
     }},
]

系统提示词也分开了：

SYSTEM = f"You are a coding agent at {WORKDIR}. Use the task tool to delegate exploration or subtasks."

SUBAGENT_SYSTEM = f"You are a coding subagent at {WORKDIR}. Complete the given task, then summarize your findings."

父是"主管"——会派活；子是"执行者"——只干事，汇报。

(2) `run_subagent`——独立循环 + 上下文丢弃

def run_subagent(prompt: str) -> str:
    sub_messages = [{"role": "user", "content": prompt}]  # 空白上下文！
    for _ in range(30):  # 安全限制：最多 30 轮
        response = client.messages.create(
            model=MODEL, system=SUBAGENT_SYSTEM, messages=sub_messages,
            tools=CHILD_TOOLS, max_tokens=8000,
        )
        sub_messages.append({"role": "assistant", "content": response.content})
        if response.stop_reason != "tool_use":
            break
        results = []
        for block in response.content:
            if block.type == "tool_use":
                handler = TOOL_HANDLERS.get(block.name)
                output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
                results.append({
                    "type": "tool_result", "tool_use_id": block.id,
                    "content": str(output)[:50000]
                })
        sub_messages.append({"role": "user", "content": results})

    # 只返回最后一段文字摘要——整个 sub_messages 被丢弃
    return "".join(b.text for b in response.content if hasattr(b, "text")) or "(no summary)"

关键设计点：

sub_messages 从空开始 — 子 Agent 看不到父对话历史，就像一个新开的 session。它不是 fork，是 fresh。
for _ in range(30) — 安全兜底，防止子 Agent 陷入死循环。最多 30 个 API 轮次，必须产出结论。
函数返回时 sub_messages 直接丢掉 — 这是 Python 的 GC 行为：函数退出，局部变量销毁。子 Agent 可能读了 10 个文件、跑了 20 个 bash 命令，但这些上下文不会回到父级。父收到的就是一段摘要文本。
共享文件系统，不共享聊天记录 — 子 Agent 对工作目录的修改会持久化（因为文件系统是共享的），但对话上下文完全隔离。

(3) 父 loop 中的 task 调度

for block in response.content:
    if block.type == "tool_use":
        if block.name == "task":                          # ← task 工具：同步阻塞
            desc = block.input.get("description", "subtask")
            prompt = block.input.get("prompt", "")
            print(f"> task ({desc}): {prompt[:80]}")
            output = run_subagent(prompt)                  # 阻塞等待子 Agent 完成
        else:
            handler = TOOL_HANDLERS.get(block.name)        # 其他工具走正常分发
            output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
        results.append({"type": "tool_result", "tool_use_id": block.id, "content": str(output)})

注意这里是同步执行——父 Agent 派发 task 后会阻塞等待子 Agent 完成。它不是启动一个后台线程，也没有并发。run_subagent(prompt) 返回之前，父 loop 停在那。s08 会把这种模式升级为后台任务。

(4) 为什么不允许递归生成

子 Agent 的 CHILD_TOOLS 里没有 task 工具。这是刻意的：

父 → task → 子 → task → 孙子 → task → ... 爆炸

没有 task 工具，子 Agent 就不知道"派子 Agent"这件事存在。它的 system prompt 只让它"完成给定的任务然后总结"，它的 JSON Schema 里没有 task。这就是工具层面的权限分级——不是你告诉子 Agent "别递归"，而是它物理上就没有这个能力。

(5) 这个模式的应用场景

s04 的模式最适合两类子任务：

探索/搜索类 — "找一下这个项目的测试框架是什么"、"列出所有用了 requests 库的文件"、"检查 auth 模块是怎么处理 token 的"。这类任务需要读很多文件但只需要一个简短结论。
生成/创建类 — "创建一个 utils.py，包含 safe_filename() 和 hash_cache_key() 两个函数"、"写一个数据库迁移脚本"。子 Agent 写文件，父 Agent 看到结果。

不适合的场景：需要和用户持续交互的任务（子 Agent 没有 input，看不到外部对话）。

(6) s03 → s04 变化总结

组件	s03	s04
工具分级	无（所有工具平等）	Parent 有 task，Child 没有
上下文模型	共享一个 `messages`	父子隔离，子上下文即用即弃
System prompt	1 个	2 个（父 + 子）
安全边界	无	子 Agent 有 30 轮限制，无 task 防递归
返回值	—	仅最后一段文本摘要

(7) 运行

python agents/s04_subagent.py

推荐测试 prompt：

Use a subtask to find what testing framework this project uses
Delegate: read all .py files and summarize what each one does
Use a task to create a new module, then verify it from here

启动后观察一个细节：父对话历史始终很短，而子 Agent 的内部循环你看不到（没有 print 它的每次工具调用）。你只收到子 Agent 的最终总结。

关键洞察

s04 的核心思想不是"多一个 Agent 干活更快"，而是上下文隔离 = 思维清晰。父对话历史保持干净，杂活交给子 Agent 在它自己的空间里做完，只带回答案。

这里有一个有趣的类比：函数调用。 在编程里，你不会把一个大函数的内部变量全暴露给调用者——你只返回一个值。s04 做的是同样的事：子 Agent = 函数，prompt = 参数，summary = 返回值，sub_messages = 函数内部的局部变量，退出即释放。

另一点值得注意：工具权限的分级从 s04 就开始了。不是给子 Agent 加"规则"让它别调 task——而是它根本没有 task 的 schema。这就是 harness 权限的本质：控制能力，不控制意图。

5. s05：Skill 加载——"用到什么知识，临时加载什么"

s05 解决的是 system prompt 膨胀问题。

你有 10 套领域知识想让 Agent 遵循——git 工作流规范、代码审查清单、测试最佳实践、PDF 处理流程……如果全塞进 system prompt，每次 API 调用都带着，10 个 skill × 2000 token = 20000 token 白白烧掉，而当前任务可能一个都用不上。

解决方案：两层按需加载——第一层放便宜的名字列表，第二层只在模型请求时才取出完整内容。

(1) Skill 的文件格式——YAML frontmatter + Markdown 正文

每个 skill 是 skills/<name>/SKILL.md 目录结构：

skills/
  agent-builder/
    SKILL.md          # YAML 头部 + Markdown 指导内容
  code-review/
    SKILL.md
  mcp-builder/
    SKILL.md
  pdf/
    SKILL.md

SKILL.md 用前端常见的 frontmatter 格式分隔元数据和正文：

---
name: pdf
description: Process PDF files - extract text, merge, split, and convert
tags: [document]
---

# PDF Processing

## Reading PDFs
Use `pdftotext` (from poppler-utils) to extract text...

## Creating PDFs
...

前面的 YAML 块是元数据（便宜，塞进 system prompt），后面是操作指南（贵，仅在加载时取出）。

(2) SkillLoader——扫描、解析、两层供给

class SkillLoader:
    def __init__(self, skills_dir: Path):
        self.skills_dir = skills_dir
        self.skills = {}
        self._load_all()

    def _load_all(self):
        if not self.skills_dir.exists():
            return
        for f in sorted(self.skills_dir.rglob("SKILL.md")):
            text = f.read_text()
            meta, body = self._parse_frontmatter(text)
            name = meta.get("name", f.parent.name)
            self.skills[name] = {"meta": meta, "body": body, "path": str(f)}

    def _parse_frontmatter(self, text: str) -> tuple:
        """用正则解析 --- YAML --- Markdown 结构"""
        match = re.match(r"^---\n(.*?)\n---\n(.*)", text, re.DOTALL)
        if not match:
            return {}, text
        try:
            meta = yaml.safe_load(match.group(1)) or {}
        except yaml.YAMLError:
            meta = {}
        return meta, match.group(2).strip()

rglob("SKILL.md") 递归扫描，你只需创建目录和文件，SkillLoader 自动发现。_parse_frontmatter 用正则 ^---\n(.*?)\n---\n(.*) 拆出 YAML 头和后边的 Markdown。

两层供给方法：

def get_descriptions(self) -> str:
    """Layer 1: 轻量描述列表 → 拼进 system prompt"""
    lines = []
    for name, skill in self.skills.items():
        desc = skill["meta"].get("description", "No description")
        tags = skill["meta"].get("tags", "")
        line = f"  - {name}: {desc}"
        if tags:
            line += f" [{tags}]"
        lines.append(line)
    return "\n".join(lines)

def get_content(self, name: str) -> str:
    """Layer 2: 完整内容 → 作为 tool_result 返回"""
    skill = self.skills.get(name)
    if not skill:
        return f"Error: Unknown skill '{name}'. Available: {', '.join(self.skills.keys())}"
    return f"<skill name=\"{name}\">\n{skill['body']}\n</skill>"

(3) system prompt 中只放名字

SYSTEM = f"""You are a coding agent at {WORKDIR}.
Use load_skill to access specialized knowledge before tackling unfamiliar topics.

Skills available:
{SKILL_LOADER.get_descriptions()}"""

最终生成的 system prompt 大概长这样：

You are a coding agent at /home/ubuntu/owen.
Use load_skill to access specialized knowledge before tackling unfamiliar topics.

Skills available:
  - agent-builder: Build custom AI agents using best practices [agent]
  - code-review: Review code for quality, security, and performance [code]
  - mcp-builder: Build MCP servers that integrate with Claude [mcp]
  - pdf: Process PDF files - extract text, merge, split, and convert

每个 skill 只占 ~100 token（名字 + 一句话描述），而不是完整 2000 token 的操作指南。

(4) `load_skill` 工具——模型需要时自己调

TOOL_HANDLERS = {
    "bash":       lambda **kw: run_bash(kw["command"]),
    "read_file":  lambda **kw: run_read(kw["path"], kw.get("limit")),
    "write_file": lambda **kw: run_write(kw["path"], kw["content"]),
    "edit_file":  lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
    "load_skill": lambda **kw: SKILL_LOADER.get_content(kw["name"]),  # ← 新增
}

{"name": "load_skill",
 "description": "Load specialized knowledge by name.",
 "input_schema": {
     "type": "object",
     "properties": {"name": {"type": "string", "description": "Skill name to load"}},
     "required": ["name"]}}

模型收到任务后，如果觉得需要某个领域的知识，会先调 load_skill("code-review")，harness 把完整的代码审查指南作为 tool_result 注入当前轮次。然后模型基于刚加载的操作指南工作。

(5) 为什么走 tool_result 而不是 system prompt？

这是 s05 最重要的设计选择。

如果走 system prompt：

模型需要 skill → 修改 system → 重新发请求，翻倍 API 调用

如果走 tool_result：

模型调 load_skill → skill 内容作为 tool_result 进入 messages → 下一轮模型已看到

走 tool_result 的好处：

不打断循环 — 就是一次普通工具调用，和其他工具行为一致
只在需要时出现 — pdf skill 的 2000 行内容不会出现在一个纯代码任务里
和对话上下文一起在 messages 里 — 模型能自然引用，不会像 system prompt 那样离对话历史太远
和其他工具结果一样被压缩/截断 — 后续 s06 的上下文压缩对 skill 内容一视同仁

(6) 和 prompt engineering 的区别

这个模式不是"写更好的 prompt"，而是把知识变成可被 Agent 自己调用的资源。

	传统 prompt engineering	s05 skill loading
知识位置	system prompt 或 user prompt	文件系统中独立的 SKILL.md
触发方式	每次对话都带着	模型主动调用 load_skill
token 成本	全量，每轮都付	按需，只付一次
可维护性	改 prompt 模板	改文件，无需重写代码

skill 文件是数据不是代码——新增一个 skill 就是 mkdir + touch SKILL.md + 写 YAML，不用改 Python。

(6.5) 一个常见误解：pdf skill 能"处理 PDF"吗？

初学者看到项目里有 skills/pdf/SKILL.md，直觉反应是"PDF 处理非常复杂（解析字体、渲染引擎、字符编码……），一个 skill 文件怎么可能搞定？"

实际上，看看 skills/pdf/SKILL.md 里写了什么：

## Reading PDFs
# 推荐用 pdftotext 或 pymupdf
pdftotext input.pdf -
# 或者
python3 -c "import fitz; doc = fitz.open('input.pdf'); ..."

## Creating PDFs
# 推荐用 pandoc (从 Markdown 生成)
pandoc input.md -o output.pdf
# 或者用 reportlab 编程生成

## Key Libraries
| Task | Library | Install |
|------|---------|---------|
| Read/Write/Merge | PyMuPDF | pip install pymupdf |
| Create from scratch | ReportLab | pip install reportlab |

skill 不是 PDF 处理引擎，它是一份操作指南/小抄。 里面写了三样东西：

bash 命令 — pdftotext、pandoc、wkhtmltopdf
Python 代码片段 — 标准库/三方库的调用模板
推荐库对照表 — 什么场景用什么库、怎么安装

模型收到这个 skill 后，和之前做的事情完全一样：调 bash 工具去执行这些命令。 如果 pdftotext 没装，模型会先 pip install pymupdf 再试 Python 方案。如果 pandoc 没装，模型会切到 reportlab。

所以 pdf skill 的本质是领域知识注入——不是给 Agent 新能力，而是告诉它"处理 PDF 用这些工具就够了，别绕远路"。模型本身已经会写代码、会调 bash、会读报错后修正，skill 只是把 PDF 场景的最佳路径预先告诉它。

可以这样理解：skill 相当于一个资深同事给你留的便利贴，上面写着"用 pymupdf 别用 pdfplumber，后者太慢"。便利贴没有给你新能力，但它让你做决策更快更准。

这个机制的好处是：新增领域支持的成本极低。你不需要写"PDF 解析器"、"PDF 渲染器"——你把 Python 生态里已有的工具（pymupdf、pdftotext、pandoc）组织成一份指南，模型自己会按指南去调用它们。模型的通用能力 + skill 的领域路径 = 领域专家行为。

(7) s04 → s05 变化总结

组件	s04	s05
工具	5 (基础 + task)	5 (基础 + load_skill)
系统提示	静态	动态拼接 skill 列表
知识管理	无	SkillLoader + SKILL.md 文件系统
注入策略	—	两层：名字在 system，内容在 tool_result
循环变化	—	无（又是 dispatch map 加一行）

(8) 运行

python agents/s05_skill_loading.py

推荐测试 prompt：

What skills are available?
Load the agent-builder skill and follow its instructions
I need to do a code review -- load the relevant skill first

关键洞察

s05 的 skill 机制和 s03 的 TodoWrite 在哲学上是一致的：不要把所有东西塞进 prompt，让 harness 提供按需的结构。 s03 是按需给规划能力，s05 是按需给领域知识。

这个两层注入模式——便宜的名字在 system prompt，昂贵的内容在 tool_result——做到了"模型知道什么知识存在，但只在用到时才付 token 代价"。这就是 Claude Code 里你看到的 /pdf /review 等 slash command 以及内置 skill 的核心机制。

6. s06：上下文压缩——"Agent 可以策略性地遗忘"

s06 解决的是 LLM Agent 的终极瓶颈：上下文窗口有天花板。

读一个 1000 行的文件 ~4000 token。读 30 个文件、跑 20 条 bash 命令，10 万 token 打不住。不压缩，Agent 根本没法在大项目里工作——messages 数组不断胀大，最终超过 API 的上下文限制，直接报错。

s06 用三层压缩金字塔解决了这个问题。

Layer 1：micro_compact——沉默的清扫工

每次 API 调用前自动运行，安静无感。策略很简单——旧工具结果替换为占位符：

KEEP_RECENT = 3               # 保留最近 3 个工具结果
PRESERVE_RESULT_TOOLS = {"read_file"}  # read_file 结果永不压缩

def micro_compact(messages: list) -> list:
    # 收集所有 tool_result 的位置
    tool_results = []
    for msg_idx, msg in enumerate(messages):
        if msg["role"] == "user" and isinstance(msg.get("content"), list):
            for part_idx, part in enumerate(msg["content"]):
                if isinstance(part, dict) and part.get("type") == "tool_result":
                    tool_results.append((msg_idx, part_idx, part))

    if len(tool_results) <= KEEP_RECENT:
        return messages

    # 匹配 tool_use_id → 工具名
    tool_name_map = {}
    for msg in messages:
        if msg["role"] == "assistant":
            content = msg.get("content", [])
            if isinstance(content, list):
                for block in content:
                    if hasattr(block, "type") and block.type == "tool_use":
                        tool_name_map[block.id] = block.name

    # 清理旧的（保留最后 KEEP_RECENT 个），跳过 read_file
    to_clear = tool_results[:-KEEP_RECENT]
    for _, _, result in to_clear:
        if not isinstance(result.get("content"), str) or len(result["content"]) <= 100:
            continue  # 已经很短了，不处理
        tool_id = result.get("tool_use_id", "")
        tool_name = tool_name_map.get(tool_id, "unknown")
        if tool_name in PRESERVE_RESULT_TOOLS:
            continue  # read_file 结果保留，避免模型重读文件
        result["content"] = f"[Previous: used {tool_name}]"

    return messages

关键设计决策：

保留最近 3 个 — 当前在做的事需要完整上下文，不压缩
read_file 永久保留 — 文件内容是参考材料，压缩后模型会忘了文件内容然后重读，反而不划算
替换而不是删除 — 结构保留（tool_result 对象还在），只是内容变成占位符。模型能看到"我之前调过 bash"，但看不到 bash 的完整输出。这种"知道发生了什么但忘了细节"的状态，和人类记忆很像
长度 >100 的才压缩 — 短结果（比如 "Wrote 50 bytes"）不值得替换

Layer 2：auto_compact——"我记不住了，帮我总结一下"

当 token 估算超过阈值（50000），触发自动压缩。用 LLM 总结 LLM 的对话：

THRESHOLD = 50000
TRANSCRIPT_DIR = WORKDIR / ".transcripts"

def estimate_tokens(messages: list) -> int:
    """粗略 token 估算：~4 个字符 ≈ 1 token"""
    return len(str(messages)) // 4

def auto_compact(messages: list) -> list:
    # 1. 先存盘，不丢数据
    TRANSCRIPT_DIR.mkdir(exist_ok=True)
    transcript_path = TRANSCRIPT_DIR / f"transcript_{int(time.time())}.jsonl"
    with open(transcript_path, "w") as f:
        for msg in messages:
            f.write(json.dumps(msg, default=str) + "\n")

    # 2. 取最后 80000 字符（防止总结请求本身超限），发给 LLM
    conversation_text = json.dumps(messages, default=str)[-80000:]

    # 3. LLM 总结（不带工具，纯文本总结）
    response = client.messages.create(
        model=MODEL,
        messages=[{"role": "user", "content":
            "Summarize this conversation for continuity. Include: "
            "1) What was accomplished, 2) Current state, 3) Key decisions made. "
            "Be concise but preserve critical details.\n\n" + conversation_text}],
        max_tokens=2000,
    )

    summary = next((block.text for block in response.content if hasattr(block, "text")), "")

    # 4. 整个 messages 数组被替换为一条总结消息
    return [
        {"role": "user", "content": f"[Conversation compressed. Transcript: {transcript_path}]\n\n{summary}"},
    ]

几个细节值得注意：

transcript_{timestamp}.jsonl — 完整对话存盘到 .transcripts/，以便后续 debug 或审查。信息没有丢失，只是移出了活跃上下文。
[-80000:] — 取对话尾部分给 LLM 做总结。因为最近的对话最重要，旧的对话可能在之前的压缩中已经被总结过了。
不带 tools 的 API 调用 — 这是 s06 中唯一一次不带 tools 参数的调用。总结这件事不需要工具，模型只输出一段纯文本。

Layer 3：compact 工具——模型主动请求压缩

# 工具定义
{"name": "compact",
 "description": "Trigger manual conversation compression.",
 "input_schema": {
     "type": "object",
     "properties": {"focus": {"type": "string",
         "description": "What to preserve in the summary"}}}}

# dispatch map 中的 handler
"compact": lambda **kw: "Manual compression requested.",

模型调用 compact 工具后，循环中检测到 manual_compact = True，同样调用 auto_compact()。focus 参数目前只是定义中的占位，实际只返回字符串 "Compressing..."——真正的压缩逻辑和 Layer 2 共享同一个 auto_compact 函数。

三层在循环中的位置

def agent_loop(messages: list):
    while True:
        # Layer 1: 每轮静默执行
        micro_compact(messages)

        # Layer 2: 超过阈值自动触发
        if estimate_tokens(messages) > THRESHOLD:
            print("[auto_compact triggered]")
            messages[:] = auto_compact(messages)

        response = client.messages.create(
            model=MODEL, system=SYSTEM, messages=messages,
            tools=TOOLS, max_tokens=8000,
        )
        messages.append({"role": "assistant", "content": response.content})
        if response.stop_reason != "tool_use":
            return

        results = []
        manual_compact = False
        for block in response.content:
            if block.type == "tool_use":
                if block.name == "compact":
                    manual_compact = True
                    output = "Compressing..."
                else:
                    handler = TOOL_HANDLERS.get(block.name)
                    output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
                results.append({"type": "tool_result", "tool_use_id": block.id, "content": str(output)})

        messages.append({"role": "user", "content": results})

        # Layer 3: 模型调了 compact 后触发
        if manual_compact:
            print("[manual compact]")
            messages[:] = auto_compact(messages)
            return

三层金字塔的总结

层 1: micro_compact  ─  每轮、轻量、自动    ─  旧 tool_result → 占位符
层 2: auto_compact   ─  超 50000 token 触发  ─  全量对话 → LLM 总结
层 3: compact 工具   ─  模型主动调用        ─  同层 2，手动触发

三层是递进关系：层 1 是日常清理，拖慢膨胀速度；层 2 是安全阀，防止越过 API 限制；层 3 是给模型的自主权，它可以在任务阶段切换时主动清空上下文。

s05 → s06 变化总结

组件	s05	s06
工具	5 (基础 + load_skill)	5 (基础 + compact)
上下文管理	无	三层压缩
循环变化	dispatch 分发	+ 层 1 前置检查 + 层 2 阈值检查 + 层 3 后置检查
文件系统	skills/	+ .transcripts/ 存档
模型可请求压缩	无	compact 工具

运行

python agents/s06_context_compact.py

推荐测试 prompt（故意制造大量工具调用观察压缩）：

Read every Python file in the agents/ directory one by one — 观察 micro-compact 逐步替换旧结果
Keep reading files until compression triggers automatically — 触发 auto_compact
Use the compact tool to manually compress the conversation — 手动触发

关键洞察

s06 的三层压缩机制本质上是给 Agent 可控的遗忘能力。人类不会记住今天敲过的每一条命令的完整输出，只记住"我刚才在干 X，结果是 Y"。Agent 需要同样的能力。

这里有一个反直觉的设计决策：read_file 的结果不压缩。 原因用一句话说就是——"忘掉 bash 输出没关系（可以重跑），忘掉文件内容会导致重复读文件，反复读文件反而更费 token"。好的压缩策略不是无差别清理，而是知道什么值得保留。

另一点：auto_compact 里的总结请求是不带工具的 API 调用。这说明 Agent 的压缩能力本身也在 harness 层面，不在对话循环里——压缩时模型不开着 bash/edit 等工具，它只用纯文本能力做总结。如果让压缩迭代跑到一半模型突然调了个 bash，那就不是压缩了。这是一种"能力降级"——在特定的 harness 路径上，工具集可以临时收紧。

7. s07：任务系统——"比任何一次对话都长命的目标"

s07 解决的是 s03 TodoManager 的两个致命弱点：内存态（压缩后丢失） 和 扁平无依赖。

s03 的 todo 列表在 Python 内存里，s06 的 auto_compact 一跑，整个消息历史被一条总结替换——todo 状态消失了。而且 todo 就是 [ ] [>] [x] 三态，没有"任务 B 依赖任务 A"的能力。

s07 的解法：把任务图持久化到磁盘上的 JSON 文件。 每组文件构成一个带依赖关系的 DAG（有向无环图）。

(1) 磁盘上的任务图

.tasks/
  task_1.json  {"id":1, "subject":"Set up project", "status":"completed"}
  task_2.json  {"id":2, "subject":"Write code", "blockedBy":[1], "status":"pending"}
  task_3.json  {"id":3, "subject":"Write tests", "blockedBy":[1], "status":"pending"}
  task_4.json  {"id":4, "subject":"Run CI", "blockedBy":[2,3], "status":"pending"}

对应的有向图：

               +----------+
          +--> | task 2   | --+
          |    | pending  |   |
+----------+  +----------+    +--> +----------+
| task 1   |                         | task 4   |
| completed| --> +----------+   +--> | blocked  |
+----------+     | task 3   | --+    +----------+
                 | pending  |
                 +----------+

顺序:  task 1 必须先完成, 才能开始 2 和 3
并行:  task 2 和 3 可以同时执行
依赖:  task 4 要等 2 和 3 都完成

这个语义非常清晰：什么能做（pending 且 blockedBy 为空）、什么被卡住（blockedBy 里还有未完成的 ID）、什么做完了（completed）。

(2) TaskManager——CRUD + 依赖传播

class TaskManager:
    def __init__(self, tasks_dir: Path):
        self.dir = tasks_dir
        self.dir.mkdir(exist_ok=True)
        self._next_id = self._max_id() + 1

    def _max_id(self) -> int:
        ids = [int(f.stem.split("_")[1]) for f in self.dir.glob("task_*.json")]
        return max(ids) if ids else 0

    def _load(self, task_id: int) -> dict:
        path = self.dir / f"task_{task_id}.json"
        return json.loads(path.read_text())

    def _save(self, task: dict):
        path = self.dir / f"task_{task['id']}.json"
        path.write_text(json.dumps(task, indent=2, ensure_ascii=False))

s07 是第二个用到文件系统持久化的 session（第一个是 s06 的 .transcripts/）。_next_id 从已有文件中读取最大值 +1——进程重启后 ID 不冲突。注意它不是靠全局计数器或者自增序列，而是 glob("task_*.json") 扫描磁盘，文件系统本身就是状态存储。

create 方法：

def create(self, subject: str, description: str = "") -> str:
    task = {
        "id": self._next_id, "subject": subject, "description": description,
        "status": "pending", "blockedBy": [], "owner": "",
    }
    self._save(task)
    self._next_id += 1
    return json.dumps(task, indent=2, ensure_ascii=False)

owner 字段现在是空字符串——这将来在 s09-s11 的 Agent 团队中会用到，标记任务属于哪个 Agent。

(3) 依赖传播——完成即解锁

这是 s07 最精巧的机制。当任务完成时，自动从所有其他任务的 blockedBy 中移除已完成的任务 ID：

def _clear_dependency(self, completed_id: int):
    """Remove completed_id from ALL other tasks' blockedBy lists."""
    for f in self.dir.glob("task_*.json"):
        task = json.loads(f.read_text())
        if completed_id in task.get("blockedBy", []):
            task["blockedBy"].remove(completed_id)
            self._save(task)

def update(self, task_id: int, status: str = None,
           add_blocked_by: list = None, remove_blocked_by: list = None) -> str:
    task = self._load(task_id)
    if status:
        if status not in ("pending", "in_progress", "completed"):
            raise ValueError(f"Invalid status: {status}")
        task["status"] = status
        if status == "completed":
            self._clear_dependency(task_id)    # ← 关键：标记完成时级联解锁
    if add_blocked_by:
        task["blockedBy"] = list(set(task["blockedBy"] + add_blocked_by))
    if remove_blocked_by:
        task["blockedBy"] = [x for x in task["blockedBy"] if x not in remove_blocked_by]
    self._save(task)
    return json.dumps(task, indent=2, ensure_ascii=False)

这里有一个重要的设计：_clear_dependency 扫描全部任务文件，而不是被完成的那个任务自己反查。这样可以安全处理"任务 A 被任务 B、C、D 共同依赖"的情况——A 完成那一刻，B、C、D 的 blockedBy 都被清理。

此外，add_blocked_by 用 list(set(...)) 去重，防止同一个依赖被加两次。

(4) 四个 task 工具

TOOL_HANDLERS = {
    "bash":        lambda **kw: run_bash(kw["command"]),
    "read_file":   lambda **kw: run_read(kw["path"], kw.get("limit")),
    "write_file":  lambda **kw: run_write(kw["path"], kw["content"]),
    "edit_file":   lambda **kw: run_edit(kw["path"], kw["old_text"], kw["new_text"]),
    "task_create": lambda **kw: TASKS.create(kw["subject"], kw.get("description", "")),
    "task_update": lambda **kw: TASKS.update(kw["task_id"], kw.get("status"),
                                              kw.get("addBlockedBy"), kw.get("removeBlockedBy")),
    "task_list":   lambda **kw: TASKS.list_all(),
    "task_get":    lambda **kw: TASKS.get(kw["task_id"]),
}

四个工具的职责很明确：增、改、列、查。注意没有删除——任务完成了就是标记为 completed，留下痕迹。

(5) s03 TodoWrite vs s07 TaskManager 对比

	s03 TodoWrite	s07 TaskManager
存储	Python 内存	`.tasks/` 磁盘 JSON
持久性	进程内	跨进程重启
依赖关系	无	`blockedBy` 有向图
压缩安全性	丢失（在 messages 里）	存活（在文件系统里）
字段	id, text, status	id, subject, description, status, blockedBy, owner
并发	无	owner 字段（为 s09+ 准备）

(6) 为什么是"第二个关键枢纽"

s07 在整个 12 个 session 序列中处于中点位置（s01-s06 | s07-s12），文档特别用 | 分隔。这不是偶然的——s07 是一切合作的骨架：

s08 的后台线程读取任务列表，自动认领 pending 任务
s09-s10 的 Agent 团队通过 owner 字段协商任务分配
s12 的 worktree 隔离用任务 ID 绑定工作目录

任务图是"被动的数据"，但它解耦了生产者和消费者——Agent A 创建任务，Agent B 执行任务，它们不需要直接通信，只需要读写同一个 .tasks/ 目录。

(7) s06 → s07 变化总结

组件	s06	s07
工具数	5	8 (+4 task)
持久化	.transcripts/（只存档）	.tasks/（活跃状态）
规划引擎	无（s06 没带 todo）	TaskManager + DAG
依赖关系	无	blockedBy 自动传播
循环变化	三层压缩	回到简单 dispatch（压缩暂未整合）

(8) 运行

python agents/s07_task_system.py

推荐测试 prompt：

Create 3 tasks: "Setup project", "Write code", "Write tests". Make them depend on each other in order.
List all tasks and show the dependency graph
Complete task 1 and then list tasks to see task 2 unblocked
Create a task board for refactoring: parse → transform → emit → test, where transform and emit can run in parallel after parse

试试关掉进程再重开，调用 task_list——任务还在磁盘上。

关键洞察

s07 的核心思想一句话：状态在对话之外。 s03 的 todo 在 messages 里（压缩后消失），s07 的 task 在文件系统里（压缩后还在）。这是从"对话级 Agent"迈向"项目级 Agent"的一道门槛——对话可以结束，任务可以继续。

从架构层面看，_clear_dependency 是一次被动传播：不是模型主动说"现在任务 B 的 blockedBy 可以移除了"，而是 harness 在任务 A 标记为 completed 那一刻自动做了级联更新。模型只需要知道"某件事做完了"，harness 负责把"做完"这件事的后果传到所有相关节点。这就是 harness 比 prompt 强的根本原因——harness 能做一致性的级联操作，prompt 只能做文本建议。

8. s08：后台任务——"慢操作丢后台，Agent 继续想下一步"

s08 解决的是 Agent 的 I/O 阻塞问题。

npm install 跑 3 分钟、pytest 跑 2 分钟、docker build 跑 5 分钟——s04 的 run_subagent 和普通的 bash 都是同步阻塞的，Agent 只能干等。用户说"装依赖 + 顺便建个配置文件"，Agent 得一个一个来。

s08 的解法：后台线程 + 通知队列。模型 spawn 任务后立即拿到 task_id，继续干别的事；任务完成后结果注入下一轮对话。

(1) BackgroundManager——线程池的朴素版

class BackgroundManager:
    def __init__(self):
        self.tasks = {}                   # task_id → {status, result, command}
        self._notification_queue = []     # 完成的任务结果
        self._lock = threading.Lock()     # 线程安全

不是线程池——就是 threading.Thread 每次新建一个线程。daemon 线程，主进程退出时自动终止。

(2) `run()`——启动即返回

def run(self, command: str) -> str:
    task_id = str(uuid.uuid4())[:8]       # 8 位随机 ID
    self.tasks[task_id] = {
        "status": "running", "result": None, "command": command
    }
    thread = threading.Thread(
        target=self._execute, args=(task_id, command), daemon=True
    )
    thread.start()
    return f"Background task {task_id} started: {command[:80]}"

关键：函数立即返回，模型看到一个 task_id，可以接着干别的事。和 s04 的 run_subagent 完全不同——那个是同步阻塞直到子 Agent 完成。

(3) `_execute()`——线程内的 subprocess

def _execute(self, task_id: str, command: str):
    try:
        r = subprocess.run(
            command, shell=True, cwd=WORKDIR,
            capture_output=True, text=True, timeout=300    # 5分钟超时
        )
        output = (r.stdout + r.stderr).strip()[:50000]
        status = "completed"
    except subprocess.TimeoutExpired:
        output = "Error: Timeout (300s)"
        status = "timeout"
    except Exception as e:
        output = f"Error: {e}"
        status = "error"

    self.tasks[task_id]["status"] = status
    self.tasks[task_id]["result"] = output or "(no output)"

    # 线程安全地推入通知队列
    with self._lock:
        self._notification_queue.append({
            "task_id": task_id, "status": status,
            "command": command[:80], "result": (output or "(no output)")[:500],
        })

和 run_bash 几乎一样——subprocess.run + 超时 + 截断。区别只有两个：

timeout 从 120s 变成 300s — 后台任务预期是长任务，给了更长的超时
结果推入通知队列而不是直接返回 — 线程不能直接往 messages 里写，所以走队列

(4) `drain_notifications()`——循环中唯一的线程交汇点

def drain_notifications(self) -> list:
    with self._lock:
        notifs = list(self._notification_queue)
        self._notification_queue.clear()
    return notifs

def check(self, task_id: str = None) -> str:
    """查询单个任务状态或列出所有"""
    if task_id:
        t = self.tasks.get(task_id)
        if not t:
            return f"Error: Unknown task {task_id}"
        return f"[{t['status']}] {t['command'][:60]}\n{t.get('result') or '(running)'}"
    # 列出所有
    lines = []
    for tid, t in self.tasks.items():
        lines.append(f"{tid}: [{t['status']}] {t['command'][:60]}")
    return "\n".join(lines) if lines else "No background tasks."

drain_notifications 是一次性操作——取走所有待通知，清空队列。这保证了每条通知只被注入一次。

(5) 循环注入——LLM 调用前的"收件箱检查"

def agent_loop(messages: list):
    while True:
        # 每次 LLM 调用前，清空通知队列
        notifs = BG.drain_notifications()
        if notifs and messages:
            notif_text = "\n".join(
                f"[bg:{n['task_id']}] {n['status']}: {n['result']}"
                for n in notifs
            )
            messages.append({
                "role": "user",
                "content": f"<background-results>\n{notif_text}\n</background-results>"
            })

        response = client.messages.create(...)

模型的核心循环是单线程的——只有 subprocess 在后台线程跑，agent loop 本身不并发。流程是：

Round N:   模型调 background_run("npm install") → 拿到 task_id
Round N+1: 模型干别的事（比如 background_run("pip install") 或 read_file）
Round N+2: drain_notifications() 发现 npm 跑完了 → 作为 <background-results> 注入
           模型看到结果，决定下一步

这不叫 agent 并发思考，这叫 I/O 并行 + Agent 顺序执行。Agent 本身还是单线程地一轮轮走，只是等待 I/O 的时间被利用了。

(6) 工具定义

# 两个新工具
{"name": "background_run", "description": "Run command in background thread. Returns task_id immediately.",
 "input_schema": {"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}},

{"name": "check_background", "description": "Check background task status. Omit task_id to list all.",
 "input_schema": {"type": "object", "properties": {"task_id": {"type": "string"}}}},

注意 check_background 的 task_id 不是 required——省略时列出所有任务。模型可以不知道自己 spawn 了哪些任务，调一次 check_background() 就能看到全局。

(7) s07 → s08 变化总结

组件	s07	s08
工具数	8 (4 task + 4 base)	6 (2 bg + 4 base，task 工具暂未整合)
执行方式	仅阻塞	阻塞 + 后台线程
通知机制	无	每轮排空通知队列
并发模型	纯串行	I/O 并行、Agent 顺序
循环变化	dispatch 分发	+ drain_notifications 前置注入

(8) 运行

python agents/s08_background_tasks.py

推荐测试 prompt：

Run "sleep 5 && echo done" in the background, then create a file while it runs
Start 3 background tasks: "sleep 2", "sleep 4", "sleep 6". Check their status.

关键洞察

s08 引入了 harness 中第一个真正异步的组件，但保持了 Agent 循环的单线程心智模型。这其实是一个重要的架构选择：模型不需要理解线程——它只知道"我上次 spawn 了一个东西，现在收到了它的结果"。 后台线程是 harness 层的事，模型的思维还是线性的。

另外值得注意：s04 的 run_subagent 是同步的，为什么不用后台线程包装它？因为子 Agent 需要的是"上下文隔离"，不是"执行并行"——父 Agent 在等子 Agent 的结论才能继续。而后台任务 (npm install) 没有这种依赖关系，模型可以继续干别的事。这就是两种异步的不同：一个是"我不等你，我干别的"，一个是"我要你的结果才能继续"。

9. s09：Agent 团队——"多个模型，通过文件协调"

s09 是从单 Agent 到多 Agent 的一道门槛。在此之前的所有 session 都是"一个模型、一个 loop"，s04 的子 Agent 是一次性的生成-返回-销毁，s08 的后台任务只能跑 shell 不能做 LLM 决策。

s09 引入了三个新能力：

持久化队友 — 有名字、有角色、有状态，跨多轮存活，不是一次性
文件邮箱通信 — append-only JSONL 收件箱，Agent 之间发消息
每个队友独立 agent loop — 每个人在自己的线程里跑完整的 while-tool_use 循环

(1) s04 Subagent vs s09 Teammate

Subagent (s04):   spawn → execute → return summary → destroyed
Teammate (s09):   spawn → working → idle → working → ... → shutdown

s04 的子 Agent 像函数调用——传参、执行、返回、清理。s09 的队友像员工——有名字 "alice"，有角色 "coder"，有生命周期 working → idle → working → idle，可以反复复派任务。

(2) 目录结构

.team/
  config.json              # 团队名册 + 各成员状态
  inbox/
    alice.jsonl            # alice 的收件箱（append-only）
    bob.jsonl              # bob 的收件箱
    lead.jsonl             # 领导的收件箱

(3) TeammateManager——队友生命周期

class TeammateManager:
    def __init__(self, team_dir: Path):
        self.dir = team_dir
        self.dir.mkdir(exist_ok=True)
        self.config_path = self.dir / "config.json"
        self.config = self._load_config()   # 从磁盘恢复
        self.threads = {}                    # 名字 → 线程

    def _load_config(self) -> dict:
        if self.config_path.exists():
            return json.loads(self.config_path.read_text())
        return {"team_name": "default", "members": []}

config.json 每次更新都 _save_config() 写回磁盘。进程重启后队员名册还在。

spawn() 方法：

def spawn(self, name: str, role: str, prompt: str) -> str:
    member = self._find_member(name)
    if member:
        if member["status"] not in ("idle", "shutdown"):
            return f"Error: '{name}' is currently {member['status']}"
        member["status"] = "working"
    else:
        member = {"name": name, "role": role, "status": "working"}
        self.config["members"].append(member)
    self._save_config()
    thread = threading.Thread(
        target=self._teammate_loop,
        args=(name, role, prompt),
        daemon=True,
    )
    self.threads[name] = thread
    thread.start()
    return f"Spawned '{name}' (role: {role})"

如果同名队友处于 idle 状态，就唤醒它并给新 prompt；如果是新名字，创建并启动线程。这实现了"队友复用"——不需要每次都创建新 Agent。

(4) MessageBus——文件级通信协议

这是 s09 最核心的发明。JSONL 文件做邮箱：

class MessageBus:
    def __init__(self, inbox_dir: Path):
        self.dir = inbox_dir
        self.dir.mkdir(parents=True, exist_ok=True)

    def send(self, sender: str, to: str, content: str,
             msg_type: str = "message", extra: dict = None) -> str:
        if msg_type not in VALID_MSG_TYPES:
            return f"Error: Invalid type '{msg_type}'"
        msg = {
            "type": msg_type, "from": sender,
            "content": content, "timestamp": time.time(),
        }
        if extra:
            msg.update(extra)
        inbox_path = self.dir / f"{to}.jsonl"
        with open(inbox_path, "a") as f:        # ← append-only
            f.write(json.dumps(msg) + "\n")
        return f"Sent {msg_type} to {to}"

    def read_inbox(self, name: str) -> list:
        inbox_path = self.dir / f"{name}.jsonl"
        if not inbox_path.exists():
            return []
        messages = []
        for line in inbox_path.read_text().strip().splitlines():
            if line:
                messages.append(json.loads(line))
        inbox_path.write_text("")               # ← drain after read
        return messages

关键设计：读即清空。read_inbox → 读所有行 → write_text("") 删文件。每条消息只被消费一次，不会重复处理。

5 种消息类型（定义了但 s09 只用到前 2 种，后 3 种留给 s10）：

VALID_MSG_TYPES = {
    "message",              # 普通文本消息
    "broadcast",            # 发给所有人
    "shutdown_request",     # 请求关闭 (s10)
    "shutdown_response",    # 同意/拒绝关闭 (s10)
    "plan_approval_response", # 审批计划 (s10)
}

还有 broadcast 方法，遍历所有队友逐个发：

def broadcast(self, sender: str, content: str, teammates: list) -> str:
    count = 0
    for name in teammates:
        if name != sender:
            self.send(sender, name, content, "broadcast")
            count += 1
    return f"Broadcast to {count} teammates"

(5) 队友的 agent loop——缩水但完整的版本

每个队友在自己的线程里跑：

def _teammate_loop(self, name: str, role: str, prompt: str):
    sys_prompt = (
        f"You are '{name}', role: {role}, at {WORKDIR}. "
        f"Use send_message to communicate. Complete your task."
    )
    messages = [{"role": "user", "content": prompt}]
    tools = self._teammate_tools()   # bash/read/write/edit/send_message/read_inbox
    for _ in range(50):              # 安全限制 50 轮
        # 每轮检查收件箱
        inbox = BUS.read_inbox(name)
        for msg in inbox:
            messages.append({"role": "user", "content": json.dumps(msg)})

        response = client.messages.create(
            model=MODEL, system=sys_prompt,
            messages=messages, tools=tools, max_tokens=8000,
        )
        messages.append({"role": "assistant", "content": response.content})
        if response.stop_reason != "tool_use":
            break
        # 执行工具（通过 _exec 分发）
        results = []
        for block in response.content:
            if block.type == "tool_use":
                output = self._exec(name, block.name, block.input)
                results.append({
                    "type": "tool_result", "tool_use_id": block.id,
                    "content": str(output),
                })
        messages.append({"role": "user", "content": results})

    # 完成后回到 idle 状态
    member = self._find_member(name)
    if member and member["status"] != "shutdown":
        member["status"] = "idle"
        self._save_config()

注意队友的 sys_prompt 和 Leader 不同——队友被告知自己的名字和角色，被要求"完成你的任务"，Leader 则被告知"你是团队领导，派发任务"。

(6) 领导（Lead）的循环——收件箱注入

def agent_loop(messages: list):
    while True:
        # 每轮先检查收件箱
        inbox = BUS.read_inbox("lead")
        if inbox:
            messages.append({
                "role": "user",
                "content": f"<inbox>{json.dumps(inbox, indent=2)}</inbox>",
            })
        # 正常 loop...

领导和队友的通信模式是对称的——都走 BUS.read_inbox，都通过 JSONL 文件交换消息。领导给 alice 发消息 → alice.jsonl 新增一行 → alice 下轮 read_inbox 读到 → 清空。

(7) 九工具全貌

Leader 有 9 个工具：

TOOL_HANDLERS = {
    "bash":            ...,  # 基础工具
    "read_file":       ...,
    "write_file":      ...,
    "edit_file":       ...,
    "spawn_teammate":  ...,  # 创建/唤醒队友
    "list_teammates":  ...,  # 列出团队状态
    "send_message":    ...,  # 点对点发消息
    "read_inbox":      ...,  # 读 lead 的收件箱
    "broadcast":       ...,  # 广播给全员
}

Leader 有 bash/edit 等完整能力（它可以亲自干活），也有团队管理能力。队友只有 6 个工具——没有 spawn_teammate / list_teammates / broadcast（防止递归管理）。

(7.5) 什么时候用哪种模式？

到 s09 为止，我们已经有了三种 Agent 协作模式。怎么选？代码没有显式写决策逻辑，但从设计意图可以看出一个判断框架：

	单 Agent (s01-s02)	Subagent (s04)	Agent 团队 (s09)
适用场景	简单任务，几步完成	探索/搜索，需要上下文隔离	复杂多步任务，可并行
任务特征	单一目标，线性执行	读多文件但只需结论	角色有分工 (coder/tester)
生命周期	一次性对话	spawn→执行→返回→销毁	spawn→work→idle→work→...
通信	无（用户↔Agent）	单向：父→子 prompt，子→父 summary	双向：JSONL 收件箱
上下文	父对话共享	子独立上下文（隔离）	各自独立上下文
并发	串行	串行（父阻塞等子）	并行（各自线程）
典型 prompt	"列出所有 py 文件"	"找一下这个项目用什么测试框架"	"alice 写代码，bob 写测试"

决策逻辑模型（LLM 自己判断）：

模型看到任务后，会基于自己的判断决定调哪个工具：

需要自己查文件但不想污染对话 → 调 task 工具 spawn 一个子 Agent
任务可以分给不同角色并行 → 调 spawn_teammate 创建队友
简单的读/写/改 → 直接用 bash / read_file / write_file / edit_file

harness 不替模型做这个决策。它只是把三种工具都提供出来，让模型自己判断场景。这和之前的原则一致——模型拥有判断权，harness 拥有执行权。

值得一提的是：这些模式不是互斥的。Leader 可以 spawn 一个 teammate（alice），alice 在处理任务时也可以在自己的 loop 里用 bash/read/write——团队模式是单 Agent 模式的超集，团队里的每个成员本质上还是一个独立 Agent。

(8) s08 → s09 变化总结

组件	s08	s09
Agent 数量	1	1 Lead + N 队友
工具数	6	9 (+spawn/send/read_inbox/broadcast，同时也有 check)
持久化	无	config.json + JSONL 收件箱
线程	跑 shell	跑完整 agent loop
通信	无（通知队列是单向）	双向文件邮箱
生命周期	一次性守护线程	idle ↔ working 循环

(9) 运行

python agents/s09_agent_teams.py

内置命令（非 LLM 路径）：

/team — 直接查看 .team/config.json 中的团队名册
/inbox — 直接查看 lead 的收件箱

推荐测试 prompt：

Spawn alice (coder) and bob (tester). Have alice send bob a message.
Broadcast "status update: phase 1 complete" to all teammates

关键洞察

s09 用最简单的通信原语——文件追加 + 读后清空——实现了多 Agent 协作。没有消息队列、没有 RPC、没有 WebSocket。JSONL 收件箱就是一个单写者多读者、append-only 的日志。

这个设计有两个极简主义洞察：

文件即协议 — 不需要定义通信协议格式，JSONL 每一行就是一条消息。没有握手、没有 ack、没有重试。读即清空 = 消息确认（如果进程在读后崩溃前没处理完，消息会丢——但对 Agent 来说，丢消息不是故障，它会在下一轮收到新消息时继续工作）。
收件箱读清是幂等屏障 — read_inbox 返回后文件为空。这意味着一个队友同一时间只有一个线程在消费它的收件箱（因为只有一个 teammate loop）。没有锁竞争，没有重复消费。

对比 s04 的 subagent，s09 的队友和 subagent 有本质不同：subagent 共享文件系统但不共享通信通道；teammate 通过收件箱随时可以收到新任务。通信通道是 Agent 从"工具"升级为"成员"的分界线。

10. s10：团队协议——"模型之间的结构化握手"

s09 的队友能干活能通信，但缺少两样东西：优雅关机和计划审批。

直接杀线程会留下写了一半的文件、过期的 config.json。高风险变更（"重构认证模块"）队友拿到就开干，没有审批环节。s10 用一个统一的模式解决这两个问题：request_id 关联 + 两态 FSM。

(1) 统一的 FSM——一个模式，两个场景

Shutdown Protocol                  Plan Approval Protocol
==================                 ======================
Lead             Teammate           Teammate           Lead
  |                 |                 |                 |
  |--shutdown_req-->|                 |--plan_req------>|
  | {req_id:"abc"}  |                 | {req_id:"xyz"}  |
  |                 |                 |                 |
  |<--shutdown_resp-|                 |<--plan_resp-----|
  | {req_id:"abc",  |                 | {req_id:"xyz",  |
  |  approve:true}  |                 |  approve:true}  |

共享状态机:  [pending] ──approve──> [approved]
            [pending] ──reject───> [rejected]

两个场景方向不同但结构完全一样：一方发带唯一 ID 的请求，另一方引用同一 ID 响应。

(2) 请求追踪器——全局状态

# 全局字典，用 request_id 做 key
shutdown_requests = {}   # {req_id: {target|from: name, status: "pending"|"approved"|"rejected"}}
plan_requests = {}        # {req_id: {from: name, plan: text, status: ...}}
_tracker_lock = threading.Lock()

这两个全局 dict 在 s09 的基础上加了一层状态可观测性——s09 发完消息就完了，不知道对方处理了没有。s10 通过 request_id 可以查到每笔请求的状态。

(3) 关机协议——"请停下手里的活"

Leader 发起：

def handle_shutdown_request(teammate: str) -> str:
    req_id = str(uuid.uuid4())[:8]
    with _tracker_lock:
        shutdown_requests[req_id] = {"target": teammate, "status": "pending"}
    BUS.send(
        "lead", teammate, "Please shut down gracefully.",
        "shutdown_request", {"request_id": req_id},
    )
    return f"Shutdown request {req_id} sent to '{teammate}' (status: pending)"

队友收到后，在 _exec 中处理：

# 队友的 _exec 方法中
if tool_name == "shutdown_response":
    req_id = args["request_id"]
    approve = args["approve"]
    with _tracker_lock:
        if req_id in shutdown_requests:
            shutdown_requests[req_id]["status"] = "approved" if approve else "rejected"
    BUS.send(
        sender, "lead", args.get("reason", ""),
        "shutdown_response", {"request_id": req_id, "approve": approve},
    )
    return f"Shutdown {'approved' if approve else 'rejected'}"

队友的 loop 中检测自己的 shutdown_response 是否被批准：

# 队友 _teammate_loop 的工具执行后
if block.name == "shutdown_response" and block.input.get("approve"):
    should_exit = True    # 批准 → 退出循环
# ...
# 循环结束时
member["status"] = "shutdown" if should_exit else "idle"

注意这里有一个微妙的设计：队友不是被 Leader 直接关掉的。 Leader 发请求 → 队友自己决定 approve/reject → 如果 approve，队友自己的 loop 检测到并退出。是"请求退出"不是"强制终止"。

(4) 计划审批——"干之前先让我看一眼"

方向上和关机相反——是队友向 Leader 提审批：

# 队友 _exec 中
if tool_name == "plan_approval":
    plan_text = args.get("plan", "")
    req_id = str(uuid.uuid4())[:8]
    with _tracker_lock:
        plan_requests[req_id] = {"from": sender, "plan": plan_text, "status": "pending"}
    BUS.send(
        sender, "lead", plan_text, "plan_approval_response",
        {"request_id": req_id, "plan": plan_text},
    )
    return f"Plan submitted (request_id={req_id}). Waiting for lead approval."

Leader 审查：

def handle_plan_review(request_id: str, approve: bool, feedback: str = "") -> str:
    with _tracker_lock:
        req = plan_requests.get(request_id)
    if not req:
        return f"Error: Unknown plan request_id '{request_id}'"
    with _tracker_lock:
        req["status"] = "approved" if approve else "rejected"
    BUS.send(
        "lead", req["from"], feedback, "plan_approval_response",
        {"request_id": request_id, "approve": approve, "feedback": feedback},
    )
    return f"Plan {req['status']} for '{req['from']}'"

这里的 feedback 参数允许 Leader 附加说明："计划可以，但别动数据库迁移部分"。

(5) 工具膨胀——12 个工具

TOOL_HANDLERS = {
    # 基础 (4):  bash, read_file, write_file, edit_file
    # 团队管理 (2): spawn_teammate, list_teammates
    # 通信 (3): send_message, read_inbox, broadcast
    # 协议 (3): shutdown_request, shutdown_response, plan_approval
}

从 s09 的 9 个涨到 12 个。注意 shutdown_request 和 shutdown_response Leader 和队友都有，但用途不同——Leader 用 shutdown_request 发请求，用 shutdown_response 查状态；队友用 shutdown_request 收请求，用 shutdown_response 回响应。同名工具在不同角色的 context 里含义不同。

(6) s09 → s10 变化总结

组件	s09	s10
工具数	9	12 (+shutdown_req/resp +plan)
关机	自然退出（线程结束）	请求-响应握手
计划控制	无	队友提交 + Leader 审批
请求追踪	无	request_id + 全局 dict
状态机	仅 config.json 的 status	pending → approved/rejected FSM

(7) 运行

python agents/s10_team_protocols.py

推荐测试 prompt：

Spawn alice as a coder. Then request her shutdown.
List teammates to see alice's status after shutdown approval
Spawn bob with a risky refactoring task. Review and reject his plan.

关键洞察

s10 引入了一个可复用的协议模式：request_id + FSM + 收件箱。关机协议和计划审批代码结构几乎一样，只有消息类型名不同。任何需要"请求→响应"的协作都可以套用这个模板——task assignment、resource lock、permission escalation——都是同一个 FSM。

另一个有趣的细节：关机是协商不是命令。Leader 不能强制 kill 队友的线程——它只能发 shutdown_request，队友自己决定是否 approve。这个设计和 Kubernetes 的 graceful shutdown 逻辑一致：发 SIGTERM 给进程，进程自己清理后退出。harness 不替 Agent 做决定——这个原则跨了 10 个 session 从未改变。

11. s11：自主 Agent——"模型自己找活干"

s09-s10 中队友只在被明确指派时才动。Leader 得给每个队友写 prompt——"alice 做 X，bob 做 Y"。任务看板上有 10 个未认领的任务，得手动分配。这不可扩展。

s11 的解法：队友完成手头工作后，进入空闲轮询——自己扫描任务看板、自己认领、自己做。Leader 只是创建任务和 spawn 队友，bootstrap 之后就不需要持续分配了。

(1) WORK → IDLE → WORK 循环

s11 把队友的 loop 从线性改成了状态机：

+-------+
| spawn |
+---+---+
    |
    v
+-------+   tool_use     +-------+
| WORK  | <------------- |  LLM  |
+---+---+                +-------+
    |
    | stop_reason != tool_use 或调用了 idle 工具
    v
+--------+
|  IDLE  |  每 5 秒轮询，最多 60 秒
+---+----+
    |
    +---> check inbox → 有新消息? → 回到 WORK
    |
    +---> scan .tasks/ → 有未认领? → claim → 回到 WORK
    |
    +---> 60s 超时 → SHUTDOWN

POLL_INTERVAL = 5   # 每 5 秒轮询一次
IDLE_TIMEOUT = 60   # 60 秒没活干就自动关机

def _loop(self, name: str, role: str, prompt: str):
    while True:
        # -- WORK PHASE: 标准 agent loop --
        for _ in range(50):
            inbox = BUS.read_inbox(name)
            for msg in inbox:
                if msg.get("type") == "shutdown_request":
                    self._set_status(name, "shutdown")
                    return
                messages.append(...)
            response = client.messages.create(...)
            # 执行工具...
            if idle_requested:
                break    # 模型说"我干完了"→ 进入 IDLE

        # -- IDLE PHASE: 轮询新工作 --
        self._set_status(name, "idle")
        resume = False
        polls = IDLE_TIMEOUT // max(POLL_INTERVAL, 1)   # 60//5 = 12 次
        for _ in range(polls):
            time.sleep(POLL_INTERVAL)
            # 检查 1: 收件箱有新消息?
            inbox = BUS.read_inbox(name)
            if inbox:
                for msg in inbox:
                    if msg.get("type") == "shutdown_request":
                        self._set_status(name, "shutdown")
                        return
                    messages.append(...)
                resume = True
                break
            # 检查 2: 任务看板有未认领任务?
            unclaimed = scan_unclaimed_tasks()
            if unclaimed:
                task = unclaimed[0]
                result = claim_task(task["id"], name)
                if result.startswith("Error:"):
                    continue    # 被别人抢了，继续看下一个
                # 注入身份（如果需要）和任务 prompt
                if len(messages) <= 3:
                    messages.insert(0, make_identity_block(name, role, team_name))
                messages.append({"role": "user", "content": task_prompt})
                resume = True
                break

        if not resume:
            self._set_status(name, "shutdown")
            return     # 超时，退出
        self._set_status(name, "working")
        # 回到 while True 顶部，重新进入 WORK PHASE

(2) 任务看板扫描——`scan_unclaimed_tasks`

def scan_unclaimed_tasks() -> list:
    TASKS_DIR.mkdir(exist_ok=True)
    unclaimed = []
    for f in sorted(TASKS_DIR.glob("task_*.json")):
        task = json.loads(f.read_text())
        if (task.get("status") == "pending"
                and not task.get("owner")         # ← 没人认领
                and not task.get("blockedBy")):   # ← 没有阻塞依赖
            unclaimed.append(task)
    return unclaimed

三个条件：pending 状态 + owner 为空 + blockedBy 为空。被阻塞的任务不会被认领——这保证了依赖顺序。

(3) 任务认领——`claim_task`

_claim_lock = threading.Lock()    # 全局锁，防止两个队友同时认领同一个任务

def claim_task(task_id: int, owner: str) -> str:
    with _claim_lock:
        path = TASKS_DIR / f"task_{task_id}.json"
        task = json.loads(path.read_text())
        if task.get("owner"):
            return f"Error: Task {task_id} has already been claimed by {task['owner']}"
        if task.get("status") != "pending":
            return f"Error: Task {task_id} cannot be claimed (status: {task['status']})"
        if task.get("blockedBy"):
            return f"Error: Task {task_id} is blocked"
        task["owner"] = owner
        task["status"] = "in_progress"
        path.write_text(json.dumps(task, indent=2))
    return f"Claimed task #{task_id} for {owner}"

_claim_lock 是关键——防止竞态条件。alice 和 bob 都在 IDLE 状态同时扫描，同时看到 task_3 未认领，同时尝试认领。_claim_lock 保证只有一个成功，另一个收到 "Error: already claimed"。

注意这里用的是锁 + 文件重读，而不是 compare-and-swap。这是安全的——因为 Python 线程虽然有 GIL，但文件 I/O 释放 GIL，_claim_lock 保证原子性。

(4) 身份重注入——压缩后不忘自己是谁

s06 的 auto_compact 会把 messages 压缩成一条摘要。队友 loop 如果经历了一次压缩（messages 变得很短），就不知道自己是谁了——system prompt 被移到了 API 调用里，但压缩后的总结不会提及身份。

def make_identity_block(name: str, role: str, team_name: str) -> dict:
    return {
        "role": "user",
        "content": f"<identity>You are '{name}', role: {role}, team: {team_name}. Continue your work.</identity>",
    }

# 在认领任务后，检查 messages 长度
if len(messages) <= 3:        # ← 3 条以下说明经历了压缩
    messages.insert(0, make_identity_block(name, role, team_name))
    messages.insert(1, {"role": "assistant", "content": f"I am {name}. Continuing."})

这是一个防御性设计：system prompt 可能膨胀（不能被压缩），但身份信息可以以 user message 的形式存在于可压缩的上下文里。 压缩后，harness 重新注入身份。

(5) `idle` 工具——模型主动说"我干完了"

{"name": "idle",
 "description": "Signal that you have no more work. Enters idle polling phase.",
 "input_schema": {"type": "object", "properties": {}}},

模型可以主动调 idle 表示当前任务完成，进入轮询等待新工作。Leader 的 handler：

"idle": lambda **kw: "Lead does not idle.",   # Leader 不休眠

(6) 新的斜杠命令

if query.strip() == "/tasks":
    TASKS_DIR.mkdir(exist_ok=True)
    for f in sorted(TASKS_DIR.glob("task_*.json")):
        t = json.loads(f.read_text())
        marker = {"pending":"[ ]", "in_progress":"[>]", "completed":"[x]"}[t["status"]]
        owner = f" @{t['owner']}" if t.get("owner") else ""
        print(f"  {marker} #{t['id']}: {t['subject']}{owner}")

/tasks 命令直接查看任务看板，显示每个任务的状态和认领人。

(7) s10 → s11 变化总结

组件	s10	s11
工具数	12	14 (+idle +claim_task)
自治性	领导指派	自组织、自认领
队友 loop	线性 50 轮后 idle	WORK/IDLE 状态机
任务认领	仅手动（通过 task_update）	自动扫描 + 认领
竞态处理	无	`_claim_lock`
身份	仅 system prompt	+ 压缩后重注入
空闲超时	无	60s → 自动关机

(8) 运行

python agents/s11_autonomous_agents.py

推荐测试：

Create 3 tasks on the board, then spawn alice and bob. Watch them auto-claim.
Spawn a coder teammate and let it find work from the task board itself
/tasks 查看带 owner 的任务看板
/team 监控谁在工作、谁在空闲

关键洞察

s11 是团队协作模式的终态：Leader 从"指挥官"退化为"创建者"——创建任务、spawn 队友，之后队友自组织。 这个模式对应的是现实中的看板管理（Kanban）：PM 往 Backlog 里放任务，开发自己拉取。

s07 的 task DAG + s11 的自主认领 = 一个自驱动的项目引擎。任务之间的依赖（blockedBy）自动控制执行顺序，队友的空闲轮询自动分配工作，_claim_lock 防止重复认领。唯一还需要 Leader 的是：创建任务、spawn 初始队友。 s12 将把最后这一步也自动化。

另外值得注意：idle 工具是模型主动声明"我没活了"的能力——它不是被动等待 stop_reason，而是主动告知 harness。这给 harness 提供了一个明确的信号"可以去找新工作了"，而不是猜测模型是否真的完成了。

12. s12：Worktree 任务隔离——"各干各的目录，永不碰撞"

s12 是整个 12 个 session 的终点，也是隔离机制的最高级。s09-s11 的 Agent 团队在同一目录下并行工作——alice 改 config.py，bob 也改 config.py，未提交的改动互相污染，谁也没法干净回滚。

s12 的解法：给每个任务一个独立的 git worktree 目录。 任务是控制面（做什么），worktree 是执行面（在哪做），二者用任务 ID 绑定。

(1) 控制面 + 执行面

Control plane (.tasks/)            Execution plane (.worktrees/)
+------------------+               +------------------------+
| task_1.json      |               | auth-refactor/         |
|   status: in_progress  <------>  |   branch: wt/auth-refactor
|   worktree: "auth-refactor" |    |   task_id: 1           |
+------------------+               +------------------------+
| task_2.json      |               | ui-login/              |
|   status: pending     <------>   |   branch: wt/ui-login
|   worktree: "ui-login"      |    |   task_id: 2           |
+------------------+               +------------------------+
                                   |
                         .worktrees/
                           index.json    (worktree registry)
                           events.jsonl  (lifecycle audit log)

每个 worktree 是一个完整的 git checkout，有自己的分支（wt/auth-refactor），自己的文件系统副本。alice 在 auth-refactor/ 里跑 pytest，bob 在 ui-login/ 里跑，互不影响。

(2) 仓库检测——s12 只在 git repo 里工作

def detect_repo_root(cwd: Path) -> Path | None:
    try:
        r = subprocess.run(
            ["git", "rev-parse", "--show-toplevel"],
            cwd=cwd, capture_output=True, text=True, timeout=10,
        )
        if r.returncode != 0:
            return None
        root = Path(r.stdout.strip())
        return root if root.exists() else None
    except Exception:
        return None

REPO_ROOT = detect_repo_root(WORKDIR) or WORKDIR

如果当前目录不在 git repo 里，REPO_ROOT 回退到 WORKDIR（git_available = False），worktree 工具会返回错误。

(3) WorktreeManager——目录隔离引擎

WorktreeManager 管理 git worktree 的完整生命周期：

class WorktreeManager:
    def __init__(self, repo_root: Path, tasks: TaskManager, events: EventBus):
        self.repo_root = repo_root
        self.tasks = tasks
        self.events = events
        self.dir = repo_root / ".worktrees"
        self.index_path = self.dir / "index.json"
        self.git_available = self._is_git_repo()

create——创建隔离副本：

def create(self, name: str, task_id: int = None, base_ref: str = "HEAD") -> str:
    self._validate_name(name)   # 1-40 字符，只允许字母数字 . _ -
    if self._find(name):
        raise ValueError(f"Worktree '{name}' already exists")
    if task_id is not None and not self.tasks.exists(task_id):
        raise ValueError(f"Task {task_id} not found")

    path = self.dir / name
    branch = f"wt/{name}"

    # 发事件
    self.events.emit("worktree.create.before", task={"id": task_id}, ...)

    # 实际执行 git worktree add
    self._run_git(["worktree", "add", "-b", branch, str(path), base_ref])

    # 写入 index
    entry = {"name": name, "path": str(path), "branch": branch,
             "task_id": task_id, "status": "active", "created_at": time.time()}
    idx["worktrees"].append(entry)
    self._save_index(idx)

    # 绑定到任务
    if task_id is not None:
        self.tasks.bind_worktree(task_id, name)   # ← 同时写两侧

    self.events.emit("worktree.create.after", ...)

bind_worktree 是双向操作——在 task JSON 里写上 worktree: "auth-refactor"，同时把任务状态从 pending 推进到 in_progress：

def bind_worktree(self, task_id: int, worktree: str, owner: str = "") -> str:
    task = self._load(task_id)
    task["worktree"] = worktree
    if owner: task["owner"] = owner
    if task["status"] == "pending":
        task["status"] = "in_progress"
    self._save(task)

run——在隔离目录中执行命令：

def run(self, name: str, command: str) -> str:
    wt = self._find(name)
    path = Path(wt["path"])
    r = subprocess.run(
        command, shell=True,
        cwd=path,            # ← 关键：cwd 指向 worktree 目录
        capture_output=True, text=True, timeout=300,
    )
    return (r.stdout + r.stderr).strip()[:50000]

这个 cwd=path 是 s12 区别于之前所有 session 的关键——命令运行在 isolatated 的目录副本中，改动不会污染主工作区。和 s01 cwd=WORKDIR 对照着看，能清楚看到隔离层级的一步步升级。

remove——拆除 worktree，同时可选完成绑定任务：

def remove(self, name: str, force: bool = False, complete_task: bool = False) -> str:
    # 1. 先跑 git worktree remove
    self._run_git(["worktree", "remove", wt["path"]])

    # 2. 如果 complete_task=True，自动完成任务
    if complete_task and wt.get("task_id") is not None:
        task_id = wt["task_id"]
        self.tasks.update(task_id, status="completed")
        self.tasks.unbind_worktree(task_id)
        self.events.emit("task.completed", task={"id": task_id, ...}, ...)

    # 3. 更新 index（标记为 removed，不删除）
    for item in idx["worktrees"]:
        if item["name"] == name:
            item["status"] = "removed"
            item["removed_at"] = time.time()

一个调用完成"删除目录 + 完成任务 + 发事件 + 更新索引"。force=True 时即使有未提交改动也会强制删除。

keep——保留 worktree 但不删除：

def keep(self, name: str) -> str:
    # 标记为 kept，不调 git worktree remove
    item["status"] = "kept"
    item["kept_at"] = time.time()
    self.events.emit("worktree.keep", ...)

两个收尾选项对应两种场景：改完了提交到主分支 → remove；想保留这个分支日后继续 → keep。

(4) EventBus——生命周期可观测性

class EventBus:
    def __init__(self, event_log_path: Path):
        self.path = event_log_path   # .worktrees/events.jsonl

    def emit(self, event: str, task: dict = None, worktree: dict = None, error: str = None):
        payload = {"event": event, "ts": time.time(),
                   "task": task or {}, "worktree": worktree or {}}
        if error: payload["error"] = error
        with self.path.open("a") as f:
            f.write(json.dumps(payload) + "\n")

    def list_recent(self, limit: int = 20) -> str:
        # 返回最近 N 条事件

8 种事件类型覆盖完整生命周期：

worktree.create.before / .after / .failed
worktree.remove.before / .after / .failed
worktree.keep
task.completed

每个事件的 JSON 行里都有 ts 时间戳、关联的 task 信息、worktree 状态。崩溃后可以用 worktree_events 工具查询事件流重建现场。

(5) 状态机：两层联动

Task FSM:       pending  →  in_progress  →  completed
                     ↑          ↑               ↑
Worktree FSM:  absent   →   active     →  removed | kept
                     │          │               │
              bind_worktree  create      remove/keep

绑定的那一刻，任务从 pending 推进到 in_progress。拆除后，任务从 in_progress 推进到 completed（如果 complete_task=True）。

(6) 工具全景——16 个工具

# 基础 (4): bash, read_file, write_file, edit_file
# 任务 (5): task_create, task_list, task_get, task_update, task_bind_worktree
# Worktree (7): worktree_create, worktree_list, worktree_status,
#                worktree_run, worktree_keep, worktree_remove, worktree_events

16 个工具，是整个序列中的最大值。和 s01 的 1 个工具（bash）对比——12 个 session，从 1 到 16，工具的数量增长就是 harness 能力的增长。

(7) s11 → s12 变化总结

组件	s11	s12
工具数	14	16
执行范围	共享目录	每任务独立 git worktree
文件隔离	无（靠自觉）	目录级硬隔离
恢复	仅 task JSON	task + worktree index + events
收尾	任务完成	任务完成 + 显式 keep/remove
可观测性	隐式	EventBus + events.jsonl

(8) 运行

python agents/s12_worktree_task_isolation.py

（需要在一个 git repo 里运行）

推荐测试：

Create tasks for backend auth and frontend login page, then list tasks.
Create worktree "auth-refactor" for task 1, then bind task 2 to "ui-login".
Run "git status" in worktree "auth-refactor".
Remove worktree "auth-refactor" with complete_task=true.

s12 关键洞察 & 全序列回顾

s12 是隔离的最后一级。从 s01 的"一个目录、一切共享"，到 s02 的路径沙箱，到 s04 的上下文隔离，到 s09 的线程隔离，到 s12 的目录级隔离——每个 Agent 在自己的 git worktree 目录里工作，文件互不干扰。

12 个 session 的全景图

Phase 1: The Loop           Phase 2: Planning & Knowledge
s01 ─ 核心循环              s03 ─ TodoWrite（内存规划）
s02 ─ 工具分发              s04 ─ Subagent（上下文隔离）
                            s05 ─ Skill 加载（按需知识）
                            s06 ─ 上下文压缩（策略遗忘）

Phase 3: Persistence        Phase 4: Teams
s07 ─ 任务系统（DAG+磁盘）   s09 ─ Agent 团队（收件箱通信）
s08 ─ 后台任务（线程异步）   s10 ─ 团队协议（请求-响应 FSM）
                            s11 ─ 自主 Agent（自组织认领）
                            s12 ─ Worktree 隔离（目录硬隔离）

三句贯穿始终的原则

模型看管判断，harness 看管执行 — 模型决定"做什么"，harness 决定"能做什么"和"做完了怎么办"。从 s01 的 run_bash 到 s12 的 worktree_remove，这个原则没变过。
加能力不加代码，改循环不碰核心 — 所有能力增量都是 dispatch map 加一行 + TOOLS 数组加一个 schema。核心循环从 s02 之后就稳定了，12 个 session 只是不断往同一条循环上叠机制。
状态在对话之外 — s03 的 todo 在内存里会丢 → s07 的 task 在磁盘上持久 → s12 的 worktree index 和 events 提供完整的崩溃恢复。每一步都在把状态往外拉，拉到模型和对话之外的文件系统里。

三、s_full：全机制集成

s_full.py 不是第 13 个 session，它是 s01-s11 的集成品（s12 是独立教学，不包含在内）。源码注释写得很直白：

"Capstone implementation combining every mechanism from s01-s11. NOT a teaching session -- this is the 'put it all together' reference."

独立 session 里，每个机制是替换式演示——s03 替换了 s02 的 todo 机制，s07 替换了 s03。s_full 是同时运行所有机制。36KB、740 行代码，用清晰的 # === SECTION: xxx === 标签标注了每个模块的来源。

18 个 SECTION 标签——源码自带的映射表

# === SECTION: base_tools ===              # s02 的基础工具函数
# === SECTION: todos (s03) ===             # s03 的 TodoManager
# === SECTION: subagent (s04) ===          # s04 的 run_subagent
# === SECTION: skills (s05) ===            # s05 的 SkillLoader
# === SECTION: compression (s06) ===       # s06 的 microcompact + auto_compact
# === SECTION: file_tasks (s07) ===        # s07 的 TaskManager（磁盘持久化）
# === SECTION: background (s08) ===        # s08 的 BackgroundManager
# === SECTION: messaging (s09) ===         # s09 的 MessageBus
# === SECTION: shutdown + plan tracking (s10) ===  # s10 协议追踪器
# === SECTION: team (s09/s11) ===          # s09+s11 融合的 TeammateManager（含自主认领）
# === SECTION: global_instances ===        # 所有模块实例化
# === SECTION: system_prompt ===           # 集成了 skill 列表的 system prompt
# === SECTION: tool_dispatch (s02) ===     # 23 个工具的 dispatch map
# === SECTION: agent_loop ===              # 集成循环——所有机制叠加
# === SECTION: repl ===                    # 外壳 + /compact /tasks /team /inbox 命令

全局实例化——一次性创建所有模块

TODO = TodoManager()
SKILLS = SkillLoader(SKILLS_DIR)
TASK_MGR = TaskManager()
BG = BackgroundManager()
BUS = MessageBus()
TEAM = TeammateManager(BUS, TASK_MGR)

6 个全局实例，对应 6 个 session 的机制。注意 TeammateManager 的构造函数现在接受 BUS 和 TASK_MGR——s_full 里的 TeammateManager 不是 s09 的复制粘贴，它把自主认领（s11）和任务看板（s07）直接集成在一起了。队友在 idle 期间自动扫描 TASK_MGR 找未认领任务。

工具 dispatch map——23 个工具

TOOL_HANDLERS = {
    # 基础 (4):  bash, read_file, write_file, edit_file
    # s03:       TodoWrite
    # s04:       task (subagent)
    # s05:       load_skill
    # s06:       compress
    # s08:       background_run, check_background
    # s07:       task_create, task_get, task_update, task_list
    # s09/s11:   spawn_teammate, list_teammates, send_message,
    #            read_inbox, broadcast, idle, claim_task
    # s10:       shutdown_request, plan_approval
}

23 个工具，是各独立 session 的并集。每个工具的 handler 写法完全一致——dispatch map 加一行。独立 session 的 handler 和 s_full 的 handler 几乎可以直接 diff 对比。

集成循环——所有机制叠加的时刻

这是 s_full 最核心的部分。每次 LLM 调用前，四条管线按序执行：

def agent_loop(messages: list):
    rounds_without_todo = 0
    while True:
        # ── 管线 1: s06 压缩层 ──
        microcompact(messages)
        if estimate_tokens(messages) > TOKEN_THRESHOLD:
            print("[auto-compact triggered]")
            messages[:] = auto_compact(messages)

        # ── 管线 2: s08 后台任务通知 ──
        notifs = BG.drain()
        if notifs:
            txt = "\n".join(
                f"[bg:{n['task_id']}] {n['status']}: {n['result']}"
                for n in notifs
            )
            messages.append({
                "role": "user",
                "content": f"<background-results>\n{txt}\n</background-results>"
            })

        # ── 管线 3: s10 收件箱检查 ──
        inbox = BUS.read_inbox("lead")
        if inbox:
            messages.append({
                "role": "user",
                "content": f"<inbox>{json.dumps(inbox, indent=2)}</inbox>"
            })

        # ── LLM 调用（23 个工具）──
        response = client.messages.create(
            model=MODEL, system=SYSTEM, messages=messages,
            tools=TOOLS, max_tokens=8000,
        )
        messages.append({"role": "assistant", "content": response.content})
        if response.stop_reason != "tool_use":
            return

        # ── 工具执行 ──
        results = []
        used_todo = False
        manual_compress = False
        for block in response.content:
            if block.type == "tool_use":
                handler = TOOL_HANDLERS.get(block.name)
                output = handler(**block.input) if handler else f"Unknown tool: {block.name}"
                results.append({
                    "type": "tool_result", "tool_use_id": block.id,
                    "content": str(output)
                })
                if block.name == "TodoWrite":
                    used_todo = True

        # ── 管线 4: s03 nag 提醒（条件化：只在有未完成 todo 时才催）──
        rounds_without_todo = 0 if used_todo else rounds_without_todo + 1
        if TODO.has_open_items() and rounds_without_todo >= 3:
            results.append({
                "type": "text",
                "text": "<reminder>Update your todos.</reminder>"
            })

        messages.append({"role": "user", "content": results})

对比 s03 独立版的 nag 是无条件注入（每 3 轮必催），s_full 加了 TODO.has_open_items() 守卫——只有在 TodoWrite 里还有未完成任务时才催。这是一个集成时才暴露出来的优化：当用户没在用 todo 模式时，nag 是噪音。

独立 session vs s_full 对照

独立 session	干什么	s_full 中的位置	集成方式
s01 loop	核心 while True	`agent_loop()` 函数	外层容器，不变
s02 dispatch	工具映射	`TOOL_HANDLERS` + `TOOLS`	23 条目的大字典
s03 TodoWrite	内存规划	`TodoManager` class	nag 条件化（有 open items 才催）
s04 subagent	上下文隔离	`run_subagent()`	作为 `task` 工具，支持 `agent_type` 参数
s05 skills	按需知识	`SkillLoader` class	名字进 system prompt，`load_skill` 进 dispatch
s06 compact	压缩	`microcompact` + `auto_compact`	每次 LLM 调用前置
s07 tasks	磁盘任务	`TaskManager` class	5 个 task 工具，`.tasks/` 目录
s08 background	后台线程	`BackgroundManager` class	drain 通知 + 注入
s09 teams	多 Agent	`MessageBus` + `TeammateManager`	收件箱注入 + spawn/msg/bcast
s10 protocols	请求响应	shutdown + plan 处理器	request_id 追踪 + FSM
s11 autonomy	自组织	集成在 `TeammateManager` 中	idle cycle + auto-claim

循环的不变结构

从 s01 到 s_full，骨架没变过：

s01 循环:   API 调用 → 执行工具 → 追加结果 → 重复

s_full 循环: microcompact → auto_compact(if needed)
              → drain bg → drain inbox
              → API 调用 → 执行工具
              → nag reminder → manual compact(if needed)
              → 重复

同一层 while stop_reason == 'tool_use' 循环，s01 只有 3 步，s_full 在前面挂了 4 个钩子（压缩 → 后台通知 → 收件箱 → LLM 调用），在后面挂了 2 个钩子（nag 提醒 → 手动压缩）。骨架不变，只在入口和出口挂钩子。 这就是整个项目最核心的架构美学——循环是平台，机制是插件。

REPL 外壳

if __name__ == "__main__":
    history = []
    while True:
        query = input("\033[36ms_full >> \033[0m")
        if query.strip().lower() in ("q", "exit", ""): break
        if query.strip() == "/compact": ...          # 手动压缩
        if query.strip() == "/tasks": ...            # 查看任务看板
        if query.strip() == "/team": ...             # 查看团队名册
        if query.strip() == "/inbox": ...            # 查看收件箱
        history.append({"role": "user", "content": query})
        agent_loop(history)

4 个 / 斜杠命令绕过 LLM 直接查询 harness 状态。和 s01 的 REPL 对比——s01 只有 input() + agent_loop()，s_full 多了 4 条本地控制通道。

关键洞察

s_full 展示的不是"如何写一个大 Agent"，而是如何让 11 个小机制和平共处。每个组件（TodoManager、SkillLoader、BackgroundManager、MessageBus、TaskManager、TeammateManager）是独立可测试的类，agent_loop 只是一条把它们串起来的装配线。

独立 session 就像乐高说明书——每一页只展示一个零件。s_full 是把所有零件拼在一起的结构图。你不需要从 s_full 开始学习——你会迷路。但当你理解了每个独立 session 后回看 s_full，740 行代码就像一本打开的手册，每一段都标注了出处。

四、真实 Claude Code vs s_full

s_full 是骨架，真实 Claude Code（以下简称 CC）是一头猛兽。先看一眼规模差距：

	s_full.py	真实 CC
代码量	740 行 Python	512,664 行 TypeScript
文件数	1	1,884 个 .ts/.tsx
语言/运行时	Python	TypeScript / Bun
工具数	23	~40+
UI	`input()` + `print()`	React + Ink（终端渲染框架）

架构骨架——完全一致

s_full 的核心循环和真实 CC 同源，只是 hooks 的数量不同：

s_full 循环:                    真实 CC 循环:
microcompact                     microcompact
auto_compact (if needed)         auto_compact (if needed)
drain background                 drain background
drain inbox                      drain inbox
                                 → run pre-tool hooks       ← 新增
                                 → check permissions        ← 新增
API call                         API call
tool dispatch                    tool dispatch (+ 并发控制)
                                 → run post-tool hooks      ← 新增
                                 → extract memories         ← 新增
nag reminder                     system-reminder 注入
manual compact                   /compact 命令

骨架没变——while stop_reason == 'tool_use' 还是那层循环。但 CC 在循环入口和出口各挂了更多钩子。

能力分层图

s_full (740 行)                    真实 CC (512K 行)
┌─────────────────┐          ┌──────────────────────────┐
│   Agent Loop    │          │     Agent Loop            │
│ + Tool Dispatch │          │   + Tool Dispatch         │
│ + TodoWrite     │          │   + TodoWrite             │
│ + Subagent      │          │   + Subagent (forkable)   │
│ + Skills        │          │   + Skills (17 bundled)   │
│ + Compact       │          │   + Compact (multi-level) │
│ + TaskManager   │          │   + Task System (6 types) │
│ + Background    │          │   + Background (remote)   │
│ + MessageBus    │          │   + Swarm (teammates)     │
│ + Team          │          │   + Coordinator Mode      │
│ + Protocols     │          │   + Protocols             │
├ ─ ─ ─ ─ ─ ─ ─ ─ ┤          ├──────────────────────────┤
│ (缺失)          │          │ + Permission Engine      │  ← 本章
│ (缺失)          │          │ + Memory System          │
│ (缺失)          │          │ + Hook System            │
│ (缺失)          │          │ + MCP Integration        │
│ (缺失)          │          │ + IDE Bridge             │
│ (缺失)          │          │ + Plugin System          │
│ (缺失)          │          │ + React/Ink UI           │
│ (缺失)          │          │ + OAuth / Enterprise     │
└─────────────────┘          └──────────────────────────┘

虚线以上：s_full 已覆盖。虚线以下：真实 CC 独有的系统。本章逐一拆解。

五、权限系统——从硬编码关键词到决策引擎

s_full 的"权限系统"只有 5 个硬编码关键词：

dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"]
if any(d in command for d in dangerous):
    return "Error: Dangerous command blocked"

真实 CC 的权限系统是一个完整的决策引擎，核心文件近 10 个，超过 4000 行代码。它要回答的不是"这个命令危险吗"，而是"在当前上下文、当前权限模式、当前规则配置下，这个操作应该被允许、拒绝、还是询问用户？"

5.1 三级决策模型

每个工具调用需要经过三层裁决：

allow  ── 直接放行
deny   ── 直接拒绝（带理由）
ask    ── 弹出对话框问用户

不是二元的"危险/安全"，而是三元。ask 的存在意味着权限系统承认自己不知道——把决定权交给用户。

5.2 权限模式——用户主动选择的信任级别

// 六种模式，从最严格到最宽松
type PermissionMode =
  | 'default'            // 正常询问
  | 'plan'               // 计划模式（只读，写操作需审批）
  | 'acceptEdits'        // 自动接受文件编辑
  | 'bypassPermissions'  // 跳过所有权限检查
  | 'dontAsk'            // 不问，直接拒绝（无头模式）
  | 'auto'               // AI 分类器自动决策（ant-only）

用户通过 --permission-mode 命令行参数或 /permissions 斜杠命令切换。不同模式对应不同信任场景——bypassPermissions 是你完全信任 Agent 时用的，dontAsk 是 CI/CD 无人值守时用的。

5.3 权限规则——用户可配置的精确控制

权限规则不是简单的关键词，而是结构化的匹配器。用户在 settings.json 里写：

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",      // 允许 npm run 开头的所有命令
      "Bash(git diff *)",     // 允许 git diff
      "WebFetch",             // 允许整个 WebFetch 工具
      "Read(MCP__github_*)", // 允许读取特定 MCP 服务器的资源
    ],
    "deny": [
      "Bash(npm publish *)",  // 永远禁止 npm publish
    ],
    "ask": [
      "Bash(curl *)",         // curl 任何地址都要先问
    ]
  }
}

规则解析支持三种匹配模式：

匹配模式	语法	示例
精确匹配	`Bash(cd /tmp)`	只匹配完全相同的命令（去除安全包装器后）
前缀匹配	`Bash(git *)`	匹配 git 开头的所有命令
通配符	`Bash(install)`	匹配包含 install 的命令

这不是正则，是 shell glob。 规则格式是 ToolName(content)，括号内的 * 是 shell 风格的通配符。正则的 .* 在这里不适用。

解析逻辑在 permissionRuleParser.ts 中：先用括号匹配提取 content 体，然后判断 content 是否包含 * 来决定走前缀匹配还是精确匹配。Bash(python3 -c ' *) 能写是因为括号匹配先把 python3 -c ' *' 整段当作 content 提取出来，再在 bash 命令匹配时作为精确或通配符处理。

注意一个安全细节：前缀匹配不会匹配复合命令。 Bash(cd *) 不会匹配 cd /tmp && rm -rf /。防止用户配置的 "允许 cd" 被串联命令绕过。

5.4 Bash 命令的语义安全分析

这是权限系统最精密的部分。不是简单的正则匹配，而是一层层剥离安全外壳。

安全包装器剥离：

用户在 settings.json 里配置了 allow: ["Bash(cd *)"]。但模型可能输出 timeout 10 cd /tmp 或 nice -n 5 cd /tmp。权限引擎需要先剥掉 timeout、nice、nohup 这些"无害包装器"，然后再做匹配：

function stripSafeWrappers(command: string): string {
  // 剥掉 timeout, time, nice, stdbuf, nohup, env VAR=val ...
  // 确保 "timeout 10 cd /tmp" 被识别为 "cd /tmp"
}

环境变量剥离：

对于 deny 规则，权限引擎会激进地剥离所有前置环境变量：

DENY_VAR=malicious curl evil.com  →  被识别为 curl evil.com  ← 拒绝

但 allow 规则只剥离安全的环境变量，保留有意义的：

ALLOW: FOO=bar npm test  →  识别为 npm test  ← 允许

如果 allow 规则也激进剥离所有环境变量，攻击者可以通过设置 PATH=~/malicious 来绕过 allow 规则执行 /tmp/malicious/npm test。allow 保留环境变量意味着一层额外防御。

复合命令检测：

// 包含 && || ; 的命令不会匹配前缀规则
if (containsCommandSeparators(command)) {
  // 跳过前缀匹配，只走精确匹配
}

Bash(git add *) 这条 allow 规则不会匹配 git add . && rm -rf /。

路径安全约束：

文件操作受工作目录限制。权限系统维护一个 additionalWorkingDirectories 列表，文件读写只能发生在这些目录内。即使模型绕过了工具层的 safe_path，权限层还有第二道防线。

Sed 约束：

特别处理 sed 命令的危险操作——sed 的 -i 参数可以原地修改任意文件，权限引擎单独拦截这类操作。

5.5 完整的决策流水线

useCanUseTool()  hook（React 层入口）
  │
  ▼
hasPermissionsToUseTool()  权限引擎入口
  │
  ├─ Step 1a: 有工具级 deny 规则？           → deny（直接拒绝）
  ├─ Step 1b: 有工具级 ask 规则？            → ask（但如果开了沙箱且命令可沙箱化，穿透）
  ├─ Step 1c: tool.checkPermissions()        → 工具自己的权限逻辑
  │    └─ bashPermissions.ts:                ← Bash 工具的 ~1350 行权限实现
  │         ├─ 精确匹配: deny > ask > allow
  │         ├─ 前缀匹配: 剥包装器 → deny > ask > allow
  │         ├─ 路径约束检查
  │         ├─ 精确 allow？→ allow
  │         ├─ 前缀 allow？→ allow
  │         ├─ Sed 约束检查
  │         ├─ 模式检查
  │         └─ 只读命令？→ 自动 allow
  ├─ Step 1d: 工具返回 deny？                → deny
  ├─ Step 1e: 工具要求用户交互？              → ask（不可绕过）
  ├─ Step 1f-g: 内容级规则 / 安全检查？       → 尊重规则结果
  │
  ├─ Step 2a: bypassPermissions 模式？        → allow（全跳过）
  ├─ Step 2b: 工具有全局 allow 规则？         → allow
  │
  └─ Step 3: 穿透 → ask                        → 弹对话框

  ↓ 后处理 ↓
  dontAsk 模式: ask → deny
  auto 模式:    acceptEdits 快速路径
                → 安全工具白名单
                → AI 分类器（YOLO）
                → 拒绝追踪（超限回退到询问）
  无头 Agent:   → PermissionRequest hooks → 无 hook 决定则 deny

5.6 安全路径检查——绕过免疫

有几种安全路径的 ask 决策是不可绕过的，即使开了 bypassPermissions：

const SAFETY_PATHS = [
  '.git/',        // 修改 git 内部文件
  '.claude/',     // 修改 Claude 配置
  '.vscode/',     // 修改 IDE 配置
  'shell config', // 修改 .bashrc / .zshrc
]

这不是配置项，是硬编码在权限引擎里的。操作这些路径时，即使 bypassPermissions 模式也会降级为 ask。防止 Agent 被诱导修改自己的安全配置或版本控制系统。

5.7 Auto 模式的 AI 分类器——"让 AI 审 AI"

auto 模式（ant-only）引入了一个元层次：用一个 AI 查询来判断另一个 AI 的操作是否安全。

模型想执行 "git push origin main"
  │
  ▼
权限引擎 → auto 模式
  │
  ├─ acceptEdits 快速路径？（编辑操作 → 自动允许）
  ├─ 安全白名单？（bash read/grep/find → 自动允许）
  ├─ 都未命中 → AI 分类器
  │    │
  │    └─ 侧查询 Sonnet:
  │        "评估这个操作：git push origin main
  │         上下文：用户正在重构 auth 模块
  │         意图：将更改推送到远程"
  │         → { safe: true, confidence: 0.95 }
  │              │
  │              ▼
  │         allow（高置信度 → 自动允许）
  │
  └─ 分类器不可用？→ fail-closed 或 fail-open
       （用 GrowthBook 标志控制）

拒绝追踪：如果 AI 分类器拒绝了太多次，系统会回退到正常的 ask 模式弹对话框，不再替用户做决定。防止分类器误判导致 Agent 卡住。

5.8 权限规则来源优先级

规则不是只来自一个地方。权限引擎合并多个来源，按优先级排序：

CLI 参数 --permission-allow     最高优先级（用户当场明确指定）
session 规则                    会话级临时规则
local settings.json             .claude/settings.local.json（不提交 git）
project settings.json           .claude/settings.json（项目级，共享）
user settings.json              ~/.claude/settings.json（全局）
policy settings                 企业 IT 管理员推送的规则（不可覆盖）

policySettings 是一个特别的设计——企业管理员可以配置强制规则，用户不能在自己的 settings.json 里覆盖。比如强制 deny: ["Bash(sudo *)", "Bash(rm *)"]。

5.9 和 s_full 的对比

维度	s_full	真实 CC
决策模型	二元（通过/拒绝）	三元（allow/deny/ask）
规则粒度	5 个硬编码字符串	工具级 + 内容级 + 前缀/通配符
Bash 分析	`'sudo' in command`	包装器剥离 + 环境变量剥离 + 复合命令检测 + Sed 约束 + 路径约束
用户控制	无	6 种权限模式 + 自定义规则 + `/permissions` 命令
安全检查	无	bypass-immune 安全路径 + 拒绝追踪
无头模式	不适用	dontAsk 模式 + PermissionRequest hooks
规则来源	1（代码）	7 个来源，优先级排序
可扩展性	改 Python 代码	改 JSON 配置文件

核心洞察

权限系统不是"阻止危险命令"——那是最低层次的目标。真正的权限引擎是一个策略框架：你在定义的不是"什么不能做"（黑名单），而是"在不同信任级别下，谁可以决定什么操作被允许"。

s_full 的 dangerous = ["rm -rf /"] 把决策权给了代码作者。真实 CC 把决策权给了用户 + 管理员 + AI 分类器 + 权限规则四方协商。这就是从 "dangerous list" 到 "permission engine" 的跨越：不是判断对错，是判断谁有资格判断对错。

六、记忆系统——从"对话即忘"到"跨会话记忆"

s_full 不持久化任何对话记忆。进程退出，一切清零。真实 CC 有一套完整的持久化记忆系统——对话结束了，但关于你和项目的信息保留下来，下次对话自动加载。

6.1 四种记忆类型

CC 的记忆系统不是"记住一切"，而是精细分类：

类型	用途	示例
user	你是谁，怎么和你协作	"用户是数据科学家，偏好 Python 而非 R"
project	项目背景、目标、进度	"周五之前冻结所有非关键合并"
feedback	你给的纠正和确认	"别 mock 数据库，上次因为 mock 生产事故"
reference	外部系统指针	"pipeline bug 在 Linear 项目 INGEST 里跟踪"

每种类型有自己的一套保存规则和何时加载的策略。memory 不只是"存东西"，而是"知道什么该存、什么不该存"。

6.2 什么不该存

系统 prompt 明确列出了不应保存的内容：

- 代码模式、命名约定、架构 → 看当前代码就行
- git 历史、最近变更 → git log / git blame 才是权威
- 调试方案、修复 recipe → 修正在代码里，commit message 有上下文
- CLAUDE.md 里已有的内容 → 别重复
- 临时任务细节 → 进程中状态、当前对话上下文

这套排除规则保证记忆库是信号而不是噪音。没有这些规则，记忆库会变成一个不可维护的日志 dump。

6.3 记忆的存储模型——文件即数据库

~/.claude/projects/<sanitized-git-root>/memory/
  ├── MEMORY.md              ← 索引文件（总是加载）
  ├── user_role.md            ← 用户角色记忆
  ├── feedback_testing.md     ← 关于测试的反馈
  ├── project_deadline.md     ← 项目截止日期
  └── reference_linear.md     ← Linear 项目指针

不是 SQLite，不是 Redis，是 Markdown 文件 + YAML frontmatter。每个记忆是一个独立的 .md 文件：

---
name: feedback-testing
description: 测试策略反馈
type: feedback
---

集成测试必须用真实数据库，别 mock。
**Why:** 上次 mock 导致生产迁移事故
**How to apply:** 任何涉及数据库的测试都要连真实 DB

MEMORY.md 是索引——每条一行，~150 字以内：

- [Testing feedback](feedback_testing.md) — 集成测试必须用真实数据库
- [PR freeze](project_deadline.md) — 周五前冻结所有非关键合并

索引始终加载到上下文，正文按需加载。索引有硬上限：200 行、25KB——防止记忆过多撑爆 system prompt。

6.4 记忆的两种创建路径

路径 A：模型主动写入（主 Agent）

模型在对话中被触发（或自发）写记忆。两步操作：

创建/更新 user_role.md（写 YAML frontmatter + 正文）
在 MEMORY.md 里加一行索引

system prompt 里有完整的写入指南，模型知道什么时候该写、写什么格式。用户也可以说"记住这个"，模型照做。

路径 B：后台自动提取（AutoMem Agent）

每次对话结束后，一个独立的 forked Agent（共享父 Agent 的 prompt cache，但有自己的消息列表）被 fire-and-forget 启动。它的工作是：

分析最近几轮对话
判断是否有值得永久保存的信息
如有，写/更新记忆文件
更新 MEMORY.md 索引

关键设计：如果主 Agent 已经在对话中手动写了记忆文件，自动提取会跳过——避免重复。通过 hasMemoryWritesSince() 检查文件修改时间戳实现。

// 自动提取 Agent 的工具权限严格受限
// 只开放：只读 Bash + Read/Grep/Glob + 仅 memory 目录的 Edit/Write
function createAutoMemCanUseTool(memoryDir: string): CanUseToolFn {
  // Bash: 只读（不允许修改文件）
  // Write/Edit: 只允许 memoryDir 路径
}

自动提取 Agent 开了 5 轮的最大限制——不需要多轮，看一眼最近对话就能判断。

6.5 记忆检索——"什么时候该回忆"

每轮对话开始时，CC 做一次异步预取（prefetch）：

用户输入
  │
  ▼
startRelevantMemoryPrefetch()
  │
  ├─ 扫描 memory/ 下所有 .md 文件的前 30 行（frontmatter 范围）
  │    └─ 提取 description + type，生成"记忆清单"
  │
  ├─ 用 Sonnet 做侧查询（side query）：
  │    "用户问的是：'重构 auth 模块的 token 处理'
  │     可用记忆：
  │       1. [project] auth middleware rewrite 由合规要求驱动
  │       2. [feedback] 不要 mock 数据库
  │       3. [reference] 监控看板在 grafana.internal/d/api-latency
  │     选最多 5 条相关的"
  │
  ├─ Sonnet 返回：["1", "2"]  ← 选中的记忆
  │
  └─ 读取完整内容，作为 <system-reminder> 注入下一轮消息

Sonnet 侧查询是非阻塞的——和主模型并行运行。等主模型下一轮 API 调用时，记忆已经准备好插入了。

注入格式：

<system-reminder>
Memory (saved 3 days ago): feedback_testing.md:
集成测试必须用真实数据库，别 mock。
**Why:** 上次 mock 导致生产迁移事故
</system-reminder>

注意 (saved 3 days ago) 这个时间戳：如果记忆超过 1 天，系统还会追加一句话："记忆是 N 天前的观察，不是实时状态。如果和当前代码冲突，相信代码。"

6.6 去重——别重复加载

记忆系统在三个层面去重：

本会话内已加载的不重复 — collectSurfacedMemories() 追踪哪些文件已被注入过
模型自己刚读过的不重复 — filterDuplicateMemoryAttachments() 检查本轮 FileRead 操作，如果模型已经读了 project_deadline.md，就跳过
和现有上下文冲突的不重复 — 记忆文件的内容和 messages 里已有的信息比较，太相似的不注入

6.7 安全约束

记忆系统有自己的安全防线：

路径验证 — validateMemoryPath() 拒绝 ..、绝对路径、Windows 盘符、空字节。攻击者不能通过构造恶意项目路径让 CC 写到 ~/.ssh/
设置来源限制 — 记忆目录路径的设置不接受 project settings。.claude/settings.json（项目级）不能重定向记忆写到恶意目录
写 carve-out — 文件记录权限对记忆目录有写 carve-out，但只在非 Cowork 模式

6.8 和 s_full 的对比

维度	s_full	真实 CC
记忆存储	无（进程退出即清零）	文件系统持久化（`~/.claude/projects/`）
记忆类型	无	四种：user/project/feedback/reference
创建方式	—	主 Agent 手动 + AutoMem 自动提取
检索方式	—	Sonnet 侧查询（最多选 5 条）
注入位置	—	`<system-reminder>` 包装的 user 消息
冲突处理	—	去重 + 时间戳 + "可能过时"警告
安全约束	—	路径验证 + 设置来源限制

核心洞察

记忆系统的设计哲学是：不是"记住一切"，是"在正确的时刻回忆起正确的事"。 四种类型的分类、严格的排除规则、Sonnet 侧查询的按需检索、去重和时间戳衰减——所有机制都在精确控制"多少记忆进入上下文"。

这里有一个巧妙的博弈：记忆系统为了让模型记住重要信息，首先得让模型忘记不重要的事（通过排除规则），然后才在每轮对话开始时悄悄塞入相关信息（<system-reminder> 不炸裂 prompt cache）。记忆不是"更大的 context window"的替代品——它是"更聪明的 context window"的构建方式。

七、Hook 系统——把 Agent 变成可编程平台

s_full 没有 hooks。真实 CC 的 hook 系统是整个架构中最灵活、最危险的扩展点——它允许外部代码在 Agent 循环的 28 个关键时刻介入、修改、甚至阻止操作。

7.1 28 个 Hook 事件——Agent 循环的"切口"

Hook 系统在 Agent 生命周期的每个节点都开了口：

类别	事件	触发时机
生命周期	`SessionStart`, `Setup`, `SessionEnd`	会话开始/设置/结束
工具执行	`PreToolUse`, `PostToolUse`, `PostToolUseFailure`	工具调前/调后/失败
对话	`UserPromptSubmit`, `Stop`, `StopFailure`	用户输入/Agent 停止/停止失败
权限	`PermissionRequest`, `PermissionDenied`	权限申请/拒绝
压缩	`PreCompact`, `PostCompact`	上下文压缩前后
Subagent	`SubagentStart`, `SubagentStop`	子 Agent 启动/停止
协作	`TeammateIdle`, `TaskCreated`, `TaskCompleted`	队友空闲/任务创建/任务完成
MCP	`Elicitation`, `ElicitationResult`	MCP 询问/结果
通知	`Notification`	系统通知
配置	`ConfigChange`	配置变更
Worktree	`WorktreeCreate`, `WorktreeRemove`	Worktree 创建/删除
文件	`CwdChanged`, `FileChanged`	目录切换/文件变更
指令	`InstructionsLoaded`	指令加载完成

不在代码里硬编码"遇到 X 就做 Y"——而是把 X 时刻暴露出来，让用户挂自己的逻辑。

7.2 四种 Hook 执行器——不同的"外部逻辑"

用户可以为每个 hook 事件配置四种类型的执行器：

类型	执行方式	适用场景	延迟
command	启动 shell 进程，JSON 走 stdin，结果读 stdout	本地脚本、lint、格式化、通知	快（进程启动）
prompt	单轮 LLM 查询（默认 Haiku）	语义判断：这个命令危险吗？	中（API 调用）
agent	多轮 LLM Agent（最多 50 轮，有完整工具）	复杂决策：审查整个 PR 是否符合规范	慢（可能数轮）
http	POST JSON 到外部 URL	触发 CI/CD、发 Slack、调 webhook	取决于网络

Command hook 示例

在 .claude/settings.json 里配置：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git push *)",
        "command": "node scripts/check-branch-protection.js",
        "timeout": 5000
      }
    ]
  }
}

Agent 要执行 git push origin main 时，CC 先启动 check-branch-protection.js，把工具调用的 JSON 通过 stdin 传给它：

{
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {"command": "git push origin main"}
}

脚本 exit 0 → 放行。exit 2 → 阻止，stderr 给模型看原因。其他非零退出码 → 不阻止，stderr 只给用户看。

如果设置了 "async": true，进程启动后立即返回，不等待结果。适合发通知、写日志等不阻塞的场景。

Prompt hook 示例

{
  "matcher": "Bash",
  "prompt": "Is this bash command safe to execute in a production environment? Command: $ARGUMENTS",
  "model": "claude-haiku-4-5",
  "timeout": 10000
}

$ARGUMENTS 会被替换为完整的工具调用 JSON。模型返回 {"ok": true} 或 {"ok": false, "reason": "会在生产环境重启服务"}。默认用 Haiku——便宜、快、对二元判断足够用。

Agent hook 示例（最强）

{
  "matcher": "Write|Edit",
  "agent": "Review this file change for security issues, SQL injection, XSS vulnerabilities. The proposed change is: $ARGUMENTS",
  "timeout": 60000
}

Agent hook 有完整的工具访问权限——它能读文件、搜代码、跑 bash。一个合法的 50 轮 Agent 循环被启动，用 SyntheticOutputTool 强制输出结构化 JSON {ok: boolean, reason?: string}。

7.3 Hook 的权限和信任模型

不是任何 hook 都能在任何地方跑。CC 有多层信任控制：

来源过滤：

// Hook 配置有多个来源，按优先级排序：
CLI 参数 > session > settings.local > settings.json > user settings > policy > plugin

allowManagedHooksOnly： 企业管理员可以设置此标志，禁止所有非 policy 来源的 hook。防止恶意 repo 通过 .claude/settings.json 注入恶意 hook。

工作区信任检查： 在交互模式下，所有 hook 要求工作区被信任。防止 git clone 一个项目后，项目自带的 hook 自动执行。

HTTP hook 的 SSRF 保护：

// ssrfGuard.ts
function ssrfGuardedLookup(url: string) {
  const ip = await dns.resolve(hostname)
  // 阻止: 私有 IP + 链路本地地址
  // 允许: 公网 IP + localhost（本地开发用）
  if (isPrivateIP(ip) && !isLoopback(ip)) {
    throw new Error("SSRF blocked")
  }
}

HTTP hook 还有 URL 白名单机制——只有 allowedHttpHookUrls 中配置的 URL 模式才能接受 POST。

7.4 Hook JSON 输出协议——双向通信

Hook 不只是"允许或拒绝"——它可以通过 stdout 返回丰富的结构化输出：

// PreToolUse 的 hook 输出可以：
{
  "continue": false,              // 阻止工具执行
  "stopReason": "Branch protected",  // 给模型的理由
  "decision": "block",            // 权限决定
  "systemMessage": "...",         // 给用户看的警告
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",   // 覆盖权限决定
    "updatedInput": {               // 修改工具输入！
      "command": "git push --force-with-lease origin main"
    },
    "additionalContext": "..."       // 注入额外上下文
  }
}

// PostToolUse 可以：
{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "updatedMCPToolOutput": "..."    // 替换 MCP 工具输出
  }
}

// SessionStart 可以：
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "initialUserMessage": "今天的任务是...",  // 注入第一条用户消息
    "watchPaths": ["src/auth/**"]       // 动态添加文件监控
  }
}

// PermissionDenied 可以：
{
  "hookSpecificOutput": {
    "hookEventName": "PermissionDenied",
    "retry": true                      // 允许模型重试
  }
}

最强大的能力是 updatedInput——hook 可以修改工具输入。git push origin main 被 hook 改成 git push --force-with-lease origin main，模型不知道发生了替换。

7.5 异步 Hook 管理

有些 hook 需要长时间运行但不阻塞 Agent：

{
  "command": "npm run long-running-check",
  "async": true,
  "asyncRewake": true,
  "asyncTimeout": 30000
}

async: true — 启动后立即返回，不等待
asyncRewake: true — hook 退出时如果是 exit 2（阻止），会注入一条任务通知唤醒 Agent
asyncTimeout: 30000 — 30 秒后强制清理

AsyncHookRegistry 跟踪所有后台 hook 进程，定期轮询检查完成状态。SessionEnd 时强制清理所有残留进程。

7.6 和 s_full 的对比

维度	s_full	真实 CC
Hook 系统	无	28 个事件 + 4 种执行器
扩展方式	改 Python 源码	写 JSON 配置 + 外部脚本
工具输入修改	不可	`updatedInput`（hook 可改模型输出）
异步执行	s08 的 background_run	`async: true` + AsyncHookRegistry
安全	—	来源过滤 + SSRF 保护 + 工作区信任
外部集成	无	HTTP POST + shell + prompt + agent

核心洞察

Hook 系统定义了"用户代码和 Agent 循环之间的界面"。它和之前各 session 的架构增量有本质区别：

s01-s12 的机制是内置的——harness 作者决定 Agent 能做什么
Hook 系统是开放的——用户决定 Agent 行为什么时候被拦截、修改、增强

Hook 不是调用外部工具——是把 Agent 循环本身变成了可编程的框架。updatedInput 的能力特别值得注意：hook 可以在模型不知道的情况下修改工具输入，这意味着安全策略可以和 Agent 逻辑完全解耦——模型的 prompt 不需要知道"生产环境禁止 force push"，hook 层的 PreToolUse 命令会拦截它。这条边界是整个架构中最锋利的一条线：一边是模型的世界（文本生成），一边是 harness 的世界（策略执行）。

八、MCP 集成——把外部工具变成 Agent 的原生能力

s_full 的工具全是 Python 函数。真实 CC 可以通过 MCP（Model Context Protocol）接入外部工具，包括第三方服务、数据库、API——不用写一行 TypeScript。

8.1 八种传输协议

MCP 服务器可以通过八种传输方式和 CC 通信：

传输	适用场景	特点
`stdio`	本地命令行工具	启动子进程，stdin/stdout 通信
`sse`	远程 HTTP 服务	Server-Sent Events，可选 OAuth
`http`	流式 HTTP API	`StreamableHTTP` 协议
`ws`	双向实时通信	WebSocket
`sdk`	进程内 SDK	直接内存调用，无序列化开销
`claudeai-proxy`	claude.ai 代理	通过 claude.ai OAuth 网关中继
`sse-ide` / `ws-ide`	IDE 内部	VS Code / JetBrains 内嵌 MCP 服务器

一个 MCP 服务器可以同时被多种传输接入。CC 根据 mcpServers 配置中的 type 选择传输。

8.2 连接生命周期

用户启动 CC / 修改 MCP 配置
  │
  ▼
MCPConnectionManager 读取配置
  │
  ├─ connectToServer(serverConfig)
  │    ├─ 创建 Transport（按 type）
  │    ├─ new Client("claude-code", { capabilities: [roots, elicitation] })
  │    ├─ client.connect(transport) ← 竞态 30s 超时
  │    └─ 成功后获取 server info + instructions
  │
  ├─ fetchToolsForClient() → tools/list
  │    └─ 每个 MCP 工具生成一个 CC Tool：
  │         name: "mcp__serverName__toolName"
  │         checkPermissions: 默认 passthrough
  │         annotations: { readOnlyHint, destructiveHint, openWorldHint }
  │
  ├─ fetchCommandsForClient() → prompts/list → 转成 slash commands
  └─ fetchResourcesForClient() → resources/list

连接断开时自动重连（指数退避 1s-30s，最多 5 次）。如果是会话过期（404 + JSON-RPC -32001），清理缓存后重连。

8.3 工具调用链路

模型: 调 mcp__github__search_repos({query: "claude code"})
  │
  ▼
CC Tool dispatch → MCPTool.call()
  │
  ├─ ensureConnectedClient()    ← 如果缓存过期，自动重连
  ├─ callMCPToolWithUrlElicitationRetry()
  │    └─ client.callTool(
  │         { name: "search_repos",
  │           arguments: {query: "claude code"},
  │           _meta: { progressToken }
  │         },
  │         CallToolResultSchema,
  │         { timeout: ~27.8h }
  │       )
  │
  ├─ 超时？→ MCP_TOOL_TIMEOUT 环境变量（默认几乎无限）
  ├─ URL Elicitation？→ 重试最多 3 次（每次让用户确认 URL）
  ├─ 401？→ McpAuthError → 提示用户重新认证
  └─ 会话过期？→ McpSessionExpiredError → 清缓存 + 重试一次
  │
  ▼
结果 → processMCPResult → transformMCPResult
  │
  ├─ text 内容 → 直接返回字符串
  ├─ image/audio → 作为 base64 content block 返回
  ├─ resource → 持久化到文件（大 output 走磁盘）
  └─ structuredContent → JSON 原样返回

8.4 权限处理

MCP 工具的权限模式是 passthrough——让主权限引擎处理：

// MCPTool.checkPermissions() 基类实现
checkPermissions() {
  return { behavior: 'passthrough' }
  // 建议用户配置: allow: ["mcp__github__*"]
}

用户可配置：

{
  "permissions": {
    "allow": [
      "mcp__filesystem__*",        // 允许整个 MCP 服务器的所有工具
      "mcp__github__search_*"      // 只允许 github 服务器的 search_ 开头工具
    ],
    "deny": [
      "mcp__database__drop_table"  // 禁止特定危险操作
    ]
  }
}

annotations 映射为 CC 的并发安全和破坏性标志：readOnlyHint → isConcurrencySafe、destructiveHint → isDestructive、openWorldHint → isOpenWorld。

8.5 和 s_full 的对比

维度	s_full	真实 CC
工具来源	硬编码 Python 函数	硬编码 + MCP 动态发现
扩展工具	改 dispatch map + 加函数	配置 JSON + 启动外部服务器
传输层	subprocess (bash)	8 种协议（stdio/sse/http/ws/sdk/...）
工具命名	`"bash"`, `"read_file"`	`mcp__{server}__{tool}` 命名空间隔离
权限	无	服务器级 / 工具级 / 前缀通配符
重连	不适用	指数退避 + 会话过期检测

核心洞察

MCP 是 CC 工具系统的"USB 接口"——外部工具的接入协议。CC 本身写了 ~40 个核心工具（bash、read、write、edit……），但剩下的能力通过 MCP 让第三方提供。命名空间 mcp__serverName__toolName 的设计隔离了不同 MCP 服务器的工具，避免冲突。

MCP 在架构上把"工具发现"和"工具执行"解耦了——MCPConnectionManager 负责发现（启动时拉取工具列表），权限引擎负责裁决（每次调前检查），MCPTool.call() 负责传输（HTTP / stdio / WebSocket）。三层独立，和 s02 的 TOOL_HANDLERS + TOOLS 双数组模式在概念上同源。

九、任务系统——从 JSON 文件到 7 种任务类型

s07 的 TaskManager 是磁盘上的 JSON。真实 CC 的任务系统有 7 种具体类型，统一在同一个注册/更新/驱逐框架下管理。

9.1 7 种任务类型

类型	类	用途
`local_bash`	LocalShellTask	后台 shell 命令（s08 的 background_run 的真实版本）
`local_agent`	LocalAgentTask	AgentTool 创建的子 Agent（s04 subagent 的真实版本）
`remote_agent`	RemoteAgentTask	远程主机上的 Agent
`in_process_teammate`	InProcessTeammateTask	同进程内的队友（s09 teammate 的真实版本）
`local_workflow`	LocalWorkflowTask	工作流编排
`monitor_mcp`	MonitorMcpTask	MCP 监控任务
`dream`	DreamTask	后台记忆巩固（AutoMem 的"做梦"阶段）

s_full 只有一种隐式任务（subagent 是一次性函数调用），真实 CC 把每类异步工作都建模为一种任务类型，统一管理。

9.2 统一的任务框架

所有 7 种类型共享同一套 API：

// 注册
registerTask(task, setAppState)        // → 写入 AppState.tasks
// 更新
updateTaskState(taskId, setAppState, updater)  // 类型安全的部分更新
// 驱逐
evictTerminalTask(taskId, setAppState) // 终端态 + 已通知 + 超 grace period → 清除

任务状态变更通过 task_started SDK 事件广播。每个任务有独立的 TASK_OUTPUT_DIR 写入磁盘输出，支持增量交付（1s 轮询）。

9.3 InProcessTeammate——s09 teammate 的真实形态

s09 的 teammate 是一个 Python 线程 + JSONL 收件箱。真实 CC 的方案复杂得多：

spawnInProcessTeammate(config, context)
  │
  ├─ agentId = "name@teamName"         ← 全局唯一标识
  ├─ 创建 TeammateIdentity             ← 存在 AppState
  ├─ 创建 AbortController              ← 用于 kill
  ├─ 创建 TeammateContext              ← AsyncLocalStorage 隔离
  │    └─ 每个 teammate 的上下文完全隔离，不能互相访问
  │
  ├─ AppState 注册 InProcessTeammateTaskState
  │    { type: 'in_process_teammate',
  │      isIdle: false,
  │      pendingUserMessages: [],
  │      awaitingPlanApproval: false }
  │
  └─ 队友启动 agent loop
       │
       ├─ 与 lead 共享同一进程
       ├─ 有自己的 permissionMode
       ├─ 可以 idle（self-set）
       ├─ 可以收到 shutdown_request（类似 s10）
       └─ killInProcessTeammate() → abort controller + 清理 TeamFile

TeamFile 存在 ~/.claude/teams/{teamName}/config.json——和 s09 的 .team/config.json 功能一样但结构更完整：

interface TeamFile {
  name: string
  leadAgentId: string
  members: {
    agentId: string
    name: string
    cwd: string
    backendType: 'in-process' | 'remote'
    subscriptions: string[]     // 订阅的事件类型
    isActive: boolean
    mode: string
  }[]
  teamAllowedPaths: string[]
}

9.4 和 s_full 的对比

维度	s_full	真实 CC
任务类型	1 (TaskManager JSON)	7 (local_bash / local_agent / remote / teammate / workflow / dream / monitor)
子 Agent	run_subagent() 函数调用	LocalAgentTask（有 lifecycle、progress、权限）
Teammate	TeammateManager 线程	InProcessTeammateTask（AsyncLocalStorage 隔离）
任务框架	无	registerTask / updateTaskState / evictTerminalTask
磁盘输出	.tasks/*.json	TASK_OUTPUT_DIR + 增量交付
TeamFile	.team/config.json	~/.claude/teams/{name}/config.json（更完整）

核心洞察

任务系统的核心贡献是把所有异步工作统一为一种抽象。shell 命令、子 Agent、远程 Agent、队友、dream——它们都是"任务"，共享同一个注册/更新/驱逐生命周期。这和 s07 的 DAG 设计一脉相承——s07 用 JSON 文件和 blockedBy 做依赖管理，真实 CC 用 TypeScript 类型系统和 task 框架做统一管理。前者教会你"任务应该有状态"，后者告诉你"不同类型的工作应该共享同一个状态机"。

十、插件系统 + IDE Bridge——Agent 进入生态

真实 CC 的最后两个大系统：插件生态（让其他人写扩展）和 IDE 桥接（让 CC 嵌入编辑器）。

10.1 插件系统——Extension Points

插件通过 .claude-plugin/ 目录中的声明文件扩展 CC：

文件	能力	对应 s_full
`commands/*.md`	注册新的 `/` 斜杠命令	s05 skill 的超集
`agents/*.md`	注册 Agent 定义（带工具白名单、system prompt、模型）	s04 subagent 的可配置版
`hooks/hooks.json`	注册 hook 回调	s_full 完全没有
`plugin.json`	元数据 + 版本 + 用户配置 schema	s_full 完全没有

插件安装流程：

用户: /plugin install my-plugin@marketplace
  │
  ▼
resolveDependencyClosure()       ← 解析依赖图
  │
  ▼
settings.json: enabledPlugins += 整个闭包
  │
  ▼
cacheAndRegisterPlugin()         ← 下载/拷贝到 ~/.claude/plugins/cache/
  │
  ▼
assemblePluginLoadResult()       ← 合并 marketplace + session + built-in
  │
  ▼
loadPluginCommands()             ← 注册斜杠命令
loadPluginAgents()               ← 注册 Agent 类型
loadPluginHooks()                ← 注册 hook 回调

安全注意：插件 Agent 的安全敏感字段（permissionMode、hooks、mcpServers）被强制忽略——只有用户自己创建的本地 Agent 可以声明这些。防止恶意插件获得过高权限。

10.2 IDE Bridge——把 CC 嵌进编辑器

CC 通过两套协议和 VS Code / JetBrains 通信：

REPL Bridge（WebSocket）：

VS Code Extension ←→ WebSocket ←→ CC Session Ingress Server
  │                                                    │
  │  SDKMessage 帧:                                     │
  │  - user/assistant turns                             │
  │  - slash commands                                   │
  │  - control requests (initialize, interrupt, etc.)   │
  │                                                    │
  │  Permission 回调:                                    │
  │  sendRequest("allow this tool?") ──────────────────→│
  │  ←────────────────────────── onResponse(allow/deny) │

Remote Bridge（HTTP 轮询）：

CLI: claude remote-control
  │
  ├─ POST /v1/environments/bridge     ← 注册为 Bridge 环境
  ├─ GET  /v1/environments/{id}/work/poll   ← 轮询任务
  │    └─ 返回 WorkSecret: { ingressToken, apiBaseUrl, auths, env }
  │
  ├─ spawn 子进程 session              ← 用 WorkSecret 启动 CC 会话
  └─ POST heartbeat                    ← 续租

Bridge 支持三种 spawn 模式：单会话、worktree 隔离、同目录复用。

10.3 Skills vs Plugins——区别

	Skill	Plugin
格式	Markdown + YAML frontmatter	`.claude-plugin/` 目录
能力	prompt 模板 + 参考文件	commands + agents + hooks
分发	项目目录 `.claude/skills/`	插件市场
版本	无	plugin.json 版本管理
用户配置	无	`userConfig` schema
权限	和主 Agent 一致	Agent 权限受限（不能声明 permissionMode）

Skill 是 prompt，Plugin 是程序。s05 的 SkillLoader 对应真实 CC 的 Skill 系统（只是更简单）。插件是全新的——s_full 完全没有对应物。

10.4 和 s_full 的对比

维度	s_full	真实 CC
扩展斜杠命令	改 REPL 代码	commands/*.md + plugin.json
自定义 Agent	改 Python	agents/*.md + 工具白名单
生态分发	无	marketplace + 版本管理 + 依赖解析
IDE 集成	无	WebSocket REPL + HTTP Remote Bridge
权限边界	无	插件 Agent 不能声明 permissionMode

核心洞察

插件系统和 IDE Bridge 代表了 Agent 从"工具"走向"平台"的最后一步。s_full 是一个你 fork 然后改源码的 Python 脚本。真实 CC 是一个你不需要 fork 的生态——通过插件扩展能力、通过 MCP 接入外部工具、通过 Bridge 嵌入编辑器。

这也解释了 512K 行代码从哪来：不是核心 Agent loop 变复杂了（它还是那个 while-tool_use），而是在这层循环周围长出了一个完整的平台——权限策略引擎、记忆持久化、hook 可编程接口、MCP 工具发现、7 种任务管理、插件市场、IDE 双向通信。骨架不膨胀，生态在骨架上生长。

十一、总结——从 s01 到 512K 行，我们学到了什么

12 个 session + s_full + 五大真实系统。最终的图景：

s01 — "一个循环+一个Bash"
  │
s02 — 工具分发（dispatch map）
  │
s03 — 内存规划（TodoWrite + nag）
s04 — 上下文隔离（Subagent）
s05 — 按需知识（Skills）
s06 — 策略遗忘（Compact）
  │
s07 — 磁盘任务图（DAG）    ← 第一个枢纽：状态在对话之外
s08 — 线程异步（Background）
  │
s09 — 多 Agent 邮箱（MessageBus）
s10 — 请求-响应 FSM（Protocols）
s11 — 自组织（Autonomous）   ← 第二个枢纽：Agent 自己找活干
s12 — 目录隔离（Worktree）
  │
s_full — 全机制集成（740行，骨架成型）
  │
真实 CC:
  权限引擎（allow/deny/ask + 6种模式 + AI 分类器）
  记忆系统（四种类型 + 自动提取 + Sonnet 侧查询）
  Hook 系统（28 事件 + 4 执行器 + updatedInput）
  MCP 集成（8 种传输 + 工具动态发现）
  任务系统（7 种类型 + 统一框架）
  插件生态 + IDE Bridge
  ─────────────────────────
  512,664 行 TypeScript

三条主线贯穿始终：

模型看管判断，harness 看管执行和约束 — 从 "dangerous" in command 到完整的权限引擎，这个原则的粒度在变化，但方向没变。
加能力不改循环 — dispatch map 加一行、TOOLS 加一个 schema、hook 加一条配置。核心 while stop_reason == 'tool_use' 从 s01 到真实 CC 骨架不变。
状态在对话之外 — s03 内存 → s07 磁盘 → memory system 持久化 → task system 多类型。每一步都在把信息从模型上下文中拉出来，放到更持久的地方。

十二、社区热议——泄露源码中最令人惊喜的设计

Claude Code 源码在 2026 年 3 月 31 日因 npm 打包事故泄露后，社区花了数周逐行拆解这 1906 个文件、51.2 万行代码。以下是普遍认为写得最好、最出人意料、最值得学习的地方。

12.1 Prompt Cache 的三段式设计——静态/动态分离

这是被引用最多的设计亮点。CC 没有简单地把整个 system prompt 当成一个缓存块，而是精心设计了静态段和动态段的边界：

┌─────────────────────────────────────┐
│  静态段 (高缓存命中率)               │
│  模型身份 + 安全规则 + 代码风格限制    │  ← 每次对话都相同
├─────────────────────────────────────┤
│  SYSTEM_PROMPT_DYNAMIC_BOUNDARY      │  ← 硬编码分隔标记
├─────────────────────────────────────┤
│  动态段 (低缓存命中率)               │
│  工作目录 + Git 状态 + MCP 配置        │  ← 每次对话可能不同
└─────────────────────────────────────┘

Anthropic 的 prompt cache 按前缀匹配。如果动态内容放在静态内容前面，每次对话变化都会导致整个缓存失效。CC 把永不变化的内容放在最前面（身份定义、安全规则），确保它们在 prompt cache 中始终命中。动态内容（当前目录、git 分支、MCP 服务器列表）放在后面。

还有两个细节：

工具描述按字母表排序 — 确保每次 tools 数组的 JSON 序列化结果一致，避免缓存因 key 顺序变化而失效
Agent 列表外置到消息附件 — 减少 ~10.2% 的 cache creation tokens。这是一个微优化，但在大规模使用时累积效果显著

12.2 自愈式记忆系统——"不信任内存，不断回到代码库验证"

社区的共识：这不是简单的"记住用户说过什么"，而是一套仿生学设计。

AutoDream——模型睡觉时整理记忆：

触发条件:
  • 时间门: 距上次 >24h
  • 会话门: 累计 5 次会话
  • 文件锁: 防止多进程冲突

四阶段:
  收集 → 提取 → 去重合并 → 写入结构化文件

"做梦"这个名字不是玩笑——它在概念上和人类睡眠中的记忆巩固过程一致：白天的经历（对话），夜间整理（压缩、去重、结构化），醒来后能更快检索。

9 段式 Compact 摘要结构：

会话目标 → 已完成任务 → 未完成任务 → 关键决策 →
代码变更 → 发现问题 → 待验证假设 → 用户偏好 → 上下文关键信息

不是把对话丢给模型让它"总结一下"，而是强制模型按 9 个维度结构化输出。这保证了压缩后的摘要可检索——"关键决策"栏位可以快速判断压缩内容是否和当前问题相关。

"不信任内存"哲学：

记忆文件里明确写着："如果记忆中的信息和当前代码冲突，相信代码。"这个原则贯穿整个系统——记忆是提示，不是权威。模型应该每次回到代码库验证，而不是依赖记忆中的快照。

12.3 ToolSearch——工具的按需加载

40+ 个工具全塞进 prompt，每次 API 调用都带着——大部分当前任务用不到。CC 的解法：

核心工具 (always loaded):  bash, read, write, edit, TodoWrite, task
非核心工具 (defer_loading):  NotebookEdit, WebSearch, SkillTool, CronCreate...
                              ↑
                              标记 defer_loading: true
                              模型需要时通过 ToolSearch 关键词动态加载

这相当于 Web 开发里的 Code Splitting。模型在对话中第一次需要某个工具时，ToolSearch 才注入该工具的完整 schema。不是所有 40 个工具的 JSON 都一直占着上下文窗口。

12.4 六级安全架构——层层剥洋葱

社区从源码中还原的安全层级：

Layer 1: 静态危险命令拦截    → "rm -rf /" 等硬编码模式
Layer 2: 用户自定义规则       → settings.json 的 allow/deny/ask
Layer 3: 工具自身安全检查     → BashTool.checkPermissions() 的 1350 行逻辑
Layer 4: Sidecar AI 分类器    → 小模型静默判断（auto 模式）
Layer 5: 交互式 UI            → 弹出对话框让人决定
Layer 6: 独立沙箱执行         → 命令在隔离环境中跑

社区最赞赏的设计是 Layer 4：用一个小 LLM 去判断另一个 LLM 的操作是否安全。 它比静态规则灵活（理解上下文），比人工审批快（毫秒级），而且有 Denial Tracking——如果小模型拒绝了太多次，系统自动降级到 Layer 5 让人类介入，防止误判卡住 Agent。

12.5 Coordinator + Fork Subagent——上下文污染的根治方案

s04 的 subagent 模式在真实 CC 中被放大为 Coordinator 架构：

Coordinator (规划层)
  ├── 只能用 3 个工具：SpawnAgent / SendMessage / TaskStop
  ├── 不直接操作文件 ← 关键约束
  │
  ├─→ Worker A (方案A探索) ──→ 结论回传 (XML task-notification)
  ├─→ Worker B (方案B探索) ──→ 结论回传
  └─→ Worker C (并行任务)  ──→ 结论回传

这里的精妙之处是 Fork 继承缓存。创建 Worker 时，它 fork 父 Agent 的 prompt cache 前缀——不需要重新发送 system prompt。创建一个子 Agent 的成本等同于发送一条 user message。这解释了为什么 CC 可以自由派发子 Agent 而不担心 token 成本爆炸。

Worker 之间也互相隔离——Worker A 探索方案 A 时读了 20 个文件，这些文件内容不会污染 Worker B 的上下文。Coordinator 只收到每个 Worker 的结论，不是完整探索日志。

12.6 泄露出的隐藏功能——最令人惊讶的部分

源码中还暴露了一些未发布或内部使用的功能：

代号	功能	状态
BUDDY	电子宠物系统（18 物种、5 稀有度、1% 闪光概率）	愚人节彩蛋
KAIROS	7×24 常驻后台助手，支持 cron/webhook/远程控制	未发布
ULTRAPLAN	30 分钟深度规划模式（Opus 驱动）	未发布
Undercover Mode	给开源仓库提 PR 时隐藏 Anthropic/AI 身份	内部使用
Capybara	新模型族代号（疑似 Claude 4.6），百万上下文	内部代号
Fennec	Opus 线模型代号	内部代号

BUDDY（电子宠物）是最令人意外的一个——CC 终端里有一个完整的 Tamagotchi 式宠物系统，包含 18 种物种、5 个稀有度等级、1% 概率出现"闪光"变体。代码里有完整的"喂食"、"玩耍"、"进化"机制。社区普遍认为这是 Anthropic 工程师的"hackathon 项目溜进了生产版本"。

KAIROS 则代表了一个远更大的野心——不只让你在终端里调一个 Agent，而是有一个常驻的 7×24 助手，能定时执行任务、响应 webhook、远程控制。

12.7 社区争议——"vibe-coded garbage" vs "真实的复杂"

源码被曝光后，Hacker News 上出现两极反应。

批评阵营：

print.ts 单函数超 3000 行，12 层嵌套
大量 feature flag + 补丁式代码
有工程师自嘲注释："memoization here increases complexity by a lot, and I'm not sure it really improves performance"

辩护阵营：

"看起来很乱，恰恰因为它进入了真实的高强度开发环境，而不再是实验室 demo"
这 51.2 万行代码处理的是真实世界的混乱——多终端兼容、shell 差异、文件系统权限、OAuth 流程、MCP 协议变体、跨平台 CI/CD
一个开源社区成员一夜之间用 AI 工具从零重写了架构（claw-code），2 小时内获得了 5 万+ Star——这说明架构好理解，只是实现细节多

最出圈的讽刺来自一位匿名评论者：

"一家做 LLM 的公司居然用 regex 做情绪分析？就像卡车公司用马来运输零件。"

回应："因为 regex 更快、更便宜，而且不会阻塞主流程。" 这个对话完美概括了真实工程和学术理想的分野——最好的工具是刚好够用的工具。

12.8 这场"被迫开源"教会我们什么

CC 泄露事件的长期影响比源码本身更值得思考：

护城河不在代码，在模型和数据 — Anthropic 在泄露后没有慌张，因为模型权重、训练数据和用户数据都没泄露。源码只是 harness——重要的，但不是不可替代的。
"Open by accident" vs "Open by design" — 同期 OpenAI 主动开源了 Codex CLI，而 Anthropic 是"被迫"暴露。两种策略折射出对竞争壁垒的不同理解。源码公开反而产生了社区认同——开发者 cleaner 用一晚上从零重写了同样的架构。
架构的价值在于清晰 — 51.2 万行源码不是好东西因为它们"复杂"，是因为它们在复杂之上保持了可读的架构。18 个 SECTION 标签、清晰的模块边界、一致的设计模式（dispatch map + JSON Schema）——这些我们在 s01-s12 里学到的东西，在真实 CC 里原样存在。

核心洞察

这场泄露最出人意料的地方：Anthropic 用了最尴尬的方式，向全世界展示了他们真正在想什么。而社区普遍同意——想法比代码更值钱。架构设计（prompt cache 三段式、Coordinator fork、六级安全、AutoDream 记忆）才是 CC 真正的竞争优势，而它们恰好是 leak 中最容易被复制的部分。

这也是学习 harness engineering 的终极价值——你不需要 512K 行代码就能理解 CC。12 个 session、740 行 s_full，已经覆盖了它最核心的架构骨架。剩下的 511K 行是把这个骨架投入真实世界的摩擦代价——多平台兼容、错误恢复、边界处理、UI 细节、企业合规。这些东西重要，但不是 harness 设计的本质。

MCP和A2A--Agent的横向与纵向沟通

Fri, 03 Apr 2026 00:00:00 GMT

MCP与A2A协议的横向与纵向沟通机制对比分析

Redis原理的学习

Fri, 03 Apr 2026 00:00:00 GMT

一、背景

Redis（Remote Dictionary Server）是一个开源的、基于内存的键值存储系统，属于 NoSQL 数据库阵营。它诞生的初衷是解决高并发场景下的性能瓶颈——传统关系型数据库将数据存储在磁盘上，每次读写都涉及磁盘 I/O，而 Redis 将数据直接放在内存中，单机 QPS 可达 10 万级别。

Redis 的核心定位是缓存，但它远不止于此。它支持丰富的数据结构（字符串、列表、集合、有序集合、哈希等），提供持久化（RDB 快照 + AOF 日志）、主从复制、哨兵高可用、集群分片等企业级特性。在现代架构中，Redis 常用于缓存加速、分布式锁、消息队列、排行榜、实时计数器等场景。在 LLM 应用中，它也被广泛用作向量存储、会话缓存和 Prompt 模板的管理层。

Redis 之所以高效，除了内存存储外，还在于它对底层数据结构做了精心设计——本章将从这些基础组件开始，逐一拆解它"快"的秘密。

此次拆解的源码是 Redis 8.6.3 版本。

二、组件

1. 动态字符串 SDS

和 C 字符串的区别

C 语言原生的字符串是以 \0 结尾的 char*，但这种方式存在几个缺陷：

获取长度要 O(n)：必须遍历整个字符串才能知道长度。
容易缓冲区溢出：拼接字符串时，如果忘记分配足够内存，就会越界写入。
内存分配频繁：每次修改字符串都要重新分配内存。
二进制不安全：遇到 \0 就认为字符串结束，无法存储图片、序列化对象等二进制数据。

SDS（Simple Dynamic String）就是为解决这些问题而设计的。它本质上是在 C 字符串的基础上包了一层头部信息，用一个 sds 类型（即 char*，指向 buf 起始位置）对外暴露，对外依然兼容 C 字符串的用法。

SDS 结构体源码（带注解）

// sds.h —— 注意 struct 使用了 __attribute__ ((__packed__)) 取消对齐填充

/* sdshdr5 实际从未使用，仅用于标记布局 */
struct __attribute__ ((__packed__)) sdshdr5 {
    unsigned char flags;  /* 低 3 位存类型，高 5 位存长度（最多 31 字节） */
    char buf[];           // 柔性数组，存放实际字符串内容
};

struct __attribute__ ((__packed__)) sdshdr8 {
    uint8_t len;          // 当前字符串长度（已用的字节数）
    uint8_t alloc;        // 已分配的总字节数（不含头、含'\0'）
    unsigned char flags;  // 低 3 位存类型标识，高 5 位未使用
    char buf[];           // 柔性数组，存放实际字符串内容
};

struct __attribute__ ((__packed__)) sdshdr16 {
    uint16_t len;         // 同上，但宽度为 16 位
    uint16_t alloc;
    unsigned char flags;
    char buf[];
};

// 类似地还有 sdshdr32（32 位）和 sdshdr64（64 位），分别对应不同长度的字符串

flags 的低 3 位表示类型：SDS_TYPE_5(0)、SDS_TYPE_8(1)、SDS_TYPE_16(2)、SDS_TYPE_32(3)、SDS_TYPE_64(4)。Redis 根据字符串长度自动选择最紧凑的头类型。对外暴露的 sds 指针指向 buf 的首地址，而不是结构体开头，因此通过 s[-1] 就能直接读出 flags 字节，进而知道该用哪种结构体去解析。

实例：构建 "name"

len = 4：当前字符串长度为 4
alloc = 4：总共分配了 4 字节可用空间
flags 的低 3 位 = SDS_TYPE_8
buf 末尾自动追加了 \0，兼容 C 库函数

实例：追加操作（"hi" → "hi,Amy"）

假设我们有一个 sds s = "hi"，现在要调用 sdscat(s, ",Amy") 追加 4 个字节。

// sds.c —— _sdsMakeRoomFor()，负责扩容的核心逻辑
sds _sdsMakeRoomFor(sds s, size_t addlen, int greedy) {
    size_t avail = sdsavail(s);      // 当前剩余空间
    size_t len = sdslen(s);          // 当前已用长度
    size_t newlen, reqlen;

    if (avail >= addlen) return s;   // 空间足够，直接返回

    reqlen = newlen = len + addlen;  // 至少需要的长度

    if (greedy == 1) {
        // 贪婪模式：多分配一些，避免下次再扩容
        if (newlen < SDS_MAX_PREALLOC)   // SDS_MAX_PREALLOC = 1MB
            newlen *= 2;                 // 小于 1MB 时直接翻倍
        else
            newlen += SDS_MAX_PREALLOC;  // 超过 1MB 后每次多给 1MB
    }
    // ... 然后根据 newlen 重新选择头类型，realloc 内存 ...
}

追加前 "hi" 的内存布局（假设 alloc = 2）：

追加 ",Amy" 时发现 avail = 0，而 newlen = 2 + 4 = 6。由于 6 < 1MB，触发贪婪分配：newlen = 6 * 2 = 12。于是实际分配的空间为 12 字节，alloc 变成 12。

追加后：

之后如果再追加少量字符（总长不超过 12），就不需要再次分配内存了——这正是内存预分配的意义。

SDS 的优势总结

O(1) 获取长度：直接读 len 字段，无需遍历。
杜绝缓冲区溢出：每次修改前都会检查 avail，不够就 sdsMakeRoomFor。
减少内存分配次数：预分配（小于 1MB 翻倍，大于 1MB+1MB）使得频繁追加时很少 realloc。
二进制安全：不再以 \0 作为字符串结束标志，而是以 len 为准，可以存储任意二进制数据。
惰性释放：缩短字符串时并不立即释放多余空间，而是保留在 alloc 中，方便后续再次增长。

2. IntSet

IntSet 是 Redis 为「只包含整数的小型 Set」设计的底层存储结构。它的本质是一个基于 C 语言整数数组实现的有序、唯一、可变长集合。

结构体定义

// intset.h
typedef struct intset {
    uint32_t encoding;   // 编码方式：INTSET_ENC_INT16 / INT32 / INT64
    uint32_t length;     // 当前元素个数
    int8_t contents[];   // 柔性数组，实际存储的元素（类型由 encoding 决定）
} intset;

encoding 取值：INTSET_ENC_INT16（2 字节）、INTSET_ENC_INT32（4 字节）、INTSET_ENC_INT64（8 字节）。
contents 虽然声明为 int8_t[]，但实际存储的类型由 encoding 决定。所有元素在数组中保持升序排列且不重复。
查找使用二分查找，时间复杂度 O(logN)。插入和删除时需要 memmove 挪动元素，复杂度 O(N)。

编码自动升级

假设当前 IntSet 中只有 {1, 2, 3} 三个小整数，encoding 为 INTSET_ENC_INT16（每个元素占 2 字节）。现在要插入 50000，这个数超过了 int16 的范围（-32768 ~ 32767），就需要触发编码升级。

升级流程的源码：

// intset.c —— intsetUpgradeAndAdd()
static intset *intsetUpgradeAndAdd(intset *is, int64_t value) {
    uint8_t curenc = intrev32ifbe(is->encoding);
    uint8_t newenc = _intsetValueEncoding(value);  // 确定新编码 → INTSET_ENC_INT32
    int length = intrev32ifbe(is->length);
    int prepend = value < 0 ? 1 : 0;  // 负数插在数组头部，非负数插在尾部

    // 1. 先更新 encoding，再 resize 数组（每个元素空间变大）
    is->encoding = intrev32ifbe(newenc);
    is = intsetResize(is, intrev32ifbe(is->length) + 1);

    // 2. 倒序遍历旧元素，逐个搬移到新位置（倒序避免覆盖）
    while(length--)
        _intsetSet(is, length + prepend,
                    _intsetGetEncoded(is, length, curenc));

    // 3. 将新元素插入头部或尾部
    if (prepend)
        _intsetSet(is, 0, value);
    else
        _intsetSet(is, intrev32ifbe(is->length), value);

    // 4. 更新 length
    is->length = intrev32ifbe(intrev32ifbe(is->length) + 1);
    return is;
}

以插入 50000（正数，prepend = 0）为例，图解如下：

插入前（INTSET_ENC_INT16）:

升级后（INTSET_ENC_INT32）:

关键细节：如果插入的是负数（如 -5），由于负数小于所有非负数，它会被放在头部（prepend = 1），原有元素整体右移一格。升级是不可逆的——升级后即使删除了导致升级的那个元素，编码也不会降回去，这也能接受，因为一旦存过大值说明这个集合以后也"大概率"还会再存。

IntSet 的特点

唯一且有序：二分查找保证去重和查找为 O(logN)。
编码升级机制：从 INT16→INT32→INT64 自动扩展，不浪费空间在小数据上。
不适合大量数据：插入/删除需要移动元素（O(N)），当集合较大时性能下降明显，Redis 会将其转为 HashTable 编码。

3. Dict

Dict（字典）是 Redis 最核心的数据结构之一，键值对的增删查改、哈希键的底层存储等，背后都是它。整个 Dict 由三个部分构成。

三部分结构

// dict.h
typedef struct dictEntry {
    void *key;                    // 键
    union {
        void *val;
        uint64_t u64;
        int64_t s64;
        double d;
    } v;                          // 值
    struct dictEntry *next;       // 链表解决哈希冲突
} dictEntry;

struct dict {
    dictType *type;               // 类型特定函数（哈希函数、比较、析构等）
    void *privdata;               // 私有数据
    dictEntry **ht_table[2];     // 两个哈希表，ht_table[0] 和 ht_table[1]
    unsigned long ht_used[2];    // 每个哈希表里已有的元素数
    long ht_size_exp[2];         // 每个哈希表的 size = 2^exp
    int16_t rehashidx;           // rehash 进度，-1 表示未在 rehash
    int16_t pauserehash;         // >0 时暂停 rehash
    unsigned bucket_size[2];     // 每个 bucket 的实际大小（内存优化）
};

dictEntry：键值对节点，用单向链表解决哈希冲突。
dictEntry 指针数组 **ht_table[2]：这是真正的「哈希表」，可理解为 dictEntry* bucket数组。
dict：字典主体，持有两个哈希表、两个 used 计数、rehash 游标等信息。

索引计算：hash & sizemask

Redis 的哈希表大小始终是 2 的幂（通过 size = 2^exp 控制）。这样做的好处是可以通过位运算代替取模来定位 bucket：

bucket_index = hash(key) & sizemask

其中 sizemask = size - 1。例如 size = 4，则 sizemask = 3（二进制 011），对任意哈希值取低两位即可找到 bucket 位置。

Redis 使用 dictGenHashFunction()（基于 SipHash，内部用 MurmurHash2），将 key 映射为一个 uint64_t。

双哈希表

Dict 维护了两个哈希表 ht_table[0] 和 ht_table[1]。正常情况下只使用 ht_table[0]，ht_table[1] 是空的。当需要进行扩容或收缩时，ht_table[1] 被创建出来，用于渐进式 rehash——一边把 ht_table[0] 中的元素迁移到 ht_table[1]，一边继续正常服务外部请求。

扩容与收缩的触发条件

扩容条件（dictExpandIfNeeded 中的逻辑）：

当负载因子 ≥ 1 且没有执行 BGSAVE / BGREWRITEAOF 等后台进程时，Redis 认为现在扩容是安全的，会触发扩容。
当负载因子 > 5（即 dict_force_resize_ratio = 5），即使有后台进程也会强制扩容，因为哈希冲突已经太严重，性能下降不可接受。

负载因子 = ht_used / size，即每个 bucket 平均存放的元素个数。

收缩条件：

当负载因子 < 0.1（即不到 10% 的 bucket 真正有数据），且当前 size 大于初始值 DICT_HT_INITIAL_SIZE（通常为 4），就会触发收缩。

扩容时 size 翻倍，收缩时 size 减半，始终保证 size 是 2 的幂。

Rehash 过程（渐进式）

无论扩容还是收缩，都需要创建新的哈希表，并将旧表中所有 key 重新计算 bucket 索引后插入新表——这个过程叫 rehash。

如果一次性完成，对于一个十几万 key 的字典会造成明显的卡顿。所以 Redis 使用渐进式 rehash（Incremental Rehashing），把迁移任务分摊到多次操作中：

在 dictExpand 中为 ht_table[1] 分配新数组，并设置 rehashidx = 0，表示 rehash 开始。
每次对字典执行增删查改操作时，除了完成本次操作，还会顺带把 ht_table[0] 中位于 rehashidx 的那条 bucket 链整条迁移到 ht_table[1]，然后 rehashidx++。
新增操作直接写入 ht_table[1]，保证 ht_table[0] 的元素只会减少不会增加。
当 rehashidx 等于 ht_table[0] 的 size 时，表示迁移完成。释放 ht_table[0]，将 ht_table[1] 提升为 ht_table[0]，重置 rehashidx = -1。
对于长时间没有请求的字典，每个事件循环也会在 databasesCron 中执行 1ms 的 dictRehash，每次处理 100 个 bucket，逐步消化。

4. ZipList

ZipList（压缩列表）是 Redis 为了极致节省内存而设计的一种特殊双向链表。它把所有元素压缩到一整块连续内存中，省去了传统链表每个节点所需的 prev / next 指针开销。

整体结构

 <zlbytes> <zltail> <zllen> <entry> <entry> ... <entry> <zlend>

字段	大小	说明
`zlbytes`	uint32_t	整个 ziplist 占用的总字节数（含自身 4 字节）
`zltail`	uint32_t	最后一个 entry 相对起始位置的偏移量，用于 O(1) 尾部操作
`zllen`	uint16_t	entry 数量，超过 65535 时设为 65535，需遍历获取真实数量
`entry`	可变	每个元素节点，详见下文
`zlend`	uint8_t	固定值 `255`(0xFF)，标识 ziplist 结束

依托 zltail，在尾部进行压入/弹出是 O(1)；依托每个 entry 的 previous_entry_length，反向遍历也是 O(1)。但中间插入仍然是 O(N)，因为需要移动后续所有元素。

Entry 结构

每个 entry 由三部分组成：

 <prevlen> <encoding> <entry-data>

prevlen（previous_entry_length）：前一个 entry 的长度。如果前一个 entry 长度 < 254 字节，prevlen 占 1 字节直接记录；如果长度 ≥ 254 字节，prevlen 占 5 字节（首字节固定为 0xFE，后 4 字节存实际长度）。这个字段是反向遍历的基础。
encoding：编码字段，同时描述了数据类型和长度。Redis 通过首字节的高 2 位来判断类型：
- 00、01、10 开头 → 字符串编码：后续位存储字符串长度，长度分三档（≤63 / ≤16383 / ≥16384 字节），编码占 1/2/5 字节，之后紧跟 entry-data 存实际字符串内容。
- 11 开头 → 整数编码：后 2 位区分具体整数类型（int16/int32/int64/24bit/8bit），编码占 3/5/9/4/2 字节，之后紧跟 entry-data 存整数值。
一个特殊情形是 |1111xxxx|（xxxx 在 0001~1101 之间）——4 位立即数编码。它直接把数值 0~12 压缩在 encoding 字节的低 4 位中，值本身就成了编码的一部分，自然不需要额外的 entry-data。同理，更大的整数类型（如 int16）的数值仍然需要单独的 entry-data 来存放，因为 encoding 字节里只描述了「这是什么类型的整数」，放不下实际数值。
entry-data：实际数据内容，在某些整数编码下可能不存在。

存储示例

存储 "ab" 和 "bc" 两个字符串（假设前一个 entry 长度均小于 254）：

存储数字 2 和 5（小整数编码，无需 entry-data）：

连锁更新问题

考虑这样一种情况：ziplist 中有多个长度恰好为 253 字节 的 entry，它们的 prevlen 都只占 1 字节。现在在头部插入一个 254 字节以上 的 entry，导致紧邻它的 entry1 的 prevlen 必须从 1 字节膨胀到 5 字节（多出 4 字节），而 entry1 膨胀后又可能让 entry2 的 prevlen 跟着膨胀……这种级联效应就是连锁更新。

连锁更新在最坏情况下需要连续多次内存 realloc，性能下降明显。但这在现实中极难触发——需要大量恰好在 253 字节临界点附近的连续 entry。因此 Redis 并没有在代码层面做特殊防护，只是意识到这个问题存在。

设计取舍：为什么 ZipList 坚持用 prevlen，直到 7.0 才被 Listpack 替代？

prevlen 不是设计缺陷，而是一个明知故留的权衡。prevlen 放在 entry 头部，反向遍历时只需读当前 entry 的第一个字节就能知道前一个 entry 的长度，代码路径极短。Listpack 的 backlen 则需要往回读 1~5 字节（解析 continuation bits），稍复杂一些。antirez 认为这个简洁性值得用连锁更新的理论风险来换——毕竟 Redis 的绝大多数 value 只有几十字节，连续多个"恰好卡在 253"的极端情况几乎不会发生。

那为什么 7.0 最终还是改了？不是因为连锁更新在生产环境爆炸了，而是双通道复制等新特性需要一个对内存块边界更友好的格式，趁着重构顺带清掉了这笔历史债。本质上是「用稍复杂一点的反向遍历，换零连锁更新的完全保证」，在长期维护中后者胜出。

5. QuickList

QuickList 是 Redis 3.2 之后 List 类型的底层实现，它在「内存紧凑」和「操作效率」之间找到了平衡。

基本结构

简单来说：QuickList 是一个双向链表，每个节点是一个 ZipList（新版使用 Listpack）。外层链表用于快速定位到某个节点，内层的 ziplist/listpack 以紧凑的内存存储实际数据。

关键配置项

list-max-listpack-size（旧称 list-max-ziplist-size）：控制每个内部节点最大占用字节数。默认 -2（8KB）。可设为正数（精确字节限制）或负数（不同优化级别，如 -1 = 4KB，-2 = 8KB，-3 = 16KB，-4 = 32KB，-5 = 64KB）。
list-compress-depth：控制 QuickList 的压缩深度。由于链表两端的节点访问频率最高，中间节点可以被 LZF 压缩以节省内存。设为 0 表示不压缩；设为 1 表示首尾各 1 个节点不压缩、中间全压缩；设为 2 表示首尾各 2 个不压缩，以此类推。

list-compress-depth = 1:
  [node0 不压缩] → [node1 压缩] → [node2 压缩] → ... → [nodeN 不压缩]
     头                                               尾

6. SkipList

SkipList（跳表）是 Redis 中 ZSet（有序集合）的底层实现之一（另一个是 Listpack，用于数据量较小时）。它的本质是一个在有序链表上加了多层索引的数据结构。

与普通链表的区别

元素按 score 升序排列，score 相同时按 ele（成员字符串）字典序排列。
每个节点可能包含多个层级指针（称为 level），每个 level 的跨度（span）不同，高层指针用来"跳过多余元素"以加速查找。
层数随机生成（最高 32 层），跳表的期望查询复杂度为 O(logN)。

结构体定义

// server.h
typedef struct zskiplistNode {
    double score;                      // 排序分值
    struct zskiplistNode *backward;    // 后退指针（仅 level 0 使用）
    struct zskiplistLevel {
        struct zskiplistNode *forward; // 本层的前进指针
        unsigned long span;            // 本层跨过的元素个数
    } level[];                         // 柔性数组，每个元素表示一个层级
} zskiplistNode;

typedef struct zskiplist {
    struct zskiplistNode *header, *tail;  // 头尾指针
    unsigned long length;                 // 节点总数
    int level;                            // 当前最高层数
} zskiplist;

typedef struct zset {
    dict *dict;          // 字典：key→score，用于 O(1) 按成员查分值
    zskiplist *zsl;      // 跳表：按 score 排序，用于范围查询
} zset;

ZSet 同时使用 dict 和 skiplist：dict 提供 O(1) 的成员分值查询，skiplist 提供 O(logN) 的范围查询和排序能力。两者存的是同一份数据（指针引用），内存不会翻倍。

查询流程示意

查找时从最高层开始，如果前进指针指向的节点的 score 小于目标值，就沿着该层前进；如果大于目标值，就下降一层继续查找。
span 记录了两个节点之间在 level 0 上跳过了多少个元素，用于计算排位（rank）。

与红黑树的对比

跳表和红黑树的增删查改复杂度都是 O(logN)，但跳表的实现更简单：不需要复杂的旋转和变色逻辑，没有红黑树的多种情况分支。此外，跳表天然支持范围查询（直接沿 level 0 遍历），而且可以方便地获取元素的排位（通过 span 累加）。这些特性恰好契合 ZSet 的需求。

7. Listpack

Listpack 是 ZipList 的继任者，Redis 7.0 起在所有场景中替代了 ZipList。它的定位完全一致——用一块连续内存紧凑存储多个元素，支持双向遍历、两端 O(1) 压入/弹出。区别在于它通过改变 entry 结构，从根本上消除了 ZipList 的连锁更新问题。

整体结构

 <total_bytes> <num_elements> <entry> <entry> ... <entry> <0xFF>

字段	大小	说明
`total_bytes`	uint32_t	listpack 占用的总字节数（含自身 4 字节）
`num_elements`	uint16_t	entry 数量，超过 65535 时取值为 65535，需遍历获取真实值
`entry`	可变	每个元素节点
`0xFF`	uint8_t	结束标记

和 ZipList 的关键差异是：Listpack 不再存 zltail，尾部定位改为从最后一条 entry 的 backlen 反向推算，少了一个 4 字节的全局字段。

Entry 结构 —— 化解连锁更新的核心

 <encoding> <data> <backlen>

encoding：编码字节。高 2 位区分类型：10 开头为短字符串（6 位长度，≤63 字节）；1110 开头为中字符串（12 位长度，≤4095 字节）；0 开头为小整数（7 位无符号，0~127）；110 开头为 13 位整数；随后还有 16/24/32/64 位整数编码。与 ZipList 的 encoding 逻辑类似，但编码号不同。
data：实际数据内容。对于小整数（7 位编码），值直接嵌在 encoding 中，此部分不存在。
backlen：当前 entry 的总长度（encoding + data + backlen 本身）。占 1~5 字节，通过每个字节的最高位（continuation bit）表示是否读下一字节。这是替代 ZipList prevlen 的关键设计。

为什么 Listpack 没有连锁更新

ZipList 的连锁更新根源在于 prevlen：entry1 膨胀导致 entry2 的 prevlen 也必须膨胀，级联扩散。Listpack 把视角翻了过来——每个 entry 记录的是自己的长度（backlen），而不是前一个 entry 的长度。

反向遍历时，从某个 entry 的起始位置往前回退一个 backlen 就是前一个 entry 的起点。一个 entry 的 backlen 只取决于自身的总大小，与前后 entry 无关，因此任何 entry 的修改都不会触发邻居的连锁连带更新。

从 entry3 反向遍历到 entry2：
  entry2_start = entry3_start - entry2_backlen

从 entry2 反向遍历到 entry1：
  entry1_start = entry2_start - entry1_backlen

与 ZipList 的对比

维度	ZipList	Listpack
连续内存	✓	✓
反向遍历	靠 `prevlen`（记录前一个 entry 长度）	靠 `backlen`（记录当前 entry 长度）
连锁更新	存在（prevlen 级联膨胀）	不存在
头部字段	zlbytes / zltail / zllen（10 字节）	total_bytes / num_elements（6 字节）
首次引入	远古版本	Redis 7.0，7.2 起全面替代

本文后续提到"小对象优化用 ZipList 做紧凑存储"的地方，在 Redis 7.0+ 中实际运行时都是 Listpack，但编码思想和应用场景完全一致。

小结：七种组件分工

组件	角色
SDS	动态字符串，承载所有文本/二进制值的存储
IntSet	小整数集合，有序、二分查找
Dict	哈希表，O(1) 增删查改，支持渐进式 rehash
ZipList / Listpack	紧凑连续内存块，小数据量下的省内存方案
QuickList	双向链表 + Listpack 节点，List 的默认实现
SkipList	多层有序跳表，O(logN) 范围查询和排名

这七种组件是 Redis 的全部"积木"。下一章会看到它们如何被组装成对外的五种数据结构。

三、RedisObject —— 类型系统的桥接层

第二章讲的是七种存储实现，第四章要讲五种对外数据类型。那么问题来了：Redis 怎么知道一个 String 该用 INT、EMBSTR 还是 RAW？一个 Set 什么时候用 IntSet、什么时候用 Dict？

答案就是 RedisObject。它不是存储实现，而是类型分发器——用两个 4 位的字段 type 和 encoding，把「数据类型」映射到「底层实现」。

结构体定义

// object.h
struct redisObject {
    unsigned type:4;                    // 4 位：数据类型（OBJ_STRING/OBJ_LIST/...）
    unsigned encoding:4;               // 4 位：底层编码方式（七种组件选其一）
    unsigned refcount : OBJ_REFCOUNT_BITS;  // 引用计数（23 位）
    unsigned iskvobj : 1;              // 是否为 kvobj（键值一体对象）
    unsigned metabits : 8;             // 附加元数据位图（仅在 iskvobj=1 时有效）
    unsigned lru : LRU_BITS;           // 24 位：LRU 时钟或 LFU 计数器
    void *ptr;                         // 8 字节：指向实际数据的指针
};

总计 16 字节。type 决定「是什么」，encoding 决定「怎么存」，ptr 指向真正的存储实现。

编码方式一览

Redis 的编码常量定义在 object.h 中：

编号	常量	对应组件	目前状态
0	`OBJ_ENCODING_RAW`	SDS	使用中
1	`OBJ_ENCODING_INT`	无（ptr 直接存值）	使用中
2	`OBJ_ENCODING_HT`	Dict	使用中
3	`OBJ_ENCODING_ZIPMAP`	—	已废弃
4	`OBJ_ENCODING_LINKEDLIST`	—	已废弃
5	`OBJ_ENCODING_ZIPLIST`	ZipList	已废弃
6	`OBJ_ENCODING_INTSET`	IntSet	使用中
7	`OBJ_ENCODING_SKIPLIST`	Dict + SkipList	使用中
8	`OBJ_ENCODING_EMBSTR`	SDS（嵌入式）	使用中
9	`OBJ_ENCODING_QUICKLIST`	QuickList	使用中
10	`OBJ_ENCODING_STREAM`	Radix Tree + Listpack	使用中
11	`OBJ_ENCODING_LISTPACK`	Listpack	使用中
12	`OBJ_ENCODING_LISTPACK_EX`	Listpack（扩展）	使用中

lru 字段 —— 内存淘汰的近似 LRU

redisObject 中的 lru（24 位）字段看起来和类型分发无关，它的职责是内存淘汰——当 Redis 使用内存超过 maxmemory 上限时，决定哪些 key 优先被清理。

和常见八股题（HashMap + 双向链表实现精确 LRU）不同，Redis 用的是近似 LRU。如果给几百万个 key 维护一个全局双向链表，每次访问都要加锁移动节点，内存和 CPU 开销根本扛不住。

实现代码在 evict.c 中，思路很简单：

1. 记录时间戳而非链表指针。 lru 存的是一个 24 位的秒级时钟值（mstime() / 1000，约 194 天转一圈）。每次访问一个 key 时，lookupKey() 顺手把 lru 更新为当前时钟——只是一个赋值，O(1)。

2. 淘汰时采样，不全局排序。 需要释放内存时，随机取 N 个 key（maxmemory-samples，默认 5），计算它们的空闲时间（当前时钟 - key.lru），把最久没访问的那些塞进一个大小为 16 的候选池（evictionPool），从中挑最老的那个淘汰。没释放够就继续采样、继续淘汰。

换句话说，它淘汰的不是「全 Redis 最久未访问的 key」，而是「几次随机采样中看起来最旧的 key」。牺牲一点精确度，换来零额外内存和无需全局锁。

淘汰策略由 maxmemory-policy 配置，共 10 种：noeviction（不淘汰，写操作直接报错）、volatile-lru / allkeys-lru（近似 LRU，按范围看是否只看有过期时间的 key）、volatile-lfu / allkeys-lfu（近似 LFU，lru 字段改为存访问频率计数器）、volatile-ttl（最接近过期的先淘汰）、volatile-random / allkeys-random（随机淘汰）、以及 volatile-lrm / allkeys-lrm（LRU 采样后二次筛选的变体）。

LFU 模式下 lru 字段的语义变了：高 16 位存上次衰减时间，低 8 位存对数计数器的访问频率。核心仍然是「用一个 int 字段替代全局链表」。

分发逻辑

  高层数据类型（type 字段）           底层实现（encoding 字段）
 ─────────────────────────         ───────────────────────────
  String  ────┬──────────────→  INT / EMBSTR / RAW
  List    ────┼──────────────→  QUICKLIST
  Set     ────┼──────────────→  INTSET ──→ HT
  ZSet    ────┼──────────────→  LISTPACK ──→ SKIPLIST
  Hash    ────┼──────────────→  LISTPACK ──→ HT
  Stream  ────┘──────────────→  STREAM

  判断逻辑由 RedisObject 的 encoding 字段驱动，
  每种数据结构的 *.c 文件中各自维护了切换阈值。

四、五种数据结构

前两章分别拆解了存储组件和类型系统，这一章看最上层——五种对用户暴露的数据结构。它们不是独立的数据结构，而是底层组件经过 RedisObject 的 encoding 分发后，呈现给用户的"最终形态"。理解每种数据结构在什么条件下选用哪种底层编码，是读懂 Redis 性能模型的关键。

1. String

String 是 Redis 中最基础的数据类型，一个键对应一个字符串值，值可以是普通文本、整数、二进制数据，最大 512MB。

三种内部编码

String 并非总是用 SDS 来存储。根据值的内容和长度，Redis 会选择三种编码之一：

编码	常量	触发条件	内部存储方式
INT	`OBJ_ENCODING_INT` (1)	值可以解析为整数，且范围在 `LONG_MIN` ~ `LONG_MAX` 内	指针直接存数值，不额外分配内存
EMBSTR	`OBJ_ENCODING_EMBSTR` (8)	字符串长度 ≤ 44 字节	RedisObject 和 SDS 在同一块连续内存中，一次分配
RAW	`OBJ_ENCODING_RAW` (0)	字符串长度 > 44 字节	RedisObject 和 SDS 分别两次分配内存

编码选择流程（对应源码）

// object.c —— createStringObject()
#define OBJ_ENCODING_EMBSTR_SIZE_LIMIT 44

robj *createStringObject(const char *ptr, size_t len) {
    if (len <= 44)  return createEmbeddedStringObject(ptr, len);  // → EMBSTR
    else             return createRawStringObject(ptr, len);       // → RAW
}

// object.c —— createStringObjectFromLongLongWithOptions()
robj *createStringObjectFromLongLongWithOptions(long long value, ...) {
    // 小整数（0~9999）优先使用共享对象，避免重复分配
    if (value >= 0 && value < 10000)
        return shared.integers[value];

    // 范围内整数直接存 ptr 中
    o->encoding = OBJ_ENCODING_INT;
    o->ptr = (void*)((long)value);   // ptr 不指向内存，直接存数值
}

EMBSTR 的 44 字节限制是精心计算的：redisObject 占 16 字节，sdshdr8 头占 3 字节，加上 44 字节数据和一个 \0 共 64 字节，正好对齐 jemalloc 的 64 字节 arena，一次 malloc 即可，分配和释放效率极高。

编码的内存布局对比

编码转换

INT → RAW：对 INT 编码的对象执行 append 等字符串操作时，会自动转为 RAW。因为 INT 编码下 ptr 存的是数字而非 SDS 指针，无法进行字符串拼接。
EMBSTR → RAW：EMBSTR 分配的内存是只读连续的，任何修改操作（如 append）都会触发重新分配，转为 RAW 编码。这是 EMBSTR 的唯一代价——它只适用于不变的短字符串。
INT 优化：当对 String 执行 incr、decr 等数值操作时，Redis 会尝试将 RAW/EMBSTR 转为 INT。tryObjectEncoding() 函数负责这一优化。

2. List

List 是一个有序的字符串列表，支持从两端压入/弹出，典型的使用场景是消息队列、最新动态列表等。

编码演进

Redis 3.2 是一个分水岭：

版本	编码方式
3.2 之前	小数据用 `ZipList`（连续内存块），大数据用 `LinkedList`（真正的双向链表）
3.2 及之后	统一切换为 `QuickList`（双向链表 + 每个节点的 Listpack/ZipList）

旧方案中 ZipList 省内存但中间插入慢，LinkedList 插入快但每个节点都有 prev/next 指针开销，内存碎片严重。QuickList 折中了二者——外层链表控制粒度，内层 listpack 保持内存紧凑。目前 List 只使用 QuickList 这一种编码，不再需要在小数据量和大数据量之间切换。

QuickList 的配置回顾

list-max-listpack-size -2   # 每个内部节点最大 8KB（负数按 4K/8K/16K/32K/64K 分级）
list-compress-depth 0       # 中间节点 LZF 压缩深度，0=不压缩

这两个参数在第二章第 5 节已有详细说明，这里不再展开。

典型操作

LPUSH mylist "world"    →  ["world"]
LPUSH mylist "hello"    →  ["hello", "world"]
RPUSH mylist "!"        →  ["hello", "world", "!"]
LRANGE mylist 0 -1      →  ["hello", "world", "!"]
LPOP mylist             →  "hello"

底层对 QuickList 头尾节点的 push/pop 都是 O(1)，而 LRANGE 等范围查询需要遍历节点内的 listpack 元素。

3. Set

Set 是一个无序、唯一的字符串集合，支持交集、并集、差集等集合运算，常用于标签系统、共同好友、随机抽奖等场景。

编码方式

Set 有两种底层编码，会根据数据特征自动选择：

1. INTSET（OBJ_ENCODING_INTSET）

当集合同时满足两个条件时使用：

所有元素都是整数（或能解析为整数）
元素数量 ≤ set-max-intset-entries（默认 512）

此时 Set 就是一个 IntSet（见第二章第 2 节），元素有序存储、二分查找去重，非常省内存。

2. HT（OBJ_ENCODING_HT）

一旦不满足上述条件（比如加入了非整数元素，或数量超阈值），Set 会转为 HashTable 编码。这里直接复用了 Dict 结构，具体做法是：

Dict 的 key 存集合元素
Dict 的 value 统一设为 NULL

也就是说，Set 本质上是一个「只有键没有值」的哈希表。这样做的好处是代码复用度极高——增删查改直接走 Dict 的 dictAdd/dictDelete/dictFind，不需要专门为 Set 写一套哈希表。

编码转换触发

// t_set.c —— intset 元素数量超限时转换
static void maybeConvertIntset(robj *subject) {
    if (intsetLen(subject->ptr) > intsetMaxEntries())   // 默认 > 512
        setTypeConvert(subject, OBJ_ENCODING_HT);        // 转为哈希表
}

// t_set.c —— 新元素不是整数时直接转 HT
if (!isSdsRepresentableAsLongLong(value, NULL)) {
    setTypeConvertAndExpand(set, OBJ_ENCODING_HT, ...);
}

注意：INTSET → HT 是单向的，转过去后即使把所有非整数元素删掉，也不会降级回 INTSET。这是因为「曾有过非整数，以后大概率还会有」。

内存布局示意

4. ZSet

ZSet（Sorted Set，有序集合）在 Set 的基础上为每个元素绑定了一个 score（分值），元素按 score 升序排列，score 相同时按元素字符串字典序排列。典型应用是排行榜、延迟队列、带权重的标签。

双结构混合编码（SKIPLIST）

当数据量较大时，ZSet 使用 两种结构配合：

typedef struct zset {
    dict *dict;          // 字典：element → score，O(1) 按元素查分值
    zskiplist *zsl;      // 跳表：按 score 排序，O(logN) 范围查询 + 排名
} zset;

操作	用哪个结构	复杂度
查某个元素的 score	dict	O(1)
按 score 范围查元素（ZRANGEBYSCORE）	skiplist	O(logN + M)
查某个元素的排名（ZRANK）	skiplist（累加 span）	O(logN)
添加/更新元素	dict + skiplist 同步操作	O(logN)

为什么不用单一结构？ 仅用 dict 拿不到排序和排名，仅用 skiplist 按元素查分值要从最高层一路找（O(logN)），不如 O(1) 的 dict 快。两者存同一份数据的指针引用，不会造成内存翻倍——dict 的 key 和 skiplist 的 ele 指向同一个 SDS 对象。

小对象优化：LISTPACK 编码

当数据量较小时，跳表的层指针和 dict 的 bucket 数组的开销就显得不划算。此时 Redis 切换为紧凑的 LISTPACK（旧版叫 ZipList）编码：

触发条件（两个都满足才使用 LISTPACK）：
  1. 元素数量 ≤ zset-max-listpack-entries（默认 128）
  2. 每个元素的字符串长度 ≤ zset-max-listpack-value（默认 64 字节）

Listpack 本身没有排序和键值对概念，Redis 通过编码约定来解决：

Listpack 中 ZSet 元素的排列方式：
  [ele1, score1, ele2, score2, ele3, score3, ...]

即相邻两个 entry 构成一对 (element, score)，按 score 从小到大排列。

当插入新元素时，Redis 会遍历 listpack 找到正确的插入位置（保持 score 有序），然后用 memmove 挪出空间。这也是为什么 listpack/zset 只在数据量小时使用——数据量大后 memmove 的开销不可接受。

有序是谁的责任？ 一个容易混淆的点：SkipList 的有序是数据结构自带的——节点按 score 链式排列，插入时走高层指针定位，O(logN)。Listpack 本身只是一个紧凑数组，没有排序能力——它的有序是 t_zset.c 的插入代码「逐对遍历、比大小、找位置、memmove」强行维系的。两者都服务于 ZSet 的排序需求，只是实现路径不同：前者靠结构，后者靠操作。

编码切换

LISTPACK → SKIPLIST：
  当插入后元素数量 > 128 或新 ele 长度 > 64 字节时触发升级

SKIPLIST → LISTPACK：
  当删除后剩余元素 ≤ 128 且最大 ele ≤ 64 字节时，会降级回 LISTPACK
  （与 Set 的 INTSET 不同，这里是双向的，通过 zsetConvertToListpackIfNeeded 实现）

结构示意图

5. Hash

Hash 是一个字段-值的映射（field → value），适合存储对象（如用户信息、商品属性）。它与 ZSet 极其相似，本质上是「去掉了排序需求的 ZSet」。

与 ZSet 的相似与区别

维度	ZSet	Hash
元素结构	`(element, score)`	`(field, value)`
排序	按 score 排序	无序
查单个	O(1) 或 O(logN)	O(1)
大对象编码	`SKIPLIST`（dict + skiplist）	`HT`（仅 dict）
小对象编码	`LISTPACK`	`LISTPACK`
小对象内部排列	`[ele, score, ele, score, ...]`	`[field, value, field, value, ...]`

关键差异一句话：Hash 不需要排序，所以把 ZSet 大对象编码中的 skiplist 去掉，只保留 dict，就是 Hash 的大对象编码。

编码方式

1. LISTPACK（小数据）

触发条件（两个都满足）：

元素数量 ≤ hash-max-listpack-entries（默认 512）
每个 field 和 value 的长度 ≤ hash-max-listpack-value（默认 64 字节）

Listpack 中相邻两个 entry 为一对 [field, value]：

Listpack 中 Hash 元素的排列：
  [field1, value1, field2, value2, field3, value3, ...]

查找时遍历 listpack，逐个匹配 field，找到后返回紧随其后的 value。因为没有排序需求，插入时直接追加到末尾（或覆盖已有 field 的 value），不需要像 ZSet 那样查找排序位置。

2. HT（大数据）

一旦超出小对象阈值，Hash 转为纯粹的 Dict 编码（OBJ_ENCODING_HT）。Dict 的 key 存 field，value 存实际值。这是 Hash 最通用的形态——O(1) 查找、O(1) 平均插入。

编码转换

Hash 的编码切换逻辑与 ZSet 基本一致，摘出核心代码（t_hash.c）：

// t_hash.c —— hashTypeSet()
if (sdslen(field) > server.hash_max_listpack_value ||
    sdslen(value) > server.hash_max_listpack_value)
    hashTypeConvert(db, o, OBJ_ENCODING_HT);       // 单条数据过大 → 转 HT

if (hashTypeLength(o, 0) > server.hash_max_listpack_entries)
    hashTypeConvert(db, o, OBJ_ENCODING_HT);       // 元素总数超限 → 转 HT

与 ZSet 不同的是，Hash 从 HT 回退到 LISTPACK 需要显式触发（如 HSCAN 扫描检测），不会像 ZSet 那样在每次删除时主动检查降级。

五种数据结构总结

String  ── INT / EMBSTR / RAW
List    ── QUICKLIST
Set     ── INTSET ──────────→ HT (dict, value=NULL)
ZSet    ── LISTPACK ────────→ SKIPLIST (dict + skiplist)
Hash    ── LISTPACK ────────→ HT (dict, field→value)

         ← 小数据，内存紧凑 →  ← 大数据，查询高效 →

这五种数据结构的设计思想一以贯之：「小对象用连续内存（INT/EMBSTR/LISTPACK/INTSET），大对象用索引结构（RAW/HT/SKIPLIST）」。Redis 用极少的代码量实现了一套自适应的存储引擎，这也是它能在各种场景下同时兼顾内存和性能的原因。

一个容易混淆的词：「有序」

Redis 的 List 和 ZSet 都被描述为"有序"，但含义完全不同：

List 的「有序」= 按插入顺序。你从左边推就在左边，右边推就在右边，listpack 中 [ele1, ele2, ele3] 就是先后插入的次序。两端 push/pop 直接操作头尾，不需要比较内容。

ZSet 的「有序」= 按 score 数值排序。每个元素带一个 score（double 类型），元素之间比大小，按升序排列。插入时要找到正确的 score 位置塞进去。

前者是"先后有序"，后者是"大小有序"。解决的是两类完全不同的问题。

五、Redis网络模型

1. Linux五种阻塞模型

(1) 阻塞IO

用户进程调用 recvfrom 后，内核等待数据到达，数据到达后内核将数据从内核空间拷贝到用户空间，整个过程用户线程一直处于阻塞状态（让出 CPU，被内核挂起），两个阶段全部阻塞。

(2) 非阻塞IO

用户进程反复调用 recvfrom，如果没有数据，内核立即返回错误码（EAGAIN），不会挂起线程。反复轮询虽然让第一阶段不再阻塞，但如果写成忙等会严重浪费 CPU。数据到达后，第二阶段拷贝数据时线程依然是阻塞的。忙等空转就是它不如 IO 多路复用的根本原因。

(3) IO多路复用

FD（File Descriptor，文件描述符）是 Linux 中一切 I/O 操作的句柄——每个 socket 连接对应一个 fd。IO 多路复用的核心思想是：单个线程同时监听多个 fd，哪个先就绪就先处理哪个，避免对每个 fd 的无意义等待。 线程阻塞在 select/poll/epoll 上，一旦有 fd 可读或可写，内核就唤醒线程，线程再去对就绪的 fd 执行读写。

监听 fd 的方式经历了三代演进：

select：将用户态的 fd_set（bitmap，默认上限 1024）拷贝进内核，内核遍历全部 fd 检查就绪状态，再拷回用户态，用户再遍历一遍才能找到就绪的 fd。两次拷贝 + 两次 O(N) 遍历，连接数一多性能急剧下降。

poll 对 select 做了最直接的改进：用 struct pollfd 数组替代固定大小的 bitmap，破除了 1024 限制。但内核和用户态依然要做 O(N) 遍历。

epoll 在 Linux 2.6 引入，三个函数分工：

epoll_create：创建 epoll 实例，内核分配 eventpoll 对象
epoll_ctl(ADD/MOD/DEL)：将 fd 注册进内核的红黑树，O(logN)
epoll_wait：阻塞等待，直接从就绪链表上取就绪的 fd，O(1)，只返回有事件的 fd，无需遍历全量

epoll 的 LT 和 ET 模式：

LT（Level Triggered，水平触发，默认）：只要 fd 缓冲区还有数据，下次 epoll_wait 仍会通知，编程简单不易丢事件。
ET（Edge Triggered，边缘触发）：只在 fd 状态从"无数据"变"有数据"的瞬间通知一次，必须配合非阻塞 IO 一次性读完（循环 read 直到返回 EAGAIN），否则剩余数据可能永远丢失。优点是减少重复通知，高并发下性能更好。

基于 epoll 模式的 web 服务的基本流程：

socket() → bind() → listen()           // 创建监听 socket
epoll_create()                          // 创建 epoll 实例
epoll_ctl(ADD, listen_fd)               // 注册监听 fd
while (1) {
    n = epoll_wait();                   // 阻塞等待事件
    for (i = 0; i < n; i++) {
        if (fd == listen_fd) {
            conn_fd = accept();         // 新连接
            set_nonblocking(conn_fd);   // 设为非阻塞
            epoll_ctl(ADD, conn_fd);    // 注册新 fd
        } else {
            read(fd);                   // 非阻塞读
            process();
            write(fd);                  // 写回响应
        }
    }
}

(4) 信号驱动IO

预先注册 SIGIO 信号处理函数后立即返回，进程不阻塞。数据就绪时内核发送 SIGIO 信号，进程在信号处理函数中调用 recvfrom 完成拷贝（第二阶段仍阻塞）。编程复杂度高，多连接下信号排队和竞态难以处理，Redis 未采用。

(5) 异步IO

调用 aio_read 后立即返回，两个阶段均由内核完成——数据直接拷贝到用户指定的 buffer，完成后内核通知用户。全程不阻塞。但 Linux 原生 AIO 对 socket 支持有限（主要面向文件 IO），实际应用极少。

2. Redis网络模型

单线程还是多线程？

分两个层面回答：

核心命令处理：始终单线程。从 readQueryFromClient 读命令 → processCommand 解析执行 → addReply 写回复，整条链路在主线程的事件循环中串行完成。这意味着不存在两个命令同时修改同一个 key 的竞争问题，所有数据结构无需加锁。
整个 Redis 进程：6.0 起引入了 IO 线程（io-threads 配置项），专门把网络读写的 CPU 密集部分分摊到多个线程，但命令执行永远在主线程。

为什么选择单线程？

CPU 不是瓶颈。Redis 纯内存操作，单个命令执行时间通常是微秒级。瓶颈在内存带宽和网络 I/O，不是 CPU。
避免锁开销。如果多线程并发执行命令，Dict、SkipList 等核心结构都需要加锁，锁竞争的开销可能超过并行收益——毕竟每个命令本身就几微秒，加锁解锁可能也几微秒。
代码简单可靠。单线程意味着没有竞态条件，没有死锁。早期可能只是 antirez 的个人偏好，但事实上这个选择让 Redis 的核心代码保持了极高的可维护性。

事件循环的核心源码

Redis 的网络模型源码分三层：ae 抽象层 → epoll 实现层 → 上层网络处理。

// ae.c —— 主循环
void aeMain(aeEventLoop *eventLoop) {
    eventLoop->stop = 0;
    while (!eventLoop->stop) {
        aeProcessEvents(eventLoop, AE_ALL_EVENTS |
                                   AE_CALL_BEFORE_SLEEP |
                                   AE_CALL_AFTER_SLEEP);
    }
}

// ae.c —— 单次循环
int aeProcessEvents(aeEventLoop *eventLoop, int flags) {
    // 1. beforeSleep: 过期键清理、AOF刷盘、回复写入、IO线程任务分发
    if (eventLoop->beforesleep && (flags & AE_CALL_BEFORE_SLEEP))
        eventLoop->beforesleep(eventLoop);

    // 2. 阻塞等待 fd 就绪（Linux 下 → epoll_wait）
    numevents = aeApiPoll(eventLoop, tvp);

    // 3. afterSleep
    if (eventLoop->aftersleep && flags & AE_CALL_AFTER_SLEEP)
        eventLoop->aftersleep(eventLoop);

    // 4. 逐个处理就绪 fd 的读写回调（→ readQueryFromClient / sendReplyToClient）
    for (j = 0; j < numevents; j++) {
        if (mask & AE_READABLE)  fe->rfileProc(eventLoop, fd, ...);
        if (mask & AE_WRITABLE) fe->wfileProc(eventLoop, fd, ...);
    }

    // 5. 处理到期的定时事件（serverCron 等）
    processTimeEvents(eventLoop);
}

一次事件循环的完整时序：

 ┌──────────────────────────────────────────────────────────┐
 │  aeProcessEvents 单次迭代                                 │
 │                                                          │
 │  beforeSleep()        epoll_wait()      处理就绪fd+定时器  │
 │  ┌──────────────┐   ┌──────────┐    ┌──────────────┐    │
 │  │ 过期键清理    │   │ 阻塞等待  │    │ 读客户端命令   │    │
 │  │ AOF 刷盘     │──→│ fd就绪或  │───→│ 执行命令      │    │
 │  │ 回复写入      │   │ 超时     │    │ 写回复        │    │
 │  │ IO线程分发    │   │          │    │ serverCron   │    │
 │  └──────────────┘   └──────────┘    └──────────────┘    │
 │  不阻塞                阻塞            不阻塞              │
 └──────────────────────────────────────────────────────────┘

Redis 启动完毕后在 main() 最后一行执行 aeMain(server.el)，进入上述死循环直到进程退出。

一条请求的完整生命周期

  1. client 连接 → TCP 三次握手
  2. epoll_wait 检测到 listen_fd 可读
  3. acceptTcpHandler → accept() → createClient()
     - 将 conn_fd 设为 O_NONBLOCK
     - 注册 AE_READABLE 回调 → readQueryFromClient
  4. 客户端发送 "GET mykey\r\n"
  5. epoll_wait 检测到 conn_fd 可读
  6. readQueryFromClient():
     - read(fd, buf, 16KB)  ← 非阻塞读
     - 解析 RESP 协议
  7. processCommand():
     - lookupKey() 查 kvstore 找 redisObject
     - 检查过期、权限
     - call() 执行命令处理函数
  8. addReply() → 回复数据写入 client 的 reply buffer
  9. beforeSleep() 中 handleClientsWithPendingWrites():
     - writeToClient() 把 reply buffer 数据写回 socket
     - 如果 socket 缓冲区满没写完，注册 AE_WRITABLE 回调等下次继续写

Redis 6.0+ 的多线程网络模型

IO 线程只做网络读写和协议解析，不执行命令。实现代码在 iothread.c：

// iothread.c —— 每个 IO 线程内部也是独立的 ae 事件循环
void *IOThreadMain(void *ptr) {
    IOThread *t = ptr;
    aeSetBeforeSleepProc(t->el, IOThreadBeforeSleep);
    aeMain(t->el);
    return NULL;
}

// iothread.c —— 初始化 IO 线程池
void initThreadedIO(void) {
    if (server.io_threads_num <= 1) return;
    server.io_threads_active = 1;

    for (int i = 1; i < server.io_threads_num; i++) {
        IOThread *t = &IOThreads[i];
        t->el = aeCreateEventLoop(server.maxclients + CONFIG_FDSET_INCR);
        // 主线程与 IO 线程通过 eventfd 通信
        aeCreateFileEvent(t->el, getReadEventFd(t->pending_clients_notifier),
                          AE_READABLE, handleClientsFromMainThread, t);
        pthread_create(&t->tid, NULL, IOThreadMain, (void *)t);
    }
}

架构示意：

主线程通过 assignClientToIOThread(c) 把客户端分配给某个 IO 线程来处理读写。IO 线程完成读写和协议解析后，通过 eventfd 通知主线程，主线程在 beforeSleep 中调用 handleClientsFromIOThread 取回结果并执行命令。一句话：命令执行永不并发，网络读写可以并行。

六、Redis通信协议

1. RESP协议

Redis 的客户端和服务端之间使用 RESP（REdis Serialization Protocol）协议通信。它用纯文本形式传输，人类可读，解析简单，但同时足够紧凑。

五种基本数据类型（RESP2）

RESP 通过每行第一个字节区分数据类型：

首字节	类型	格式	示例
`+`	Simple String	`+内容\r\n`	`+OK\r\n`
`-`	Error	`-错误信息\r\n`	`-ERR unknown command\r\n`
`:`	Integer	`:数字\r\n`	`:1000\r\n`
`$`	Bulk String	`$字节数\r\n内容\r\n`	`$5\r\nhello\r\n`
`*`	Array	`*元素个数\r\n各元素...`	`*2\r\n$3\r\nGET\r\n$5\r\nmykey\r\n`

RESP3（Redis 6 引入）扩展了 ~（Set）、%（Map）、#（Bool）、,（Double）、(（Big Number）、=（Verbatim String）、|（Attribute）、_（Null）等类型，但核心思想不变：首字节决定类型，\r\n 分隔。

请求与响应示例

客户端发送一个 SET 命令：

*3\r\n            ← 数组，共 3 个元素
$3\r\n            ← 第 1 个元素，3 字节
SET\r\n           ← "SET"
$5\r\n            ← 第 2 个元素，5 字节
mykey\r\n         ← "mykey"
$5\r\n            ← 第 3 个元素，5 字节
Hello\r\n         ← "Hello"

服务端返回：

+OK\r\n           ← 简单字符串，表示成功

一个 GET 命令：

客户端：*2\r\n$3\r\nGET\r\n$5\r\nmykey\r\n
服务端：$5\r\nHello\r\n       ← 批量字符串，5 字节 "Hello"

RESP 在源码中的处理

resp_parser.h 中定义了完整的解析器回调。每种数据类型对应一个回调函数：simple_str_callback（+）、error_callback（-）、long_callback（:）、bulk_string_callback（$）、array_callback（*），解析完成后由上层 processCommand 取出 argc/argv 执行对应命令。

七、Redis内存策略

Redis 的内存管理涉及两个层面：键的过期删除（主动的还是人为设的 TTL）和内存满时的淘汰驱逐（不要和过期混淆）。两者分别回答"怎么删到期 key"和"满了怎么办"。

1. 过期策略

Redis 的键可以设置 TTL（Time To Live），到期后需要被删除。如果只用一个单一的删除机制，要么太慢（累积太多过期 key），要么太耗 CPU（不断扫描）。所以 Redis 采用了惰性删除 + 定期删除的组合策略。

惰性删除（Lazy Expiration）

每次访问一个 key 时，先检查它是否过期。如果已过期，当场删除并返回空。核心函数是 expireIfNeeded()，在 lookupKey() 中被调用。

优点是不浪费额外 CPU，缺点是如果某个过期 key 再也没被访问，它就永远占着内存。

定期删除（Active Expiration）

为了解决惰性删除的"垃圾堆积"问题，Redis 周期性主动扫描过期键，分两种模式：

SLOW 模式（慢速周期）：

由 serverCron 周期性触发（hz 频率，默认每秒 10 次）
每次从若干个数据库中随机采样，检查并删除过期 key
单次执行时间有上限：ACTIVE_EXPIRE_CYCLE_SLOW_TIME_PERC（默认 25%）的 CPU 时间
如果一轮没扫完所有数据库，下次继续从未完成的数据库开始

FAST 模式（快速周期）：

由 beforeSleep 触发，在事件循环的每次迭代中执行（频率远高于 SLOW）
单次执行时间上限仅 1ms（ACTIVE_EXPIRE_CYCLE_FAST_DURATION）
但如果上次 SLOW 周期没有因为超时而退出（说明过期 key 不多），或者过期比例低于阈值，FAST 模式会直接跳过

两种模式协作的逻辑（expire.c）：

  FAST mode（高频短跑）     SLOW mode（低频长跑）
  ┌────────────┐           ┌────────────────────┐
  │ 每次事件循环 │           │ 每次 serverCron     │
  │ 最多耗时 1ms │           │ 最多占 25% CPU 时间 │
  │ 过期少时跳过 │           │ 持续扫描所有数据库   │
  └────────────┘           └────────────────────┘
       ↑                          ↑
       └──── 共同保证过期 key 不会堆积 ────┘

惰性删除保证「访问时一定删」，定期删除保证「不访问也最终会删」。两者合力，在 CPU 开销和内存回收之间取得平衡。

2. 淘汰策略

淘汰（Eviction）和过期是两回事：过期是 key 到了 TTL 被删，淘汰是内存满了不得不删。

当 Redis 使用的内存达到 maxmemory 上限时，触发淘汰。策略由 maxmemory-policy 配置，共 10 种：

分类	策略	选择范围	淘汰标准
不淘汰	`noeviction`	—	写操作直接报错
LRU	`volatile-lru`	仅有过期时间的 key	近似 LRU
LRU	`allkeys-lru`	所有 key	近似 LRU
LFU	`volatile-lfu`	仅有过期时间的 key	近似 LFU
LFU	`allkeys-lfu`	所有 key	近似 LFU
随机	`volatile-random`	仅有过期时间的 key	随机
随机	`allkeys-random`	所有 key	随机
TTL	`volatile-ttl`	仅有过期时间的 key	最接近过期
LRM	`volatile-lrm`	仅有过期时间的 key	LRU + 采样后二次筛选
LRM	`allkeys-lrm`	所有 key	LRU + 采样后二次筛选

近似 LRU/LFU 的具体实现在 redisObject 的 lru 字段（24 位时钟/计数器）和 evict.c 的采样淘汰机制中已有详细说明，见第三章「lru 字段 —— 内存淘汰的近似 LRU」一节。

八、持久化

Redis 是内存数据库，数据在断电后会丢失。持久化就是把内存中的数据保存到磁盘上，重启时再加载回来。Redis 提供了两种机制：RDB（快照）和 AOF（日志），二者可单独使用也可组合使用。

1. RDB（Redis Database）

RDB 是全量快照式持久化。在某个时间点，把内存中所有数据序列化成一个二进制文件（默认 dump.rdb），恢复时直接读取这个文件重建整个数据集。

触发方式

手动触发：

SAVE：由主线程执行保存，保存期间 Redis 不能处理任何请求，适合停机维护场景。
BGSAVE：fork() 出一个子进程，子进程负责写入 RDB 文件，主进程继续处理请求，不阻塞服务。

自动触发（通过配置 save 参数）：

save 900 1     ← 900 秒内至少 1 次修改
save 300 10    ← 300 秒内至少 10 次修改
save 60 10000  ← 60 秒内至少 10000 次修改

满足任一条件即自动触发 BGSAVE。

BGSAVE 的 fork 机制

  主进程                     子进程
  ┌────────┐               ┌──────────┐
  │ 处理请求 │  ──fork()──→  │ 遍历内存   │
  │ 继续干活 │              │ 写入RDB文件│
  └────────┘               └──────────┘
       ↑
  共享同一份内存页（Copy-on-Write）
  主进程写某个页时，内核才复制那一页

得益于 Linux 的 Copy-on-Write，fork 时并不立即复制全部内存，主进程和子进程共享同一份物理内存页。只有当主进程修改了某个页时，内核才会把该页复制给子进程。因此内存占用峰值 ≈ 原始数据 + 写入期间的增量修改。

RDB 的优缺点

优点	缺点
文件紧凑，适合灾备和迁移	两次快照之间的数据可能丢失
恢复速度快，直接加载二进制	大数据量下 fork 耗时长，可能造成短暂卡顿
fork 子进程写入，主进程不阻塞	频繁 fork 会消耗 CPU

2. AOF（Append Only File）

AOF 是增量日志式持久化。把每一条修改命令以 RESP 协议格式追加写入日志文件，重启时逐条回放命令来还原数据。

刷盘策略

核心配置是 appendfsync，控制 write() 之后何时执行 fsync()（真正落盘）：

值	行为	安全性	性能
`always`	每执行一条修改命令立即 fsync	最高，最多丢一条	最慢
`everysec`	每秒 fsync 一次（默认）	最多丢 1 秒数据	折中，生产环境首选
`no`	不主动 fsync，交给 OS 决定	可能丢几秒数据	最快，但不推荐

源码 flushAppendOnlyFile() 中做了区分：AOF_FSYNC_ALWAYS 每次都同步，AOF_FSYNC_EVERYSEC 靠后台 bio 线程每秒刷盘。

AOF 重写（Rewrite）

AOF 文件会随运行时间不断膨胀。例如一个计数器被 INCR 了 100 次，AOF 中有 100 条记录，但最终值其实只需要一条 SET counter 100。重写就是创建一个新的 AOF 文件，用最少命令集描述当前数据库状态。

触发条件：

auto-aof-rewrite-percentage 100   ← 文件大小比上次重写后增长 100%
auto-aof-rewrite-min-size 64mb    ← 文件至少 64MB 才考虑重写

重写同样通过 fork 子进程执行（rewriteAppendOnlyFileBackground()），不影响主进程对外服务。重写期间新产生的修改命令同时写入旧的 AOF 文件和 AOF 重写缓冲区，等子进程完成后，再把缓冲区内容追加到新文件末尾，原子性地切换（rename）过去。

AOF 的优缺点

优点	缺点
最多丢失 1 秒数据	文件体积比 RDB 大
文件是 RESP 文本，可读可编辑	恢复速度比 RDB 慢（逐条回放）
rewrite 机制控制文件膨胀	`always` 策略下性能开销大

3. RDB + AOF 混合使用

Redis 4.0 引入了混合模式（aof-use-rdb-preamble yes）。AOF 重写时，子进程先把当前数据以 RDB 格式写入 AOF 文件头，再把后续的增量命令以 AOF 格式追加。结果是：前半段的 RDB 部分加载快，后半段的 AOF 部分保证数据完整性。生产环境推荐开启。

混合 AOF 文件结构:
 ┌──────────────┬────────────────────────┐
 │ RDB 格式快照  │ AOF 增量命令（RESP文本） │
 │  (二进制)     │  重写之后的修改命令      │
 └──────────────┴────────────────────────┘

九、事务

1. 事务的实现

Redis 的事务和关系型数据库的事务完全不同——没有隔离级别，没有回滚，不做行锁。它的语义很简单：把一组命令打包，按顺序串行执行，执行期间不插入其他客户端的命令。

三个核心命令：

MULTI：开启事务，标记客户端进入事务状态（CLIENT_MULTI 标志位）
EXEC：执行队列中所有命令
DISCARD：放弃事务，清空队列

源码流程（multi.c）：

  MULTI → 客户端设置 CLIENT_MULTI 标志
  之后的每个命令 → 不执行，而是加入 c->mstate.commands 队列
  每次收到命令 → addReply(c, shared.queued)  告诉客户端"已排队"
  EXEC → 遍历队列，逐个 call() 执行
  DISCARD → 清空队列，取消 CLIENT_MULTI 标志

// multi.c —— 事务中的命令不执行，只排队
void queueMultiCommand(client *c, uint64_t cmd_flags) {
    multiCmd *mc;
    // ...
    mc = &c->mstate.commands[c->mstate.count];
    mc->cmd = c->cmd;
    mc->argv_len = c->argv_len;
    // 复制参数、记录命令 —— 但不执行
    c->mstate.count++;
}

// multi.c —— EXEC 时批量执行
void execCommand(client *c) {
    // 检查是否被 WATCH 破坏
    if (c->flags & (CLIENT_DIRTY_CAS | CLIENT_DIRTY_EXEC)) {
        discardTransaction(c);
        return;  // 事务中止
    }
    // 逐条执行队列中的命令
    for (j = 0; j < c->mstate.count; j++) {
        call(c, c->mstate.commands[j].cmd);
    }
}

2. 原子性的真实含义

Redis 事务的原子性，指的是执行期间不被打断——MULTI 和 EXEC 之间排队的命令会一口气全部执行完，不会插入其他客户端的命令。但它不保证事务中某条命令失败后回滚前面的成功命令。

举例：

MULTI
SET key1 "a"
INCR key1       ← 对字符串执行 INCR，会失败（类型错误）
SET key2 "b"
EXEC

结果：key1 被设为 "a"，INCR key1 报错，但 key2 仍然被设为 "b"。前面的 SET key1 "a" 不会因为后面 INCR 失败而回滚。Redis 的设计哲学是：编程错误应该在开发阶段暴露，不应该依赖生产环境的运行时回滚。

3. WATCH —— 乐观锁

WATCH key 可以监视一个 key。如果在 WATCH 之后、EXEC 之前，被监视的 key 被其他客户端修改了，整个事务会被中止（返回 nil）。

这是 Redis 的乐观锁机制：不阻止别人写，但在提交时检查版本是否变了。常用于实现原子性的"检查后操作"（比如余额扣减前检查余额是否足够）。

WATCH balance
GET balance        ← 假设返回 100
MULTI
DECRBY balance 50
EXEC              ← 如果 balance 在 WATCH 后被别人改了，这里返回 nil

源码中通过 c->watched_keys 列表跟踪，被监视的 key 被修改时会设置 CLIENT_DIRTY_CAS 标志位，EXEC 检测到该标志位后中止执行。

十、主从复制

1. 复制的意义

单机 Redis 有 QPS 上限，且存在单点故障风险。主从复制的核心目标：

读写分离：主节点处理写请求，多个从节点处理读请求，分摊读压力
数据冗余：从节点持有完整数据副本，主节点宕机后可接管
高可用基础：配合哨兵（Sentinel），实现自动故障转移

2. 复制流程

Redis 的复制分为全量同步和部分同步两个阶段。

全量同步（Full Resynchronization）

初次连接或复制信息丢失时触发，流程如下：

  Slave                          Master
   │                                │
   │──── PSYNC ? -1 ──────────────→│   (首次连接，不知道任何 offset)
   │                                │
   │←── FULLRESYNC <replid> <offset>│   告诉 Slave "我们要全量同步"
   │                                │
   │                                │   Master 执行 BGSAVE，生成 RDB
   │                                │   ︙
   │←── 发送 RDB 文件 ─────────────→│
   │                                │
   │  加载 RDB，重建数据              │
   │                                │
   │←── 发送 RDB 期间的增量命令 ─────│   (replication buffer)
   │                                │
   │  执行增量命令，追上最新状态       │

Slave 发送 PSYNC ? -1（? 表示未知 master，-1 表示没有 offset）
Master 返回 FULLRESYNC 和自己的 replid + offset
Master 执行 BGSAVE 生成 RDB，发送给 Slave
RDB 生成期间的写操作暂存在 replication buffer 中，RDB 发完后一并发送
Slave 先加载 RDB，再执行增量命令，之后进入命令传播阶段

部分同步（Partial Resynchronization）

在连接短暂断开后重连时，如果条件满足，可以避免全量同步：

  Slave                          Master
   │                                │
   │── PSYNC <replid> <offset> ──→│
   │                                │
   │                             检查 repl_backlog 中是否还有 offset 位置的数据
   │                                │
   │←── CONTINUE ────────────────│   (在 backlog 中找到了，只补发差额)
   │                                │
   │←── 发送 offset 之后的增量 ────│

部分同步依赖 Master 的 replication backlog（默认 1MB 的环形缓冲区）。Master 会将每个写操作同时写入 backlog。如果 Slave 携带的 offset 仍然在 backlog 范围内，就可以只补发差额；如果已经超出范围（Slave 断开太久，backlog 中对应位置的数据被覆盖了），则降级为全量同步。

// replication.c —— backlog 定义
server.repl_backlog->offset = server.master_repl_offset + 1;
server.repl_backlog->histlen = 0;  // 当前 backlog 存储的数据长度
// 当 histlen > repl_backlog_size 时，旧数据被覆盖

命令传播

全量或部分同步完成后，Master 和 Slave 进入稳定状态。Master 每执行一个写命令，都会把命令广播给所有 Slave。Slave 接收后执行，保持数据一致。这是一个异步过程——Master 不等待 Slave 确认就返回客户端，因此主从之间可能存在毫秒级的复制延迟。

3. 主从拓扑

         ┌─────────┐
         │  Master  │  ← 写请求
         └────┬────┘
      ┌───────┼───────┐
      ↓       ↓       ↓
  ┌──────┐ ┌──────┐ ┌──────┐
  │Slave1│ │Slave2│ │Slave3│  ← 读请求
  └──────┘ └──────┘ └──────┘

Slave 也可以有自己的 Slave，形成级联复制，减轻 Master 的复制压力。

全文总结

十个章节串起 Redis 从数据到网络、从存储到容灾的完整知识体系：

一、背景        —— Redis 是什么、为什么快
二、组件        —— SDS / IntSet / Dict / ZipList / QuickList / SkipList / Listpack
                  七种积木块，解决「数据怎么存」
三、RedisObject —— 类型系统，encoding 字段把五种类型映射到七种组件
四、五种数据结构 —— String / List / Set / ZSet / Hash，对外暴露的最终形态
五、网络模型     —— epoll + 事件循环 + IO 线程，解决「请求怎么来、回复怎么回」
六、通信协议     —— RESP 协议，客户端和服务端的通用语言
七、内存策略     —— 过期删除 + 淘汰驱逐，解决「内存不够怎么办」
八、持久化       —— RDB 快照 + AOF 日志，解决「数据丢了怎么办」
九、事务         —— MULTI/EXEC/WATCH，一组命令原子执行，不被打断
十、主从复制     —— 全量同步 + 部分同步 + 命令传播，解决「单机不够怎么办」

PyTorch 学习路线图：从张量到 Transformer

Wed, 01 Apr 2026 00:00:00 GMT

这组文章整理自我手头三份不同来源的 PyTorch 资料：

liuer_pytorch：跟着一套完整课程从头做到尾，主线比较完整。
pytorch_learning：我自己之前断断续续做过的练手笔记，更偏 API 和记忆点。
pytorch_using：一份单独手写 Transformer 的实践代码。

如果直接按原文件夹去看，会有两个问题：

同一个主题被分散在不同目录里，学习节奏容易断。
有些内容偏“随手查 API”，有些内容偏“课程式推进”，混在一起不太像一条能连续读的路线。

所以我把它们重排成了下面这条主线：

线性回归、梯度下降与训练四步 先用最简单的回归任务把训练流程摸清楚：数据、模型、损失、优化器。
Tensor、Autograd 与动态计算图 把 PyTorch 和 NumPy 拉开差距的关键，就在 Tensor 和自动微分。
分类任务、Dataset / DataLoader 与训练循环 从二分类、多分类到小作业，真正把“如何喂数据、如何训练一个分类模型”串起来。
Module、functional、optim 工具箱 这一篇专门整理容易散落的 API：nn.Module、nn.functional、优化器、初始化和工程辅助工具。
CNN：从 LeNet 到经典卷积网络 把卷积、池化、LeNet、GoogLeNet、ResNet 这些卷积神经网络的核心脉络拉成一条线。
RNN 与序列建模入门 从 one-hot、embedding、RNN / LSTM 到名字-国家分类，把序列模型的最小心智先搭起来。
手写 Transformer 实现拆解 最后回到一个真正的 PyTorch 代码实践：不用 nn.Transformer，自己把位置编码、多头注意力、Encoder / Decoder 组起来。

这样整理之后，这组文章的阅读顺序就不是“看到什么学什么”，而是：

先明白训练一个模型到底在做什么
再理解 PyTorch 提供了哪些关键抽象
然后进入具体网络结构
最后用 Transformer 做一次综合收束

正文里我尽量保留了原始笔记的内容、写法和代码，只做了这几类整理：

合并重复主题
补上过渡说明，让章节之间更好衔接
把零散的 API 速记收成更适合复习的结构

如果你也是第一次系统整理 PyTorch，建议按这里的顺序往下读。

强化学习学习路线图：从 RL 基础到对齐训练

Wed, 01 Apr 2026 00:00:00 GMT

这组文章来自我阶段性整理强化学习相关笔记的结果。最开始的记录更像“边学边写”，主题会随着理解推进不断外扩：先从 RL 基础进入，再走到 DQN、策略梯度、Actor-Critic，最后自然连接到 LLM 对齐里的 RLHF、DPO 和 RLVR。

所以这次我没有按零散知识点保留原顺序，而是按一条更适合学习的主线把它们重新排成系列：

强化学习入门：为什么需要 RL、术语与 MDP 先建立为什么要用 RL、RL 在解决什么，以及 MRP / MDP / Bellman 这些最基础的心智模型。
免模型强化学习：DP、MC、TD、SARSA 与 Q-learning 当环境模型未知时，如何从“建模”转向“基于经验学习”，这是后面所有现代算法的真正起点。
从表格到函数：DQN 与 Value-Based 深度强化学习 把表格型 Q 函数推进到深度网络近似，并把 DDQN、PER 等常见改进放到一条线上看。
策略梯度入门：从定理到 REINFORCE 从 value-based 切到 policy-based，理解为什么“直接学策略”是必要的。
Actor-Critic 主线：优势函数、GAE、TRPO 与 PPO 这是现代强化学习最常见的一条工程主线，也是后面 RLHF 会不断回来的基础。
LLM 对齐训练：RLHF、奖励模型与规则化分支 把强化学习真正接到大模型对齐问题上，开始进入 reward model、PPO、Constitutional AI 这些核心概念。
Off-Policy 偏好优化：DPO 与新分支 在 RLHF 主线之外，补上 DPO 这条更轻量、也更常见的偏好优化路线。
可验证强化学习：RLVR 与 Tülu 3 当奖励可以被规则直接验证时，强化学习又会呈现出怎样的新训练形态。
RLHF 奠基论文：Helpful & Harmless Assistant 速记 作为补充阅读，把早期奠基工作单独抽出来，方便后面回看。

这组文章正文尽量保留了原始笔记，只做了三类整理：

调整顺序与命名，让它更像一条学习路径
补 frontmatter、导读和站内图片资源
对少量明显的占位标题或断裂处做轻度修正

如果你是第一次系统啃强化学习，我建议就按这里的顺序往下读。前半段先把基础与算法骨架搭起来，后半段再回到 LLM 对齐和偏好优化，整体会顺很多。

RAG 学习路线图：从基础管线到进阶检索与评估

Mon, 30 Mar 2026 00:00:00 GMT

这组文章来自我当前阶段对 RAG 的连续学习记录。和只查某个 API 或某个库的文档不同，RAG 更像一条系统链路：从数据进入，到分块、嵌入、索引、检索、查询优化，再到评估与迭代，环节之间的因果关系很强。

所以这一组我没有按“工具名”来组织，而是按“理解系统”的顺序来收：

RAG 入门：概念、优势与演进路线 先回答最基础的问题：RAG 到底在解决什么，为什么很多时候它比微调更合适，以及 Naive / Advanced / Modular RAG 的演进路线是什么。
RAG 数据加载：文档解析与预处理入口 当我们说“把知识接进系统”时，第一步到底在做什么。这里主要看文档加载器、非结构化数据解析，以及为什么加载质量会直接影响后面的检索效果。
RAG 文本分块：为什么切、怎么切、怎么权衡 分块是 RAG 最容易看轻、但最影响效果的环节之一。这里把块大小、重叠、递归分块、语义分块、结构化分块等策略整理到一起。
RAG 索引基础：向量嵌入、相似度与向量数据库 从“文本为什么能变成向量”讲起，再进入相似度度量和向量数据库的角色，把检索层的基础心智搭起来。
Milvus 入门：集合、索引与检索流程 当基础概念清楚之后，再具体进入 Milvus，理解 collection、schema、index、search 等真正搭系统时会用到的对象。
Milvus 多模态实践：图文嵌入到检索闭环 最后回到一条更接近实战的路径，用多模态样例把“编码 -> 入库 -> 建索引 -> 查询 -> 可视化”串起来。
Naive-RAG 端到端实战 把前面学过的加载、分块、嵌入、Milvus 检索和 FastAPI 串起来，先做一个最小但完整的 RAG demo，重点关注 grounded answer、评估指标和可部署性。
RAG 索引优化：上下文拓展与结构化索引 开始从“能跑”进入“怎么跑得更合理”。这一篇讨论索引层的两个关键思路：检索粒度与生成粒度不必相同，以及知识库变大后如何借助 metadata 做结构化过滤与路由。
RAG 混合检索：稀疏、密集与 Milvus 实现 把 dense / sparse 两条检索线放到同一张图里理解，再进入 RRF 与线性加权的差别，以及 Milvus 中如何落地双路召回。
RAG 查询构建：从元数据过滤到 Text2SQL 当知识源不只是自由文本，查询本身也要升级。这里主要看自然语言如何转成 metadata filter、Cypher 或 SQL。
RAG 查询翻译：重写、分解与路由 继续往前推进到 query optimization：原始问题未必是最优检索输入，所以要学会重写、拆分、HyDE 和查询路由。
RAG 检索进阶：重排、压缩与校正 进入生产感更强的一层：初步召回以后，怎么通过 rerank、compression 和 corrective retrieval 控制最终送给模型的上下文质量。
RAG 评估：指标、工作流与工具 最后收口到评估：先评检索，再评响应，再谈 RAGAS、Phoenix 等工具。这样系统效果变差时，才知道该改哪一段。

这条路线的目的不是把 RAG 讲成一个“背术语的模块集合”，而是尽量把它还原成一条完整的数据与检索管线。正文我尽量保留了原始笔记，只做了这几类整理：

调整了文章顺序与命名
补了系列 frontmatter 和少量导读
统一了图片资源路径，让它能直接进入博客文集

如果你是第一次系统啃 RAG，建议就按这里的顺序往下读。

LangChain 学习路线图：先组件，后 Agents，再回看 Middleware

Sun, 29 Mar 2026 00:00:00 GMT

这组文章来自我自己阅读 LangChain 官方文档时做的整理。原始笔记目前已经写到 10 篇，但官方文档的组织方式更像“方便查 API”，不完全像“方便学习一门框架”。

我读下来的几个不适感，基本就是这三点：

一上来先讲 Agents，容易让人先看到综合体，再去倒推底层组件。
文中经常会提前出现尚未展开的概念，查询时很方便，学习时却容易打断节奏。
某些章节的边界并不稳定，像 Models / Messages / Structured Output / Tools 之间会互相提前引用。

所以我把这条学习线改成了下面这条顺序：

OpenAI API 调用基线 先建立“模型调用到底发生了什么”的最小心智。
LangChain 入门与 Quick Start 先跑通一个最小例子，再看它的设计哲学，知道这个框架想解决什么问题。
Models 先理解模型对象本身怎么初始化、怎么调用、怎么流式输出。
Messages 模型吃进去和吐出来的最核心单位到底是什么。
Tools 让模型真正开始“做事”，并理解运行时上下文、状态、存储。
Short-term Memory 当对话变长时，怎么把状态和历史留住，以及如何裁剪、总结。
Streaming 当模型和 Agent 真的跑起来时，如何把过程实时展示出来。
Structured Output 当你不想只拿一段自然语言，而是想拿稳定可解析的数据结构时应该怎么做。
Agents 最后再回到 Agent，把前面的组件重新装回一台能运行的机器里。
Middleware 最后再回头看 middleware。因为它其实是对整个 agent loop 的“运行时切面控制”，不先理解 Agents，很难真正看懂它拦在哪里、为什么好用。

这样读的好处是：
先把“零件”摸透，再去理解“整机”；先懂模型、消息、工具、记忆这些底层块，再回头看 create_agent()，很多原本觉得跳跃的地方就会顺下来。

你可以把这组文章当成一条 LangChain 的学习路径，而不是单纯的文档摘抄。正文我尽量保留了原始笔记，只做了三类处理：

调整文章顺序
补了 frontmatter 和少量导读
保留原有代码、图和大部分表述，只做轻度润色

如果你是第一次系统啃 LangChain，建议就按这里的顺序一路往下读。

Study 栏写作说明

Sat, 21 Mar 2026 00:00:00 GMT

Study 现在只读取 src/content/posts/study/ 下的文章，并且会自动扫描它下面的一级目录生成主题入口与筛选项。

你之后写学习类内容时，只需要按主题新建目录，然后把文章放进去：

Python Base -> src/content/posts/study/python-base/
LLM Base -> src/content/posts/study/llm-base/
算法题 -> src/content/posts/study/算法题/
Fine Tuning -> src/content/posts/study/fine-tuning/
FastAPI -> src/content/posts/study/fastapi/
Pytorch -> src/content/posts/study/pytorch/
Reinforce Learning -> src/content/posts/study/reinforce-learning/
LangChain -> src/content/posts/study/langchain/

如果你之后想新增别的主题，比如 study/transformer-notes/，只要新建这个目录，它就会自动出现在 Study 的知识星点和文章筛选里。

如果你想控制这个目录在 Study 里的标题、右上角小图标、颜色和排序，就在目录里放一个 meta.json。

例如：

{
  "title": "Reinforce Learning",
  "eyebrow": "RL",
  "description": "放强化学习、DQN、PPO、策略梯度等内容。",
  "size": "medium",
  "accent": "138 168 255",
  "icon": "mdi:robot-outline",
  "order": 70
}

目前支持这些标识：

title 目录展示标题。
eyebrow 目录的小标签。
description 目录说明文案。
icon 目录图标，推荐用 mdi:*，例如 mdi:robot-outline、mdi:brain、mdi:api。
accent 目录主题色，格式是 "118 166 255" 这种 RGB 三元组字符串。
size 展示尺寸参数，可选： "wide"、"medium"、"default"
order 目录排序，数字越小越靠前。
hidden 是否隐藏这个目录入口，填 true 后不会显示在 Study 里。

Study 现在会直接联动下方的 Study 全部文章：

点击知识星点图里的主题节点，或者直接点筛选器
页面会滚动到下面的总文章列表
自动筛选出这个目录下的文章

写法还是普通 Markdown：

---
title: 你的文章标题
published: 2026-03-21
description: 一句话摘要
tags: [Python, Study]
category: Python Base
draft: false
---

如果你想在文章里插入可运行的 Python 代码块，可以直接这样写：

total = sum(i * i for i in range(6))
print("sum =", total)

上面这种写法现在会在文章页渲染成可折叠的 Python 代码卡。如果你想真正边写边跑，可以直接使用页面右侧悬浮的 Python Lab 小窗口。

写完保存后，本地开发环境会自动刷新；Study 的知识星点、筛选器和文章列表也会同步更新。提交并部署后，线上站点会一起更新。

PDF-RAG-Agent 项目文档

Sat, 02 May 2026 00:00:00 GMT

1. 项目介绍

PDF-RAG-Agent 是一个面向 Zotero 个人论文库的智能论文研究助手。它基于 FastAPI、SSE 流式对话和可视化前端，将用户问题先解析为结构化意图，再通过会话记忆、本地 PDF 语料检索、必要的 Web 搜索、证据抽取、claim 生成与 grounding 校验，最终输出带引用来源的 Markdown 回答。系统支持 PDF 文本、表格、图像/图注等多模态证据处理，默认使用 Milvus Dense 向量检索（可选 BM25/Title Anchor 多路融合），并在前端实时展示 Intent、Tool Loop、Evidence、Verification 和 PDF 预览，让论文问答从普通 RAG 升级为一个可追踪、可校验、支持多轮研究上下文的论文 Agent。

2. 项目背景与目标

2.1 为什么需要这个项目

该项目是在学习了RAG技术、Agent知识等内容后，想要做一个实际有价值、能解决固定问题的Agent系统，从而锻炼自己的Agent设计能力，积累相关经验。

2.2 普通 PDF RAG 的问题

常见的PDF RAG方法，对于大量pdf而言，召回困难，且得到的信息生硬，并且一旦需要多次RAG才能得到答案的问题，完全无法解决。

2.3 想解决什么

我们的目标是实现一个智能论文研究助手。它不仅要能快速找到目标论文，还要能完成多论文比较、论文公式提取、论文图表理解、用户意图拆解、多轮上下文延续和基础自我认知。也就是说，系统不能只停留在“检索一段文本然后回答”的普通 RAG 形态，而是需要在 RAG 层面做精细设计，并配合一个成熟可用的 Agent 系统，才能完成真实论文研究场景中的复杂问题。

3. 系统架构总览

PDF-RAG-Agent 是一个围绕论文研究的 Agent Loop 系统。从部署视角看分为前端、API、Agent、检索、数据、模型调用六层。从代码组织看，app/services/ 下按职责分为四组：

app/services/
├── 基础设施
│   └── infra/          model_clients, confidence, prompt_safety
├── 数据与检索
│   ├── library/        core, zotero_sqlite, metadata_sql, citation_ranking
│   ├── retrieval/      DualIndexRetriever, indexing, pdf_extractor, vector_index, web_search
│   └── memory/         session_store, learnings, artifacts, research
├── 领域逻辑（14 个子包）
│   ├── intents/        LLMIntentRouter, research, conversation, library, figure, followup, marker_matching
│   ├── planning/       research plan, query_shaping, query_rewrite, compound_tasks, solver_dispatch
│   ├── contracts/      session_context, normalization, contextual_resolver, followup_relationship
│   ├── claims/         ★ 23 modules: solver_pipeline, 13 deterministic solvers, verifiers, helpers
│   ├── answers/        entity, evidence_presentation, citation_whitelist, followup, formula, paper, topology, library_recommendations
│   ├── entities/       definition_helpers, definition_profiles, type_inference
│   ├── followup/       candidates, relationship_memory
│   ├── clarification/  intents, questions, limit_runtime
│   ├── eval/           judge (LLM-as-judge for evaluation)
│   └── tools/          dynamic_context, proposals, registry_helpers
└── Agent 编排
    ├── agent/          ★ 26 modules: core, loop, planner, runtime, chat_runtime, compound, handlers, traces
    └── agent_mixins/   answer_composer, claim_verifier, entity_definition, followup_routing, solver_pipeline

与前几版最大的架构变化：Agent 核心不再是一个巨大的单文件，而是拆成了 agent/（编排）和 agent_mixins/（正交能力注入）两层。领域逻辑也不在 Agent 内部耦合——claims/（23 个模块）、intents/、planning/、contracts/、answers/ 都是独立的领域子包，Agent 通过组合它们完成推理。

3.1 前端层

前端层由 app/static/index.html 提供单页页面，包含 Zotero 论文库侧栏、聊天区、运行时 Inspector、引用来源和 PDF 预览区域。用户的问题通过普通聊天接口或 SSE 流式接口发送到 API 层，前端再根据后端返回的 session、contract、agent_plan、plan、observation、agent_step、thinking_delta、tool_call、candidate_papers、screened_papers、evidence、solver_selection、claims、verification、reflection、confidence、answer_delta 和 final 等事件实时更新界面。它的重点不是承载复杂业务逻辑，而是提升系统可观察性。

3.2 API 层

API 层是前端和后端之间的边界，由 app/api/routes.py 提供。暴露健康检查、论文库浏览、论文预览、PDF 访问、引用预览、索引重建、普通聊天、SSE 流式聊天和动态工具提案管理等接口。API 层不承担 Agent 推理，只负责接收请求、调用依赖注入得到的服务对象、处理异常并序列化响应。

3.3 Agent 编排层

Agent 编排层由 agent/（26 个模块）和 agent_mixins/（6 个模块）组成，是整个系统的指挥中心。

agent/core.py 中的 ResearchAssistantAgent 通过多重继承组合五个 Mixin 获得正交能力：

class ResearchAssistantAgentV4(
    FollowupRoutingMixin,    # 追问路由：识别纠正/延续/切换
    AnswerComposerMixin,     # 答案组合：按 relation 分发到不同 answer composer
    EntityDefinitionMixin,   # 实体定义：消歧 + 定义提取
    SolverPipelineMixin,     # Claim 求解：schema / deterministic / shadow 三路径
    ClaimVerifierMixin,      # Grounding 校验：三层验证
):

Agent 执行一条请求的完整流程在 chat_runtime.py → loop.py 中编排：

run_agent_chat_turn() — 入口：解析 session → compress 历史 → 创建 run context → 尝试 compound → 走 standard turn
run_standard_turn() → extract_agent_query_contract() → planner.plan_actions() → runtime.execute_*() → solver → verifier → composer
loop.py 区分 run_conversation_turn() 和 run_research_turn() 两条路径

agent/ 目录下的其他关键模块：

planner.py — AgentPlanner：tool-calling / JSON / fallback 三级 plan 生成
runtime.py — AgentRuntime：conversation 和 research 两条 tool loop 执行路径
tool_registries.py — 构建 conversation (12 工具) 和 research (19 工具) 的 RegisteredAgentTool 字典
tools.py — 20 个 AgentToolSpec（LLM 可见） + AgentToolExecutor（运行时调度）
research_*_handlers.py — 四个 research 阶段的 handler：search / compose / verification / reflection
compound.py — 复合查询分解（”比较 DPO 和 PPO” → 两个子任务并行）
task.py — Task 子任务委托
trace.py / trace_diff.py — 执行追踪与 diff

3.4 意图与规划层

意图与规划层由三个子包构成，负责理解用户问题并生成执行计划：

intents/（10 模块）：router.py 中的 LLMIntentRouter 使用 tool-calling 模式做意图路由（5 个 tool choice → 20+ 种 relation）。research.py、conversation.py、library.py、figure.py、followup.py、memory.py 分别处理不同类型的意图标记和 answer slot 推断。contract_adapter.py 在 relation 和 answer_slots 之间做双向转换。marker_matching.py 提供 MarkerProfile 机制匹配用户问题中的关键词。
planning/（7 模块）：research.py 构建 ResearchPlan（召回模式、证据数量、solver 顺序）；query_shaping.py 从问题中提取 targets；query_rewrite.py 做多查询改写；compound_tasks.py 分解复合查询；solver_dispatch.py 和 solver_goals.py 决定哪些 solver 需要执行。
contracts/（8 模块）：session_context.py 构建每次 LLM 调用的会话上下文（含历史压缩）；normalization.py 规范化 targets；contextual_resolver.py 根据会话上下文消解实体引用；conversation_memory.py 管理跨轮次的 memory bindings；followup_relationship.py 处理追问关系继承。

关于 QueryContract：QueryContract 仍然是意图解析后的核心数据结构（定义在 domain/models.py），但它的构建不再是单一模块的责任。extract_agent_query_contract() 在 contract_extraction.py 中组合了 router 输出、target 抽取、followup 继承、pending clarification 处理等多个来源，最后统一规范化。

3.5 Claim 求解与验证层

这是整个系统最庞大的领域逻辑层。claims/ 子包有 23 个模块，是论文问答的核心引擎：

求解器（solvers）：solver_pipeline.py 是总入口，调度 schema solver 和 deterministic solver。13 个 deterministic solver 各处理一种 relation（formula_solver、figure_solver、table_solver、text_solver、origin_solver、entity_definition_solver、concept_definition_solver、followup_research_solver、generic_solver 等），通过 _DETERMINISTIC_SOLVER_REGISTRY 注册。deterministic_runner.py 提供 solver 执行基础设施。
验证器（verifiers）：verifier_pipeline.py 编排验证流程；type_verifiers.py 按 claim 类型做确定性校验（公式完整性、数值精确度、起源引用正确性）；llm_verifier.py 处理需要语义判断的复杂验证。
辅助模块：formula_text.py、metric_text.py、visual_helpers.py 处理公式/指标/图表的文本提取；paper_helpers.py、paper_summary.py 处理论文元信息；origin_selection.py 处理起源论文选择。

与 claims 紧密配合的是 answers/（10 模块）、entities/（4 模块）、followup/（2 模块）和 clarification/（3 模块），它们负责将 claim 转化为最终回答、处理实体定义、管理追问候选和生成澄清问题。

3.6 检索与数据层

retrieval/（9 模块）：core.py 中的 DualIndexRetriever 是在线检索核心——当前默认使用 Milvus Dense 单路召回。经过严格的消融实验（159 题 × 6 配置，详见 §11.5），text-embedding-3-large（3072 维）在 113 篇论文的封闭域上已达 Hit@1=97.5%，多路融合未带来增益，因此简化了默认检索路径。BM25 仍保留并修复了中文 jieba 分词；title anchor 和 relation anchor 保留为可选模块。indexing.py 中的 IngestionService 负责离线入库。pdf_extractor.py 基于 pypdf 做 PDF 文本和信号抽取。vector_index.py 封装 Milvus 向量索引。web_search.py 对接 Tavily API。
library/（4 模块）：zotero_sqlite.py 读取 Zotero 本地 SQLite；core.py 提供 LibraryBrowserService 论文库浏览；metadata_sql.py 提供 SQL 查询论文库元信息（供 query_library_metadata 工具使用）；citation_ranking.py 按引用数排序论文。
memory/（4 模块）：session_store.py 提供 SQLiteSessionStore（生产）和 InMemorySessionStore（测试）；learnings.py 管理持久化学习；artifacts.py 管理工具执行产物；research.py 管理研究记忆。

3.7 基础设施层

infra/（3 模块）：model_clients.py 中的 ModelClients 统一封装 Chat（当前 deepseek-v4-flash）、VLM（gpt-4.1-mini）、Embedding（text-embedding-3-large，走 Qihai 网关）三个模型能力。confidence.py 处理置信度归一化。prompt_safety.py 做输入安全检查。
eval/（1 模块）：judge.py 提供 LLM-as-judge 评估能力。
tools/（3 模块）：proposals.py 管理动态工具提案的生命周期；registry_helpers.py 提供工具注册的辅助函数；dynamic_context.py 管理动态工具上下文。

4. 启动入口

4.1 app/main.py

app/main.py 是整个 FastAPI 后端的装配入口。它本身不负责论文问答、检索或 Agent 推理，而是负责把应用运行所需的几类东西串起来：读取配置、初始化日志、定义生命周期、创建 FastAPI 应用、注册 API 路由、提供前端页面（/ 返回 index.html，/v4 /v5 301 重定向到 /），并在依赖存在时暴露 /metrics 监控指标。

from __future__ import annotations
from contextlib import asynccontextmanager
from pathlib import Path
from typing import AsyncIterator

这里首先导入了基础工具。from __future__ import annotations 用于延迟注解解析，Path 用于处理路径。asynccontextmanager 和 AsyncIterator 则与后面的 lifespan 机制有关，具体放在 4.4 再展开。

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import FileResponse, RedirectResponse

这里导入的是 FastAPI 应用装配相关能力。FastAPI 用于创建后端应用，CORSMiddleware 用于跨域配置，FileResponse 用于返回静态 HTML 或 PDF 文件，RedirectResponse 用于做路径跳转。

try:
    from prometheus_fastapi_instrumentator import Instrumentator
except Exception:
    Instrumentator = None

这里是可选监控依赖的导入逻辑。如果当前环境安装了 prometheus_fastapi_instrumentator，后面就可以用它暴露 Prometheus metrics；如果没有安装，也不会影响主应用启动。

from app.api.routes import router
from app.core.config import get_settings
from app.core.deps import close_cached_resources
from app.core.logging import setup_logging

这几行导入的是项目内部核心依赖。router 是 API 路由集合，get_settings 用于读取配置，close_cached_resources 用于应用关闭时释放缓存资源，setup_logging 用于初始化 JSON 日志。

APP_DIR = Path(__file__).resolve().parent
STATIC_DIR = APP_DIR / "static"

settings = get_settings()
setup_logging(settings.log_level)

这里完成了入口文件的基础准备工作。APP_DIR 指向 app 目录，STATIC_DIR 指向 app/static 目录，后面 /v4 会从这里返回 index.html。settings = get_settings() 会读取环境变量和项目 .env，并确保运行时目录存在；setup_logging(settings.log_level) 则根据配置初始化日志。

4.2 FastAPI 应用创建

app = FastAPI(
    title=settings.app_name,
    version="0.1.0",
    description="Zotero paper research agent",
    lifespan=lifespan,
)

这段代码真正创建了 FastAPI 应用对象。title、version 和 description 会出现在 OpenAPI 文档和服务元信息中。这里的 title 来自 settings.app_name，说明应用名称由配置统一管理。lifespan=lifespan 则把应用生命周期函数注册给 FastAPI，使服务启动和关闭时可以执行自定义逻辑。

if settings.cors_allow_origins:
    app.add_middleware(
        CORSMiddleware,
        allow_origins=list(settings.cors_allow_origins),
        allow_credentials=True,
        allow_methods=["GET", "POST"],
        allow_headers=["Authorization", "Content-Type", "X-API-Key"],
    )

创建应用之后，代码会根据配置决定是否启用 CORS。只有当 settings.cors_allow_origins 不为空时，才会添加 CORSMiddleware。这样可以避免默认放开跨域访问，同时在需要前后端分离或跨域调试时，通过环境变量显式配置允许访问的前端来源。

4.3 路由与静态页面挂载

app.include_router(router, prefix="/api/v1")

这句把 app/api/routes.py 中定义的 API 路由统一挂载到 /api/v1 前缀下面。也就是说，路由文件里定义的 /v4/chat、/v4/health 等接口，最终会变成 /api/v1/chat、/api/v1/health。其中 /api/v1 是接口协议版本，/api/v1 为协议版本前缀。

@app.get("/", include_in_schema=False)
def root() -> RedirectResponse:
    return RedirectResponse(url="/", status_code=307)

根路径 / 提供一个兜底跳转，用于本地直连或反向代理未单独配置首页时，直接返回前端页面（当前运行时版本）。在线上部署中，真实入口通常由域名和 Nginx 配置决定，例如 owen571.top 可以直接作为用户访问入口，所以这里不应该理解成项目唯一入口，而只是 FastAPI 内部的默认访问兜底。

@app.get("/legacy", include_in_schema=False)
def ui_legacy() -> FileResponse:
    return FileResponse(
        STATIC_DIR / "index.html",
        headers={
            "Cache-Control": "no-store, no-cache, must-revalidate, max-age=0",
            "Pragma": "no-cache",
            "Expires": "0",
        },
    )


@app.get("/v5", include_in_schema=False)
def ui_index() -> FileResponse:
    return FileResponse(
        STATIC_DIR / "index.html",
        headers={
            "Cache-Control": "no-store, no-cache, must-revalidate, max-age=0",
            "Pragma": "no-cache",
            "Expires": "0",
        },
    )

/v4 和 /v5 返回的是同一个静态 HTML 页面，也就是 app/static/index.html。浏览器拿到这个页面后，会执行其中的 JavaScript，再去请求 /api/v1/chat/stream、/api/v1/library 等后端接口。这里设置 Cache-Control: no-store 是为了避免浏览器缓存旧版前端页面，方便前端持续迭代和线上刷新。两个路径并存是为了兼容不同版本的前端入口（/v4 和 /v5 指向同一个最新前端页面，当前运行时版本为 V5）。

4.4 lifespan 资源释放

@asynccontextmanager
async def lifespan(_: FastAPI) -> AsyncIterator[None]:
    try:
        yield
    finally:
        await close_cached_resources()

这里，asynccontextmanager 是一个装饰器，用来把带有 yield 的异步函数变成异步上下文管理器。它用一种简单的方式表达了应用启动时进入、应用运行中停在 yield、应用关闭时执行 finally。FastAPI 在实例化时接收 lifespan=lifespan，就能自动识别启动和关闭时要执行的逻辑。它近似做了这件事：

cm = lifespan(app)

await cm.__aenter__()   # 执行 yield 前面的代码
try:
    await run_server()  # 应用运行中
finally:
    await cm.__aexit__()  # 继续执行 yield 后面和 finally

当前项目没有在启动阶段额外初始化重资源，所以直接 yield 提供服务。运行阶段由 FastAPI 处理各种请求；关闭阶段执行 finally，调用 close_cached_resources() 释放模型客户端、Retriever、HTTP 连接池等缓存资源。

4.5 Prometheus metrics

if Instrumentator is not None:
    Instrumentator(
        should_group_status_codes=True,
        should_ignore_untemplated=True,
    ).instrument(app).expose(app, include_in_schema=False, endpoint="/metrics")

如果 prometheus_fastapi_instrumentator 成功导入，应用就会暴露 /metrics 运维观测入口。Prometheus 会定时抓取这个接口并存储指标，Grafana 再读取 Prometheus 数据并画图。当前项目的基础 metrics 包括 HTTP 请求数、响应状态码、接口耗时、Python GC、进程内存、CPU 和文件描述符等。

从监控面板上可以看出几类信息。流量方面，Chat Stream Request Rate = 0.00702 req/s，表示最近五分钟平均每秒请求数；HTTP Request Rate by Handler 中 /metrics 最高，这是因为 Prometheus 每 15 秒抓一次，1 / 15 = 0.0667 req/s。延迟方面，Chat Stream p95 Latency = 1s，表明 95% 的 /chat/stream 请求耗时不超过约 1 秒；不过这个指标来自 FastAPI HTTP 层，对于 SSE 流式接口来说，它不完全等价于用户感知的首 token 延迟。错误方面，5xx Error Rate = No data 通常表示最近没有出现 5xx 错误。资源方面，内存如果长期持续上涨不下降就要怀疑泄漏；CPU 当前很低，说明服务基本空闲；Open File Descriptors 也很低，说明没有明显连接泄漏或文件句柄泄漏。

5. API 路由

API 路由层主要集中在 app/api/routes.py，负责把 FastAPI 的 HTTP 请求转换为对后端服务层和 Agent 层的调用。它通过 APIRouter 定义 /v4/* 系列接口，并在 main.py 中统一挂载到 /api/v1 前缀下。该层不直接实现复杂业务逻辑，而是负责参数接收、依赖注入、权限校验、异常转换、响应模型封装和 SSE 流式事件输出，是前端与后端核心能力之间的边界层。

这里，我们先用 app.schemas.api 中定义的一系列Schema，来规范返回的格式。

from app.schemas.api import (
    AgentChatRequest,
    AgentChatResponse,
    AgentCitation,
    CitationPreviewResponse,
    HealthResponse,
    IngestRequest,
    IngestResponse,
    LibraryResponse,
    PaperPreviewResponse,
)

5.1 health

health 是最简单的状态检查接口，用来判断后端服务是否已经正常启动，并让前端确认当前加载的是 V4 的新版运行时。

@router.get("/v4/health", response_model=HealthResponse)
def health() -> HealthResponse:
    return HealthResponse()

这个接口没有请求参数，也不会触发 Agent、检索器或模型调用，只是直接返回一个 HealthResponse。由于 routes.py 中的路由会在 main.py 里统一挂载到 /api/v1 前缀下，所以它的真实访问路径是 /api/v1/health。前端启动时会请求这个接口，用返回值判断服务是否在线、当前 runtime 是否支持结构化摘要，以及后端暴露的 canonical tools 是否为 read_memory、search_corpus、web_search、query_library_metadata、compose、ask_human。

class HealthResponse(BaseModel):
    status: str = "ok"
    runtime_profile: str = "structured-intent-react-loop"
    runtime_summary_supported: bool = True
    canonical_tools: list[str] = Field(
        default_factory=lambda: ["read_memory", "search_corpus", "web_search", "query_library_metadata", "compose", "ask_human"]
    )

5.2 library

library 接口用于返回当前论文库的整体列表，是前端左侧 Zotero Corpus 侧栏的数据来源。

@router.get("/v4/library", response_model=LibraryResponse)
def library(
    library_service: LibraryBrowserService = Depends(get_library_service),
) -> LibraryResponse:
    return LibraryResponse(**library_service.list_library())

这个接口通过 Depends(get_library_service) 获取 LibraryBrowserService 实例。Depends 是 FastAPI 的依赖注入机制，意思是请求进入这个接口时，FastAPI 会先调用 get_library_service()，把返回的服务对象传给 library_service 参数。真正读取论文库、整理分类、生成论文列表的逻辑不写在路由层，而是交给 library_service.list_library() 完成。

接口返回值被声明为 LibraryResponse，LibraryResponse 是论文库接口的最外层响应，表示“整个论文库浏览结果”。它里面有一个 categories，类型是 list[LibraryCategory]，表示按 Zotero collection、标签或“未分类”分组后的论文列表；还有一个 total_papers，表示当前论文库里去重后的论文总数。LibraryCategory 表示一个分类分组，name 是分类名，count 是这个分类下有多少篇论文，papers 是该分类下的论文列表。最里面的 LibraryPaper 是前端论文卡片需要的最小展示单元，包含 paper_id、title、authors、year、tags、categories、file_path、preview 等字段。

5.3 paper preview / pdf

这一节对应两个论文预览相关接口：一个返回论文的结构化预览信息，另一个返回真实 PDF 文件。

@router.get("/v4/library/papers/{paper_id}/preview", response_model=PaperPreviewResponse)
def paper_preview(
    paper_id: str,
    library_service: LibraryBrowserService = Depends(get_library_service),
) -> PaperPreviewResponse:
    payload = library_service.paper_preview(paper_id)
    if payload is None:
        raise HTTPException(status_code=404, detail="paper not found")
    return PaperPreviewResponse(**payload)

paper_preview 用于根据 paper_id 返回某篇论文的预览信息。这里的 paper_id 来自 URL 路径，例如 /api/v1/library/papers/xxx/preview。路由层会调用 library_service.paper_preview(paper_id)，如果找不到对应论文，就抛出 404 paper not found；如果找到，就包装成 PaperPreviewResponse 返回。这个响应里包含论文基础信息和若干证据片段，供前端右侧 Preview 面板展示。

@router.get("/v4/library/papers/{paper_id}/pdf")
def paper_pdf(
    paper_id: str,
    _: None = Depends(require_pdf_access),
    library_service: LibraryBrowserService = Depends(get_library_service),
) -> FileResponse:
    path = library_service.pdf_path(paper_id)
    if path is None:
        raise HTTPException(status_code=404, detail="pdf not found")
    return FileResponse(path, media_type="application/pdf", filename=path.name, content_disposition_type="inline")

paper_pdf 用于返回某篇论文的 PDF 文件。这个接口比 preview 更敏感，因为它会直接把 Zotero 本地 PDF 文件发给浏览器，所以这里增加了 Depends(require_pdf_access) 做访问控制。library_service.pdf_path(paper_id) 会解析并校验 PDF 路径，如果文件不存在、不是 PDF，或者不在允许的 Zotero 路径范围内，就返回 None，接口再抛出 404 pdf not found。成功时，FileResponse 会以 application/pdf 类型返回文件，并通过 content_disposition_type="inline" 让浏览器尽量以内嵌预览方式打开，而不是直接下载。

5.4 citation preview

citation preview 用于根据回答中的引用信息，反查对应的证据片段，给前端的引用预览面板使用。

@router.get("/v4/citations/preview", response_model=CitationPreviewResponse)
def citation_preview(
    doc_id: str = Query(default=""),
    paper_id: str = Query(default=""),
    library_service: LibraryBrowserService = Depends(get_library_service),
) -> CitationPreviewResponse:
    payload = library_service.citation_preview(doc_id=doc_id, paper_id=paper_id)
    if payload is None:
        raise HTTPException(status_code=404, detail="citation evidence not found")
    return CitationPreviewResponse(**payload)

这个接口和前面的论文预览不同，它不是按路径参数接收 paper_id，而是通过 query 参数接收 doc_id 和 paper_id，真实访问形式类似 /api/v1/citations/preview?doc_id=xxx&paper_id=yyy。其中 doc_id 更精确，指向某一个 evidence block；paper_id 更粗，指向某一篇论文。服务层会优先用 doc_id 找 block 级证据，如果找不到，再尝试用 paper_id 找论文级信息。

class CitationPreviewResponse(BaseModel):
    paper_id: str = ""
    doc_id: str = ""
    title: str = ""
    authors: str = ""
    year: str = ""
    file_path: str = ""
    page: int = 0
    block_type: str = ""
    caption: str = ""
    snippet: str = ""

返回结果里既包含论文元信息，也包含页码、块类型、图注和证据片段。这样前端在用户点击回答里的引用时，不需要重新跑 Agent，也不需要重新检索，只要拿着引用里的 doc_id 或 paper_id 调这个接口，就能展示对应来源。换句话说，citation preview 是“回答引用”到“原始证据”的轻量跳转接口，它主要服务于可追踪性和结果校验。

5.5 ingest rebuild

ingest rebuild 是索引重建接口，用来把 Zotero 论文库重新抽取、切块、入库，并更新本地检索索引。

@router.post("/v4/ingest/rebuild", response_model=IngestResponse)
def ingest_rebuild(
    payload: IngestRequest,
    _: None = Depends(require_admin_access),
    ingestion_service: IngestionService = Depends(get_ingestion_service),
) -> IngestResponse:
    try:
        stats = ingestion_service.rebuild(max_papers=payload.max_papers, force_rebuild=payload.force_rebuild)
        get_retriever().refresh()
    except Exception as exc:
        logger.exception("v4 ingest rebuild failed")
        raise HTTPException(status_code=500, detail="ingest rebuild failed") from exc
    return IngestResponse(message="v4 ingestion completed", **stats.to_dict())

这个接口是 POST 请求，因为它会改变系统状态。它不是给普通用户频繁点击的问答接口，而是管理员在新增论文、修改 Zotero 库、重建向量索引时使用的维护接口。所以参数中有 Depends(require_admin_access)，请求必须带正确的 admin API key，否则会返回 401；如果服务端没有配置 ADMIN_API_KEY，则会返回 503，避免危险接口在无保护状态下暴露。

class IngestRequest(BaseModel):
    force_rebuild: bool = True
    max_papers: int | None = Field(default=None, ge=1)

class IngestResponse(BaseModel):
    message: str
    paper_records: int = 0
    papers_indexed: int = 0
    papers_missing_pdf: int = 0
    block_docs: int = 0
    paper_docs: int = 0
    vectors_upserted: int = 0
    papers_with_generated_summary: int = 0

max_papers 用于限制本次最多处理多少篇论文，适合调试或小规模验证；force_rebuild 会传给向量索引层，如果为 true，会重建 Milvus collection 后再写入向量。返回值里的 paper_records 表示从 Zotero 读取到的记录数，papers_indexed 表示成功完成 PDF 抽取并入库的论文数，papers_missing_pdf 表示 Zotero 里有记录但本地 PDF 缺失的数量，paper_docs 是论文级索引文档数，block_docs 是 PDF 页面、段落、表格、图注等证据块文档数，vectors_upserted 是写入 Milvus 的向量数量。

它的完整链路是：路由层接收请求并校验管理员权限，IngestionService.rebuild() 读取 Zotero 记录，调用 PDF 抽取器解析页面内容，生成 paper card 和 block documents，写入 papers.jsonl、blocks.jsonl 和 ingestion state；如果配置了 embedding 所需的 API key，还会把论文级文档和证据块文档写入 Milvus。最后，路由层调用 get_retriever().refresh()，让正在运行的服务重新加载本地 JSONL 和 BM25 索引，这样重建完成后前端查询可以立即使用新论文库。

5.6 chat / stream chat

chat 和 chat/stream 是前端真正发起论文问答的两个入口。它们使用同一个请求模型 AgentChatRequest，区别在于返回方式不同：chat 等 Agent 全部运行结束后一次性返回完整 JSON；chat/stream 则通过 SSE 把运行事件和回答增量实时推给前端。

class AgentChatRequest(BaseModel):
    query: str = Field(min_length=1)
    session_id: str | None = None
    mode: str = "auto"
    use_web_search: bool = False
    max_web_results: int = Field(default=3, ge=1, le=10)
    clarification_choice: dict[str, Any] | None = None

这里的 query 是用户输入的问题，session_id 用于延续多轮对话，mode 默认为 auto，让 Agent 自己判断是普通对话还是研究任务。use_web_search 控制是否允许补充 Web Search，max_web_results 限制网页搜索数量，clarification_choice 用于处理上一轮 Agent 反问用户后的选择结果。

@router.post("/v4/chat", response_model=AgentChatResponse)
async def agent_chat_v4(
    payload: AgentChatRequest,
    agent: ResearchAssistantAgent = Depends(get_agent),
) -> AgentChatResponse:
    try:
        result = await agent.achat(
            query=payload.query,
            session_id=payload.session_id,
            mode=payload.mode,
            use_web_search=payload.use_web_search,
            max_web_results=payload.max_web_results,
            clarification_choice=payload.clarification_choice,
        )
    except Exception as exc:
        logger.exception("v4 chat failed")
        raise HTTPException(status_code=500, detail="chat failed") from exc

普通 chat 接口通过 Depends(get_agent) 拿到全局缓存的 ResearchAssistantAgent，然后调用 agent.achat()。虽然路由函数是 async，但 Agent 内部主要是同步的检索、规划和模型调用，所以 achat() 实际上会用 asyncio.to_thread() 把同步 chat() 放到线程里执行，避免长时间阻塞 FastAPI 的事件循环。接口如果执行失败，会记录异常日志，并统一返回 500 chat failed。

citation_models = [AgentCitation(**item) for item in result.get("citations", [])]
return AgentChatResponse(
    session_id=str(result.get("session_id", "")),
    interaction_mode=str(result.get("interaction_mode", "")),
    answer=str(result.get("answer", "")),
    citations=citation_models,
    query_contract=dict(result.get("query_contract", {})),
    research_plan_summary=dict(result.get("research_plan_summary", {})),
    runtime_summary=dict(result.get("runtime_summary", {})),
    execution_steps=list(result.get("execution_steps", [])),
    verification_report=dict(result.get("verification_report", {})),
    needs_human=bool(result.get("needs_human", False)),
    clarification_question=str(result.get("clarification_question", "")),
    clarification_options=list(result.get("clarification_options", [])),
)

这里可以看到，chat 的返回不只是最终答案，还包括引用、结构化意图、研究计划摘要、运行时摘要、执行步骤、验证报告和澄清信息。因此它更像是一次完整 Agent 运行结果的快照，适合调试、测试或不需要实时流式展示的调用场景。

@router.post("/v4/chat/stream")
async def agent_chat_v4_stream(
    payload: AgentChatRequest,
    agent: ResearchAssistantAgent = Depends(get_agent),
) -> StreamingResponse:
    async def event_stream() -> object:
        try:
            async for item in agent.astream_chat_events(
                query=payload.query,
                session_id=payload.session_id,
                mode=payload.mode,
                use_web_search=payload.use_web_search,
                max_web_results=payload.max_web_results,
                clarification_choice=payload.clarification_choice,
            ):
                yield _format_sse(str(item.get("event", "message")), item.get("data", {}))
        except Exception as exc:
            logger.exception("v4 stream failed")
            for event, data in _stream_error_events(exc):
                yield _format_sse(event, data)

chat/stream 是前端主要使用的接口。它没有声明 response_model，因为它返回的不是一个普通 JSON，而是一条持续输出的事件流。event_stream() 是一个异步生成器，会不断从 agent.astream_chat_events() 里拿事件，再用 _format_sse() 转成 SSE 格式。SSE 的基本格式是 event: 事件名 加 data: JSON字符串，中间用空行分隔，浏览器可以边接收边渲染。

def _format_sse(event: str, data: object) -> str:
    return f"event: {event}\ndata: {json.dumps(data, ensure_ascii=False)}\n\n"

Agent 在运行过程中会不断产生 session、contract、agent_plan、plan、observation、agent_step、thinking_delta、tool_call、candidate_papers、screened_papers、evidence、solver_selection、claims、verification、reflection、confidence、answer_delta、final 等事件。前端收到这些事件后，就能实时更新 Runtime 面板、引用列表和回答正文。最新的 LLM-judge 候选消歧也会通过 observation 暴露出来，例如 summary=options=4, judge=auto_resolve, confidence=0.95。相比普通 chat，chat/stream 的价值在于可观察性更强，用户不用等完整答案生成完，前端也能展示 Agent 正在理解问题、调用工具、检索证据、消解候选并组合答案的过程。

return StreamingResponse(
    event_stream(),
    media_type="text/event-stream",
    headers={
        "Cache-Control": "no-cache",
        "Connection": "keep-alive",
        "X-Accel-Buffering": "no",
    },
)

最后返回的 StreamingResponse 指定了 text/event-stream，这是 SSE 的标准媒体类型。Cache-Control: no-cache 避免中间层缓存流式结果，Connection: keep-alive 保持连接不断开，X-Accel-Buffering: no 则是给 Nginx 的提示，避免反向代理把事件攒在一起后再一次性返回。这个接口本质上就是把 Agent 内部运行轨迹包装成浏览器可以消费的实时事件流。

流式返回的总链路：用户点击发送 -> fetch POST /api/v1/chat/stream -> FastAPI StreamingResponse 打开长连接 -> Agent 在线程里执行 run_agent_chat_turn() -> 执行过程中 emit_event(item) 把事件放入 asyncio.Queue -> astream_chat_events() 从 queue 取事件并 yield -> routes.py 转成 SSE 文本 -> 浏览器 reader.read() 持续读取 -> parseSse() 解析 event/data -> answer_delta 追加回答，final 收尾

5.7 动态工具提案管理 API

这是一组管理员接口，用于管理动态注册的 Agent 工具提案，支持从提案创建、沙盒测试到正式启用的完整生命周期。

@router.get("/v4/admin/tools/proposals")
def admin_list_tool_proposals(
    include_code: bool = Query(default=False),
    _: None = Depends(require_admin_access),
    settings: Settings = Depends(get_settings),
) -> dict[str, object]:
    return {"items": list_tool_proposals(data_dir=settings.data_dir, include_code=include_code)}

GET /api/v1/admin/tools/proposals 列出所有工具提案，可选参数 include_code 控制是否返回提案中的 Python 代码。

@router.get("/v4/admin/tools/proposals/{proposal_id}")
def admin_get_tool_proposal(proposal_id: str, ...) -> dict[str, object]:
    return load_tool_proposal(data_dir=settings.data_dir, proposal_id=proposal_id, include_code=include_code)

GET /api/v1/admin/tools/proposals/{proposal_id} 获取单个工具提案的完整内容，包括代码和元信息。

@router.post("/v4/admin/tools/proposals/{proposal_id}/sandbox")
def admin_run_tool_proposal_sandbox(proposal_id: str, payload: ToolProposalSandboxRequest, ...):
    return run_tool_proposal_sandbox(
        proposal_path=proposal_path,
        args=payload.args,
        timeout_seconds=payload.timeout_seconds,
        memory_limit_mb=payload.memory_limit_mb,
    )

POST /api/v1/admin/tools/proposals/{proposal_id}/sandbox 在沙盒环境中执行工具提案代码，验证其功能是否正常。ToolProposalSandboxRequest 包含 args（工具参数）、timeout_seconds（超时限制，最大 30s）和 memory_limit_mb（内存限制，64-2048 MB）。

@router.post("/v4/admin/tools/proposals/{proposal_id}/status")
def admin_transition_tool_proposal_status(proposal_id: str, payload: ToolProposalTransitionRequest, ...):
    return transition_tool_proposal_status(
        proposal_path=proposal_path,
        next_status=payload.next_status,
        code_sha256=payload.code_sha256,
        reviewer=payload.reviewer,
        note=payload.note,
        sandbox_report=payload.sandbox_report,
    )

POST /api/v1/admin/tools/proposals/{proposal_id}/status 切换工具提案的状态（如 draft → sandboxed → active 或 deprecated）。ToolProposalTransitionRequest 包含 next_status（下一状态）、code_sha256（代码哈希用于校验完整性）、reviewer（审核人）、note（备注）和 sandbox_report（沙盒测试报告）。

所有工具提案接口都需要通过 require_admin_access 校验管理员身份，与 ingest rebuild 一样的安全控制。

6. 数据模型

6.1 API schema

app.schemas.api 里的 BaseModel 负责规定前端和后端之间的数据格式。它们更像 HTTP 边界上的“合同”：前端传进来的请求必须满足请求 schema，后端返回给前端的数据也要满足响应 schema。比如 AgentChatRequest 约束了 query 不能为空，max_web_results 必须在 1 到 10 之间；AgentChatResponse 则规定了一次问答最终要返回 answer、citations、query_contract、runtime_summary、verification_report 和澄清相关字段。

如果请求不满足 schema，FastAPI 会在进入路由函数之前返回 422。如果后端构造出来的响应不满足 response_model 或手动实例化的 Pydantic schema，就说明后端实现违反了自己的接口合同，通常会变成服务端异常。也就是说，API schema 的价值不只是“写注解”，而是把前后端交互格式固定下来，让错误尽早暴露。

6.2 domain models

这是更靠近 Agent 内部推理的数据结构，比如 QueryContract、SessionContext、ResearchPlan、CandidatePaper、DisambiguationJudgeDecision、EvidenceBlock、Claim、VerificationReport、AssistantCitation、AssistantResponse 等。它们不是给前端页面直接展示用的，而是 Agent 在理解问题、规划检索、筛选论文、消解歧义、抽取证据、生成 claim、做 grounding 校验和组织最终答案时使用的内部协议。

用一句话概括：API schema 是后端对前端说话的格式，domain models 是 Agent 内部思考和协作的格式。没有这些结构，系统就会退化成到处传 dict，每个模块都靠记忆猜字段名，很容易出现 target、targets、paper_titles、active_titles 混用的问题。

当前研究链路可以概括为：

用户问题
-> AgentChatRequest：API 接收用户请求
-> QueryContract：把自然语言问题变成结构化研究意图
-> ResearchPlan：决定召回方式、证据数量和 solver 顺序
-> CandidatePaper：论文级候选
-> DisambiguationJudgeDecision：在候选有歧义时判断是否可自动绑定
-> EvidenceBlock：具体证据块
-> Claim：基于证据提炼出的结论
-> VerificationReport：检查 claim 是否被证据支持，是否需要 retry 或澄清
-> AssistantResponse：最终回答、引用、运行摘要和澄清信息
-> SessionContext / SessionTurn：把本轮研究写入多轮记忆

6.3 QueryContract

QueryContract 是用户问题进入 Agent 后最关键的结构化意图对象。它把一句自然语言问题拆成后续模块可以执行的字段，例如 relation 表示问题类型，targets 表示目标实体或论文，requested_fields 表示需要回答哪些信息，required_modalities 表示需要什么证据类型，answer_shape 表示答案形态，precision_requirement 表示精确度要求。

以最新真实 trace 中的 DPO 查询为例，用户输入是 帮我看看 DPO 这篇论文的核心公式，系统得到的核心 contract 是：

{
  "clean_query": "帮我看看 DPO 这篇论文的核心公式",
  "interaction_mode": "research",
  "relation": "formula_lookup",
  "targets": ["DPO"],
  "answer_slots": ["formula"],
  "requested_fields": ["formula", "variable_explanation", "source"],
  "required_modalities": ["page_text", "table"],
  "answer_shape": "bullets",
  "precision_requirement": "exact",
  "continuation_mode": "fresh",
  "allow_web_search": false
}

这里的 relation=formula_lookup 决定了后续会走公式相关的检索和 solver；requested_fields 要求答案必须包含公式、变量解释和来源；precision_requirement=exact 表示系统不能只给概念性总结，而要尽量找到原文中的数学表达式。

notes 是 QueryContract 里的扩展记录区，用于保存结构化意图之外的运行痕迹。最新 LLM-judge 自动消歧后，真实 notes 中会出现 auto_resolved_by_llm_judge、selected_paper_id=S6H9FE28、disambiguation_judge_confidence=0.950 和 disambiguation_judge_reason=...，说明系统不是让用户手动选择，而是在高置信度条件下自动绑定到了 DPO 原论文。

6.4 SessionContext

SessionContext 负责保存多轮对话状态。它包含当前会话的 session_id、最近研究主题、active research、历史 turn、工作记忆和 pending clarification 等信息。比如用户上一轮刚问过 DPO，下一轮追问“那这个公式里的 beta 是什么”，系统就需要通过 SessionContext 知道“这个公式”指的是 DPO 论文中的公式，而不是重新把问题当成一个全新任务。

这个模型里有一些 legacy 字段，例如 active_targets、active_titles、active_research_relation 等，同时也有新的 active_research 对象。sync_active_research_compatibility() 的作用就是在旧字段和新结构之间做兼容同步，这是项目多次重构后留下的真实工程痕迹。

在旧机制里，DPO 歧义会写入 pending_clarification_options，然后等待用户下一轮选择。现在加入 LLM-judge 后，如果 judge 给出高置信度自动绑定，系统就不会进入 needs_human=true；如果 judge 不够确定，仍然会保留人工澄清路径，并把推荐候选标记为 judge_recommended。

6.5 ResearchPlan

ResearchPlan 是 Agent 对“怎么查”的计划。它不关心最终回答怎么写，而是规定论文召回模式、候选数量、证据数量、solver 顺序和 retry 预算。

class ResearchPlan(BaseModel):
    paper_recall_mode: Literal["anchor_first", "broad", "broad_then_anchor"] = "broad"
    paper_limit: int = 6
    evidence_limit: int = 14
    solver_sequence: list[str] = Field(default_factory=list)
    required_claims: list[str] = Field(default_factory=list)
    retry_budget: int = 1

DPO 公式查询的真实计划是 paper_recall_mode=anchor_first、paper_limit=6、evidence_limit=24、solver_sequence=["formula_solver", "table_solver"]、required_claims=["formula", "variable_explanation"]。这说明系统会先围绕 DPO 这个 anchor 找论文，再在选中论文里扩展更多公式/表格相关证据。

6.6 CandidatePaper / DisambiguationJudgeDecision

CandidatePaper 是论文级候选，表示“系统认为可能相关的一篇论文”。它包含 paper_id、title、year、score、match_reason、anchor_terms、doc_ids 和原始 metadata。对于 DPO 这类缩写问题，单纯召回候选还不够，因为本地库里可能有很多论文都提到了 DPO。

最新加入的 DisambiguationJudgeDecision 就是为了解决这个问题。它是 LLM-judge 的结构化输出：

class DisambiguationRejectedOption(BaseModel):
    option_id: str = ""
    reason: str = ""

class DisambiguationJudgeDecision(BaseModel):
    decision: Literal["auto_resolve", "ask_human"] = "ask_human"
    selected_option_id: str | None = None
    selected_paper_id: str | None = None
    confidence: float = Field(default=0.0, ge=0.0, le=1.0)
    reason: str = ""
    rejected_options: list[DisambiguationRejectedOption] = Field(default_factory=list)

这一步发生在 _agent_solve_claims() 中。系统先根据 evidence 生成多个 ambiguity options，再调用 _judge_disambiguation_options()，让模型根据用户 query、QueryContract、候选 title、snippet、paper summary 和 ranking signals 判断哪个候选最符合用户真实意图。

这里有两个阈值很重要：DISAMBIGUATION_AUTO_RESOLVE_THRESHOLD = 0.85，只有 judge 决策为 auto_resolve 且置信度不低于 0.85，系统才会自动绑定候选；DISAMBIGUATION_RECOMMEND_THRESHOLD = 0.65，如果置信度在推荐区间，系统只会把候选置顶并标记 judge_recommended，仍然让用户确认。这样既减少了显然可判断场景下的打断，也保留了低置信度情况下的人工兜底。

6.7 Evidence / Claim / Verification / Citation

EvidenceBlock 是证据块，负责保存证据来自哪篇论文、哪一页、哪种 block、具体片段是什么。它让回答可以追溯到 PDF 页面，也让 citation preview 和 PDF preview 有了可定位的信息。

Claim 是从 evidence 中抽取出来的结论单元。比如公式查询中，claim 会保存公式文本、变量解释、证据 ids、paper ids 和置信度。这样答案生成不是直接从一堆文本片段自由发挥，而是先形成可检查的结构化结论。

VerificationReport 是 grounding 校验结果。它用 status=pass|retry|clarify 表示当前 claim 是否足够可靠，missing_fields 表示缺什么，unsupported_claims 表示哪些结论没有证据支持，recommended_action 表示下一步应该 retry、澄清还是继续回答。

AssistantCitation 和 AssistantResponse 是 Agent 内部最终返回对象。AssistantResponse 里不只有 answer，还包括 citations、query_contract、research_plan_summary、runtime_summary、execution_steps、verification_report、needs_human 和澄清字段。API 层随后再把它包装成 AgentChatResponse 返回给前端。

6.8 真实流转案例

以下是 2026-05-02 的真实 DPO 公式查询 SSE 流式 trace，完整原始文件保存在 docs/dpo_real_trace_20260502.txt。请求：

{
  "query": "帮我看看 DPO 这篇论文的核心公式",
  "mode": "auto",
  "use_web_search": false,
  "max_web_results": 3,
  "session_id": "dpo-real-trace-20260502-010824"
}

本次流式响应共 60 个 SSE 事件，事件类型分布：answer_delta: 21, observation: 10, thinking_delta: 6, tool_call: 5, agent_step: 3, screened_papers: 2, evidence: 2, 以及 session, contract, agent_plan, plan, candidate_papers, solver_selection, claims, reflection, verification, confidence, final 各 1 个。

关键事件快照：

[event #1] session — 生成 session_id=dpo-real-trace-20260502-010824

[event #2] contract — LLMIntentRouter 输出的结构化意图：

{
  "clean_query": "帮我看看 DPO 这篇论文的核心公式",
  "interaction_mode": "research",
  "relation": "formula_lookup",
  "targets": ["DPO", "Direct Preference Optimization"],
  "answer_slots": ["formula"],
  "requested_fields": ["formula", "variable_explanation", "source"],
  "required_modalities": ["page_text", "table"],
  "answer_shape": "bullets",
  "precision_requirement": "exact",
  "continuation_mode": "fresh",
  "allow_web_search": false,
  "notes": ["structured_intent", "llm_tool_router", "intent_confidence=0.90",
            "router_action=need_corpus_search", "router_confidence=0.90", ...]
}

[event #3] agent_plan — AgentPlanner 的初始计划：

{
  "thought": "Use tools through the agent loop, observe the result, then compose or ask for clarification.",
  "actions": ["search_corpus"],
  "tool_call_args": [{"name": "search_corpus", "args": {"query": "DPO Direct Preference Optimization core formula...", "scope": "auto", "top_k": 8}}]
}

[event #4] plan — ResearchPlan：

{"paper_recall_mode": "anchor_first", "paper_limit": 6, "evidence_limit": 24,
 "solver_sequence": ["formula_solver"], "required_claims": ["formula", "variable_explanation"], "retry_budget": 1}

[tool loop] 执行序列共 15 个 execution steps：

query_contract_extractor → formula_lookup
agent_planner → search_corpus
agent_tool:build_research_plan → formula_solver（内置工具，不暴露给 LLM planner）
agent_loop → search_corpus
agent_tool:search_corpus → candidates=6, selected=1
agent_tool:search_corpus → evidence=6（第一轮证据块）
agent_tool:search_corpus → papers=1, evidence=6（筛选后）
agent_tool:read_memory → turns=0（检查会话历史）
agent_tool:compose → options=4, judge=auto_resolve, confidence=0.95
agent_tool:compose → claim_solver=deterministic
agent_tool:compose → claims=1
agent_tool:verify_claim → pass
agent_tool:compose → pass
agent_reflection → pass
agent_tool:verify_claim → pass

[LLM-judge 消歧] 第 9 步 observation 事件中的真实决策：

{
  "tool": "compose",
  "summary": "options=4, judge=auto_resolve, confidence=0.95",
  "payload": {
    "judge_decision": {
      "decision": "auto_resolve",
      "selected_option_id": "acronym-meaning-dpo-...",
      "selected_paper_id": "S6H9FE28",
      "confidence": 0.95,
      "reason": "The query explicitly asks for the core formula of 'DPO,' and the candidate titled 'Direct Preference Optimization: Your Language Model is Secretly a Reward Model' directly defines and originates the concept of DPO."
    }
  }
}

[event #60] final — 最终答案：

interaction_mode: research
answer: 574 字符，含 LaTeX 公式 $$\mathcal{L}{\mathrm{DPO}} = -\log \sigma\left( \beta \log \frac{\pi{\theta}(y_w|x)}{\pi_{\mathrm{ref}}(y_w|x)} - \beta \log \frac{\pi_{\theta}(y_l|x)}{\pi_{\mathrm{ref}}(y_l|x)} \right)$$ 及变量解释
citations: 2 条（均来自 paper S6H9FE28，page 4）
verification_report.status: pass
needs_human: false
claim_sources: {"deterministic_formula_solver": 1}

本次 trace 反映的链路口径：Intent Router（tool-calling LLM）→ Contract → Agent Plan（LLM planner）→ Research Plan（内置 resolver）→ Tool Loop（search_corpus → read_memory → compose/消歧 → compose/solver → verify_claim → reflection）→ Final。相比旧版，新 trace 新增了 solver_selection、confidence、reflection、thinking_delta、agent_step 事件类型，工具验证使用 verify_claim 替代了旧版 verify_grounding，增加了 read_memory 工具在检索前检查会话历史。

7. 服务层拆解

服务层是整个项目最容易被深入追问的部分，因为它决定了这个系统是不是只是在“套一个聊天壳”，还是确实把论文库读取、PDF 抽取、索引构建、向量嵌入、混合检索、会话记忆和模型调用这些底层能力设计清楚了。API 层只是入口，Agent 层负责调度，真正支撑论文问答质量和效率的是服务层。

从职责上看，服务层可以分成三条主线。第一条是离线入库链路：ZoteroSQLiteReader 读取 Zotero 元信息，PDFExtractor 抽取 PDF 页面文本、表格、图像和图注，IngestionService 生成 paper docs 和 block docs，并写入 JSONL 与 Milvus。第二条是在线检索链路：DualIndexRetriever 加载本地 paper/block 文档，使用 Milvus Dense 检索为主（BM25/Title Anchor 可选），先找候选论文，再找证据块。第三条是运行支撑链路：SessionStore 负责多轮会话持久化，ModelClients 统一封装 LLM/VLM/Embedding 调用，WebSearch 在本地语料不足时提供外部补充。

7.0 服务层设计总览

这个项目的核心嵌入结构不是“把所有 PDF 切块后一起扔进向量库”，而是采用 paper index 和 block index 两级索引。paper index 面向论文级召回，保存的是 paper card，里面包含 title、aliases、authors、year、tags、abstract_or_summary 和 top_evidence_hints；block index 面向证据级召回，保存的是从 PDF 中抽出来的 page_text、table、figure、caption 等块，并保留 page、block_type、caption、bbox、formula_hint、paper_id、doc_id 等 metadata。

这样设计是为了解决普通 PDF RAG 的两个问题。第一，如果直接在所有 PDF chunks 里检索，召回空间太大，噪声高，容易找到同名概念但不是目标论文的片段。第二，如果只做论文级检索，虽然能找到论文，但回答公式、指标、图表、实验结果时没有足够细的证据。两级索引的思路是先用 paper index 找“哪几篇论文可能相关”，再用 block index 在这些论文内部找“哪几个证据块可以支撑答案”。

检索效果上，系统默认使用 Milvus Dense 向量检索作为主召回路径。BM25 适合处理标题、缩写、公式 token、作者名、年份这类精确匹配，保留为可选模块（接入 jieba 中文分词后 Hit@1 从 0.176 恢复到 0.748）。对于 DPO、PPO、PBA 这类缩写和公式问题，系统还会利用 title anchor、relation anchor、formula token weights、target terms、block_type 和 formula_hint 做额外加权，避免向量相似度把语义相关但不是目标论文的内容排到前面。

其中 relation anchor 是最近从 stub 补完为完整实现的四路之一。它的设计思路是：如果用户明确提到了某个概念/方法名，那与已匹配论文共享标签、缩写词、作者或 Zotero 分类的其他论文也很可能相关——即使这些论文的标题里不含 query term。实现上，先由 title_anchor 确定锚点论文并提取其"关系指纹"（tags、aliases、body_acronyms、authors、collection paths），再遍历全库论文按共享信号数量打分排序。Zotero 分类路径从 SQLite 的 collections/collectionItems 表实时加载，缓存为内存字典；若 DB 不可用则自动降级，跳过 collection 信号。

检索效率上，系统把重活尽量放在离线入库阶段。PDF 抽取、文本切块、summary 生成、embedding upsert 都在 ingest rebuild 时完成；在线请求只加载已经持久化的 papers.jsonl、blocks.jsonl 和 Milvus collection。DualIndexRetriever 被依赖注入缓存成长期对象，启动后构建 BM25，后续请求复用；重建索引后再调用 refresh() 重新加载本地 JSONL 和 BM25。向量入库使用 batch upsert、retry 和 fallback embedding model，避免一次失败导致整个入库不可用。

7.1 Zotero 读取

Zotero 论文库的元信息全部来自 Zotero 本地的 zotero.sqlite 数据库。ZoteroSQLiteReader（app/services/library/zotero_sqlite.py）是这个数据的唯一入口，负责读取论文记录、解析附件路径、构建 paper card 所需的 title/author/year/tags/abstract/collection 等字段。

核心读取方法是 read_records()，它会查询 Zotero SQLite 中的 items、collections、creators、itemAttachments、itemNotes 等表，按 itemType 筛选出期刊论文、会议论文、学位论文、书籍章节等类型，并组装成 PaperRecord 数据结构：

class PaperRecord:
    parent_item_id: int
    attachment_item_id: int
    attachment_key: str       # Zotero attachment key，用作 paper_id
    item_type: str            # 如 "journalArticle", "conferencePaper"
    title: str
    authors: list[str]
    year: str
    tags: list[str]
    abstract_note: str
    source_url: str
    website_title: str
    file_path: str            # 解析后的本地 PDF 绝对路径
    file_exists: bool         # PDF 是否实际存在

附件的 PDF 路径解析是 reader 的核心——通过 ATTACHMENT_SQL 查询 itemAttachments 表，利用 parentItemID 关联父条目、contentType='application/pdf' 过滤 PDF 文件：

ATTACHMENT_SQL = """
SELECT
    ia.parentItemID AS parent_item_id,
    ia.itemID AS attachment_item_id,
    ia.path AS attachment_path,
    ia.contentType AS content_type,
    parent.key AS parent_key,
    attachment.key AS attachment_key,
    parent_type.typeName AS parent_item_type
FROM itemAttachments ia
JOIN items parent ON parent.itemID = ia.parentItemID
JOIN items attachment ON attachment.itemID = ia.itemID
JOIN itemTypes parent_type ON parent_type.itemTypeID = parent.itemTypeID
WHERE ia.parentItemID IS NOT NULL
  AND ia.path IS NOT NULL
  AND lower(ia.contentType) = 'application/pdf'
ORDER BY ia.parentItemID
"""

Zotero SQLite 的 schema 中，items 和 collections 通过 collectionItems 做多对多映射，creators 通过 itemCreators 关联（creatorData 和 creators 表有两个查询路径），附件通过 itemAttachments.parentItemID 关联到父条目的 itemID（注意 Zotero 用 itemID 而非 id）。ZoteroSQLiteReader 封装了这些查询细节，上层模块不需要直接写 SQL。

read_attachment_collection_paths() 方法专门为前端侧栏服务，返回 {attachment_key: [collection_path, ...]} 映射，在 LibraryBrowserService.list_library() 中被用来按 collection 分组展示论文库。

7.2 PDF 抽取

PDF 抽取由 PDFExtractor（app/services/retrieval/pdf_extractor.py）完成。它基于 pypdf 提取页面文本，并通过启发式信号识别页面中的表格、图表、扫描页等特殊区域。

核心数据结构是三个 dataclass：

TABLE_LIKE_THRESHOLD = 2.5
FIGURE_LIKE_THRESHOLD = 2.5
SCANNED_LIKE_THRESHOLD = 2.0
MAX_HI_RES_PAGES_PER_DOC = 6

@dataclass(slots=True)
class PageSignals:
    caption_anchor_count: int = 0        # "Table 1", "Fig. 2", "表 1", "图 2"
    table_anchor_count: int = 0
    figure_anchor_count: int = 0
    numeric_density: float = 0.0         # 数值 token 占比
    short_line_ratio: float = 0.0        # 短行比例
    avg_tokens_per_line: float = 0.0
    separator_pattern_score: float = 0.0 # 表格分隔符模式
    text_chars: int = 0
    image_object_count: int = 0
    table_like_score: float = 0.0
    figure_like_score: float = 0.0
    scanned_like_score: float = 0.0
    selected_reasons: tuple[str, ...] = ()

@dataclass(slots=True)
class ExtractedBlock:
    page: int
    block_type: str          # "page_text", "table", "figure", "caption"
    text: str
    bbox: tuple[float, float, float, float] | None = None
    caption: str = ""
    source_parser: str = "hi_res"

@dataclass(slots=True)
class ExtractedPage:
    page: int
    text: str
    blocks: list[ExtractedBlock] = field(default_factory=list)
    signals: PageSignals = field(default_factory=PageSignals)
    selected_for_hi_res: bool = False

抽取流程分两步：先用 pypdf.PdfReader 逐页提取文本并计算 PageSignals，再用这些信号分类每个页面。PDFExtractor.extract_pages() 的主流程：

def extract_pages(self, pdf_path: Path) -> list[ExtractedPage]:
    reader = PdfReader(str(pdf_path))
    pages = self._extract_pages_with_pypdf(reader)          # Step 1: 文本 + 信号
    selected_pages = self._select_hi_res_pages(pages)        # 选出前 N 页做高分辨率
    if selected_pages and self.prefer_unstructured:
        hi_res_blocks = self._extract_selected_hi_res_blocks(pdf_path, reader, selected_pages)
        for page in pages:                                   # Step 2: 合并 hi_res 块
            page.selected_for_hi_res = page.page in selected_pages
            page.blocks = hi_res_blocks.get(page.page, [])
    return pages

_select_hi_res_pages() 根据 PageSignals 的 table_like_score、figure_like_score 决定哪些页面值得做高分辨率抽取，最多选 MAX_HI_RES_PAGES_PER_DOC = 6 页。对于扫描版 PDF（scanned_like_score > 2.0），后续可通过 pdf_rendering.py 渲染为图片再由 VLM 理解。

7.3 Ingestion 入库

入库流程由 IngestionService（app/services/retrieval/indexing.py）统一编排。初始化时组装好 reader、extractor、splitter 三大组件：

class IngestionService:
    def __init__(self, settings: Settings, clients: ModelClients | None = None) -> None:
        self.settings = settings
        self.clients = clients or ModelClients(settings)
        self.reader = ZoteroSQLiteReader(settings)
        self.extractor = PDFExtractor(settings=settings, prefer_unstructured=True)
        self.splitter = RecursiveCharacterTextSplitter(
            chunk_size=800,
            chunk_overlap=120,
            separators=["\n\n", "\n", "。", ". ", " ", ""],
        )

rebuild() 方法执行完整的离线入库链路：

def rebuild(self, *, max_papers=None, force_rebuild=True) -> IngestionStats:
    records = self.reader.read_records(max_papers=max_papers)
    stats = IngestionStats(paper_records=len(records))
    paper_docs, block_docs = [], []
    state: dict[str, Any] = {"papers": {}}

    for record in records:
        paper_id = record.attachment_key
        if not record.file_exists:
            stats.papers_missing_pdf += 1
            continue
        pages = self.extractor.extract_pages(Path(record.file_path))
        # 生成 paper card (含 LLM 摘要) 和 block documents
        paper_doc, generated = self._build_paper_card(record=record, pages=pages)
        paper_docs.append(paper_doc)
        block_docs.extend(self._build_block_documents(record=record, pages=pages))
        stats.papers_indexed += 1
        state["papers"][paper_id] = {...}

    # 持久化到 JSONL
    self._persist_jsonl(self.settings.paper_store_path, paper_docs)
    self._persist_jsonl(self.settings.block_store_path, block_docs)
    # 向量化写入 Milvus
    vectors_upserted = self._upsert_vectors(paper_docs, block_docs, force_rebuild)
    ...

入库的核心产出是两类 LangChain Document：

paper docs：论文级索引，page_content 含 title/abstract/summary，metadata 含 paper_id、doc_id、title、authors、year、tags、top_evidence_hints
block docs：证据级索引，来源是 ExtractedBlock，metadata 含 doc_id（SHA1 哈希）、paper_id、page、block_type、caption、bbox、formula_hint

FORMULA_HINT_RE 会对包含 π、β、sigma、loss、objective、reward 等 token 的页面标记 formula_hint，供检索加权使用。向量写入 Milvus 时先尝试 text-embedding-3-large，失败自动降级到 text-embedding-3-small，batch upsert 默认每批 128 条带重试（可通过 upsert_batch_size 配置）。

7.4 Retriever 双索引检索

DualIndexRetriever（app/services/retrieval/core.py）是在线检索的核心。初始化时加载本地 JSONL 并构建双路索引：

class DualIndexRetriever:
    def __init__(self, settings: Settings) -> None:
        self.settings = settings
        self._paper_docs: list[Document] = []
        self._block_docs: list[Document] = []
        self._load_library_docs()
        self._paper_bm25 = self._build_bm25(self._paper_docs, settings.paper_bm25_top_k)
        self._block_bm25 = self._build_bm25(self._block_docs, settings.block_bm25_top_k)
        self._paper_dense = CollectionVectorIndex(settings, collection_name=settings.milvus_paper_collection)
        self._block_dense = CollectionVectorIndex(settings, collection_name=settings.milvus_block_collection)

    def refresh(self) -> None:
        """ingest rebuild 后重新加载 JSONL 和重建 BM25，无需重启服务"""
        self._load_library_docs()
        self._paper_bm25 = self._build_bm25(self._paper_docs, self.settings.paper_bm25_top_k)
        self._block_bm25 = self._build_bm25(self._block_docs, self.settings.block_bm25_top_k)

论文级检索 search_papers() 的核心逻辑——多路加权融合：

def search_papers(self, *, query, contract, limit=None) -> list[CandidatePaper]:
    search_text = query.strip()
    target_terms = self._contract_target_terms(contract)
    # 用 targets 扩展检索词
    if target_text and target_text.lower() not in search_text.lower():
        search_text = f"{target_text} {search_text}".strip()

    weighted_docs: list[tuple[float, list[Document]]] = []
    # title anchor 精确匹配 (权重 1.6)
    anchors = self.title_anchor(target_terms)
    if anchors: weighted_docs.append((1.6, anchors))
    # relation anchor 关系锚定 (权重 1.3)
    relation_anchors = self.relation_anchor_docs(contract)
    if relation_anchors: weighted_docs.append((1.3, relation_anchors))
    # BM25 稀疏检索 (权重 0.9)
    if self._paper_bm25: weighted_docs.append((0.9, self._paper_bm25.invoke(search_text)))
    # Milvus dense 检索 (权重 0.8)
    dense_docs = self._paper_dense.search_documents(search_text, limit=...)
    if dense_docs: weighted_docs.append((0.8, dense_docs))
    # Weighted RRF 融合 + paper_match_boost 加权 → CandidatePaper 列表
    fused = self._rrf_fuse(weighted_docs)
    ...

四路召回最初设计为 Weighted RRF 多路融合（title anchor 1.6 / relation anchor 1.3 / BM25 0.9 / dense 0.8）。经过 159 题 × 12 配置消融实验，Pure Dense + paper_query_text QE 在所有条件下均最优（Hit@1=97.5%），多路融合不如 Dense 且慢 6 倍。当前默认使用 Dense-only 检索，BM25/Title Anchor/Relation Anchor 保留为可选模块。

relation_anchor_docs 的完整实现（core.py:690-770）：

def relation_anchor_docs(self, contract: QueryContract) -> list[Document]:
    target_terms = self._contract_target_terms(contract)
    if not target_terms:
        return []

    # 第一步：用 title_anchor 找出锚点论文
    anchors = self.title_anchor(target_terms)
    if not anchors:
        return []

    # 第二步：从锚点论文提取"关系指纹"
    anchor_tags: set[str] = set()
    anchor_acronyms: set[str] = set()
    anchor_authors: set[str] = set()
    anchor_collections: set[str] = set()
    anchor_ids: set[str] = set()

    for doc in anchors:
        meta = doc.metadata or {}
        anchor_ids.add(str(meta.get("paper_id", "")))
        # 标签（|| 分隔）
        for tag in str(meta.get("tags", "")).split("||"):
            tag = tag.strip().lower()
            if tag: anchor_tags.add(tag)
        # 缩写词（从 aliases 和 body_acronyms 提取）
        for field in ("aliases", "body_acronyms"):
            for item in str(meta.get(field, "")).split("||"):
                item = item.strip().lower()
                if item and len(item) >= 2:
                    anchor_acronyms.add(item)
        # 作者（逗号分隔）
        for author in str(meta.get("authors", "")).split(","):
            author = author.strip().lower()
            if author: anchor_authors.add(author)
        # Zotero 分类路径（从预加载的 _collection_paths 字典查询）
        paper_id = str(meta.get("paper_id", ""))
        for coll_path in self._collection_paths.get(paper_id, []):
            anchor_collections.add(coll_path.lower())

    # 第三步：遍历所有非锚点论文，按共享信号打分
    scored: list[tuple[float, Document]] = []
    for doc in self._paper_docs:
        meta = doc.metadata or {}
        paper_id = str(meta.get("paper_id", ""))
        if paper_id in anchor_ids:
            continue  # 跳过锚点本身（title anchor 已召回）

        score = 0.0
        # 共享标签：+1.8 / 个
        doc_tags = {t.strip().lower() for t in
                    str(meta.get("tags", "")).split("||") if t.strip()}
        shared_tags = anchor_tags & doc_tags
        if shared_tags: score += len(shared_tags) * 1.8
        # 共享缩写词：+1.0 / 个（上限 5 个，防止高频缩写词噪声）
        doc_acronyms: set[str] = set()
        for field in ("aliases", "body_acronyms"):
            for item in str(meta.get(field, "")).split("||"):
                item = item.strip().lower()
                if item and len(item) >= 2:
                    doc_acronyms.add(item)
        shared_acronyms = anchor_acronyms & doc_acronyms
        if shared_acronyms:
            score += min(len(shared_acronyms), 5) * 1.0
        # 共享作者：+1.2 / 个
        doc_authors = {a.strip().lower() for a in
                       str(meta.get("authors", "")).split(",") if a.strip()}
        shared_authors = anchor_authors & doc_authors
        if shared_authors: score += len(shared_authors) * 1.2
        # 共享 Zotero 分类路径：+2.5 / 个（最强信号）
        doc_collections = set()
        for coll_path in self._collection_paths.get(paper_id, []):
            doc_collections.add(coll_path.lower())
        shared_collections = anchor_collections & doc_collections
        if shared_collections:
            score += len(shared_collections) * 2.5

        if score > 0:
            meta["relation_score"] = score
            scored.append((score, doc))

    if not scored:
        return []
    scored.sort(key=lambda x: x[0], reverse=True)
    return [doc for _, doc in scored[:self.settings.paper_bm25_top_k]]

四个关系信号的权重设计依据：

信号	权重	数据来源	设计理由
Zotero 分类	2.5	`_collection_paths` 字典（检索器初始化时从 zotero.sqlite 加载）	用户手动整理的分类结构，同一分类的论文天然强相关
共享标签	1.8	paper_card metadata `tags` 字段	用户标记的结构化知识，置信度高
共享作者	1.2	paper_card metadata `authors` 字段	弱信号——同一作者可能跨领域发表
共享缩写词	1.0（≤5）	paper_card metadata `aliases` + `body_acronyms`	最弱信号——PPO/RLHF 等高频缩写词易引入噪声，加 5 个上限

Zotero 分类数据通过 _load_collections() 在 DualIndexRetriever.__init__ 时调用 ZoteroSQLiteReader.read_attachment_collection_paths() 加载，返回 dict[attachment_key, list[collection_path_string]]。若 Zotero SQLite 不可用（非本地环境），静默降级为空字典，collection 信号自动跳过，其余三个信号继续生效。

RETRIEVAL_MARKERS 字典定义了场景化检索标记：公式场景加重 "objective"、"formula"、"公式" 等词；机制场景加重 "workflow"、"mechanism" 等词。BOOK_ITEM_TYPES 和 BOOKISH_TITLE_MARKERS（"实战"、"教程"、"指南"等）用于识别和降权书籍类条目。

7.5 Milvus 向量索引

向量索引由 CollectionVectorIndex（app/services/retrieval/vector_index.py）封装，底层对接 Milvus（本地部署 http://localhost:19530）。系统维护两个 collection：zprag_papers 和 zprag_blocks。Embedding 使用独立的 embedding_api_key + embedding_base_url（fallback 到 openai_api_key），当前部署通过 Qihai 网关调用 text-embedding-3-large（3072 维），失败自动降级到 text-embedding-3-small（1536 维）。

配置项（app/core/config.py）：

milvus_uri: str = "http://localhost:19530"
milvus_paper_collection: str = "zprag_papers"
milvus_block_collection: str = "zprag_blocks"
embedding_model: str = "text-embedding-3-large"        # 3072 维
embedding_fallback_model: str = "text-embedding-3-small"  # 1536 维
embedding_request_timeout_seconds: float = 120.0
embedding_batch_retry_attempts: int = 3

向量生成通过 ModelClients 提供的 HTTP client 直接调用 embedding API，不走 LangChain 包装——以便精细控制 batch size、超时和重试。CollectionVectorIndex.upsert_documents() 分批写入（默认 batch_size=128），遇网络错误自动重试；search() 返回 top_k 结果含 id/score/metadata。

7.6 SessionStore

两个实现：InMemorySessionStore（测试/开发用 dict 存储）和 SQLiteSessionStore（生产用）。data/v4_sessions.sqlite3 存储 session 数据：

class SQLiteSessionStore:
    def __init__(self, db_path: str | Path, max_turns: int = 8) -> None:
        self.db_path = Path(db_path)
        self.max_turns = max(1, max_turns)
        self._lock = threading.RLock()
        self.db_path.parent.mkdir(parents=True, exist_ok=True)
        self._init_db()

    def get(self, session_id: str) -> SessionContext:
        with self._lock:
            row = conn.execute(
                "SELECT context_json FROM sessions WHERE session_id = ?", (session_id,)
            ).fetchone()
            if row is None:
                return SessionContext(session_id=session_id)  # 首次访问创建新上下文
            return SessionContext.model_validate_json(row["context_json"])

    def upsert(self, context: SessionContext) -> None:
        context = _trim_context_history(context, max_turns=self.max_turns)
        payload = context.model_dump_json()
        conn.execute(
            """INSERT INTO sessions(session_id, context_json, updated_at)
               VALUES(?, ?, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
               ON CONFLICT(session_id) DO UPDATE SET ...""",
            (context.session_id, payload),
        )

核心操作：get(session_id) → 获取/创建上下文；upsert(context) → 保存并裁剪历史；append_turn(session_id, turn) → 追加一轮对话。每次 upsert 时 _trim_context_history() 裁剪超过 max_turns 的旧轮次（构造函数默认 8，生产环境通过 deps.py 传入 agent_history_max_turns=24），压缩为摘要存入 summary 字段。序列化通过 Pydantic model_dump_json() / model_validate_json()。sync_active_research_compatibility() 负责 legacy 字段与新版 active_research 之间的兼容同步。

7.7 ModelClients

ModelClients（app/services/infra/model_clients.py）是项目中所有大模型调用的统一封装层。惰性初始化，只在首次访问时创建连接：

class ModelClients:
    def __init__(self, settings: Settings) -> None:
        self.settings = settings
        self._chat: ChatOpenAI | None = None
        self._vlm: ChatOpenAI | None = None
        self._http_client: httpx.Client | None = None
        self._async_http_client: httpx.AsyncClient | None = None

    @property
    def chat(self) -> ChatOpenAI | None:
        if not self.settings.openai_api_key: return None
        if self._chat is None:
            self._chat = ChatOpenAI(
                model=self.settings.chat_model,         # 当前部署: deepseek-v4-flash (默认: gpt-4o-mini)
                api_key=self.settings.openai_api_key,
                base_url=self.settings.openai_base_url,  # 当前: api.deepseek.com/v1
                temperature=0.1,
                max_tokens=self.settings.chat_max_tokens,  # 默认 1800
                http_client=self.http_client,
            )
        return self._chat

    @property
    def vlm(self) -> ChatOpenAI | None:
        if not self.settings.openai_api_key or not self.settings.enable_figure_vlm:
            return None
        if self._vlm is None:
            self._vlm = ChatOpenAI(
                model=self.settings.vlm_model,           # gpt-4.1-mini
                temperature=0.0,
                max_tokens=self.settings.chat_max_tokens,
                ...
            )
        return self._vlm

三个模型能力（均通过 OpenAI 兼容 API 调用，当前部署使用不同 provider）：

chat：意图识别、工具规划、claim 提取、验证、答案生成。当前部署 deepseek-v4-flash（配置项 chat_model，默认 gpt-4o-mini），temperature=0.1，max_tokens=1800
vlm：仅 enable_figure_vlm=True 时初始化，用于图表理解。当前部署 gpt-4.1-mini（配置项 vlm_model），temperature=0.0
embedding：通过 http_client / async_http_client 调用独立的 embedding API（embedding_api_key + embedding_base_url，fallback 到 openai_api_key）。当前部署 text-embedding-3-large（3072 维），通过 Qihai 网关

close() / aclose() 在 lifespan 关闭阶段释放连接池。invoke_json_messages() 和 invoke_tool_plan_messages() 封装了"发送 → 解析 JSON → fallback"流程，遇解析失败返回 fallback 而非抛异常。

7.8 WebSearch

Web Search 由 TavilyWebSearchClient（app/services/retrieval/web_search.py）提供，对接 Tavily Search API。它的 search() 方法接受 query、max_results、search_depth 等参数，返回带标题、URL、摘要和原始内容的搜索结果列表。

在 Agent 主链路中，Web Search 不是默认开启的——用户需要在前端勾选"使用 Web 搜索"或请求中包含 use_web_search=true。当本地语料检索后证据不足时，Agent 会自动判断是否需要补充 Web 证据，调用 web_search 工具获取外部信息，再经过 build_web_research_claim() 把网页内容转化为与本地证据格式兼容的 claim。

collect_web_evidence() 函数负责完整的 Web 证据收集流程：搜索 → 获取页面内容 → 提取相关片段 → 生成带引用的 claim。Web 证据的引用格式与本地 PDF 证据统一，但在 citation 中会标记 source_type=web，前端展示时能区分来源是本论文库还是外部网页。

7.9 意图识别（intents/）

intents/ 子包（10 模块）负责将用户自然语言问题转化为结构化意图，是整个 Agent 链路的入口认知层。

核心是 LLMIntentRouter（router.py），使用 tool-calling 模式而非传统文本分类——向 Chat Model 提供 5 个 tool choice，让模型根据语义选择最合适的动作：

RouterAction = Literal["answer_directly", "need_conversation_tool",
                       "need_corpus_search", "need_web", "need_clarify"]

路由输出不是只有动作标签，而是包含 relation（20+ 种：formula_lookup、paper_summary_results、entity_definition、metric_value_lookup、origin_lookup 等）、targets、requested_fields、confidence、continuation_mode 的完整结构。

各模块按问题类型分工：

research.py — 研究类问题的 answer slot 推断（research_answer_slots()）
conversation.py — 对话类意图（library_status, library_recommendation, memory_followup 等）
library.py — 论文库查询意图
figure.py — 图表类意图信号检测（figure_signal_score()）
followup.py / followup_relationship.py — 追问意图与关系判断
memory.py — 记忆类意图
contract_adapter.py — 在 answer_slots 和 research relation/requirements 之间做双向转换
marker_matching.py — MarkerProfile 机制，用关键词配置文件匹配用户问题特征

配置文件 intent_marker_profiles.json 定义了各类问题的标记词（如 DPO、PPO、PBA 等缩写属于 acronym 类 marker）。

7.10 规划与合约（planning/ + contracts/）

planning/（7 模块） 负责将意图转化为可执行的研究计划：

research.py — build_research_plan()：从 QueryContract 生成 ResearchPlan（召回模式、evidence 数量、solver 顺序）
query_shaping.py — query_target_candidates()：从用户问题中提取目标实体和论文缩写
query_rewrite.py — rewrite_query()：多查询改写（multi_query / hyde / step_back），为检索生成多个角度的查询
solver_dispatch.py / solver_goals.py — 决定哪些 solver 需要执行，以及各自的目标
compound_tasks.py — 复合查询分解与合并
schema_claims.py — 判断是否应该使用 schema-based claim solver

contracts/（8 模块） 负责管理会话级别的上下文和约束：

session_context.py — agent_session_conversation_context()：构建 LLM 调用上下文（含历史轮次压缩、active research context 等）
normalization.py — normalize_contract_targets()：规范化 targets（别名、缩写、大小写统一）
contextual_resolver.py — 根据会话上下文消解实体引用（"它的实验结果" → 指上一轮那篇论文）
contextual_helpers.py — 上下文辅助函数
conversation_memory.py — 跨轮次 memory bindings（active_memory_bindings()）
conversation_helpers.py — 对话状态辅助
followup_relationship.py — 追问关系继承和纠正检测
context.py — contract_has_note()、contract_notes() 等辅助

7.11 Claim 求解与验证（claims/）

claims/ 是最大的领域子包（23 模块），负责三类核心工作：求解（从 evidence 生成 claim）、验证（grounding 校验）、辅助（文本/公式/图表处理）。

求解器入口 solver_pipeline.py：

def run_claim_solver_pipeline(*, schema_allowed, generic_enabled, shadow_enabled,
                               solve_schema, solve_deterministic) -> ClaimSolverPipelineResult:

三路径策略：schema solver 可用且产出非空 → 直接用；否则走 deterministic solver；shadow mode 启用时两者并行运行并比较。

13 个 deterministic solver（_DETERMINISTIC_SOLVER_REGISTRY）： origin_lookup, formula（公式提取+变量解释）, followup_research, figure（VLM 图表理解）, table, metric_context, paper_recommendation, topology_recommendation, topology_discovery, paper_summary_results, default_text, entity_definition, concept_definition

验证器：verifier_pipeline.py 编排验证流程；type_verifiers.py 按 claim 类型做确定性校验；llm_verifier.py 处理复杂语义判断。deterministic_runner.py 和 deterministic_solver.py 提供 solver 执行基础设施。

辅助模块：formula_text.py（公式 token 提取与加权）、metric_text.py（指标数值提取）、visual_helpers.py（图像/图表信号）、paper_helpers.py / paper_summary.py（论文元信息）、origin_selection.py（起源论文选择）、followup_helpers.py（追问处理）、generic_solver.py（通用 schema solver）。

7.12 答案组合与实体（answers/ + entities/ + followup/ + clarification/）

这四个子包负责将 claim 转化为最终回答：

answers/（10 模块）：AnswerComposerMixin 调用各 answer composer。evidence_presentation.py 构建引用格式（citations_from_doc_ids()、build_figure_contexts()）。citation_whitelist.py 提供回答引用白名单后置过滤（P0-1 安全加固）。entity.py / formula.py / paper.py / followup.py / topology.py / library_recommendations.py / memory_followup.py 各处理一种 answer 类型。conversation_state.py 管理对话回答状态。
entities/（4 模块）：实体定义相关。definition_helpers.py 提供实体定义求解辅助；definition_profiles.py 定义实体 marker profile；supporting_paper_selector.py 选择支撑论文；type_inference.py 推断实体类型。
followup/（2 模块）：candidates.py 生成追问候选；relationship_memory.py 管理追问关系记忆。
clarification/（3 模块）：intents.py 处理澄清意图（contract_from_selected_clarification_option()、clarification_options_from_contract_notes()）；questions.py 构建澄清问题（build_agent_clarification_question()）；limit_runtime.py 限制澄清次数（force_best_effort_after_clarification_limit()）。

7.13 Agent Mixin 架构（agent_mixins/）

agent_mixins/（6 模块）是 Agent 架构的核心创新——将正交能力通过 Mixin 模式注入 ResearchAssistantAgent：

class ResearchAssistantAgentV4(
    FollowupRoutingMixin,     # 追问路由：is_negative_correction_query, inherit_followup_relationship
    AnswerComposerMixin,      # 答案组合：compose_formula_answer, compose_paper_summary_results_answer 等
    EntityDefinitionMixin,    # 实体定义：消歧 + 定义提取
    SolverPipelineMixin,      # Claim 求解：_run_solvers → run_claim_solver_pipeline
    ClaimVerifierMixin,       # Grounding 校验：_verify_claims, _verify_claims_with_schema
):

这种设计让每个 Mixin 只关注自己的领域，不互相污染。concept_reasoning.py 是预留的概念推理 Mixin（未注入类继承）。

7.14 动态工具系统（tools/）

tools/（3 模块）支持在不修改核心代码的情况下扩展 Agent 能力：

proposals.py — 工具提案管理：list_tool_proposals()、load_tool_proposal()、run_tool_proposal_sandbox()、transition_tool_proposal_status()。生命周期：draft → sandboxed → active → deprecated
registry_helpers.py — 700+ 行的工具注册基础设施，为 tool_registries.py 提供 handler 辅助函数
dynamic_context.py — 动态工具上下文管理

工具提案的 JSON manifest 包含 name、when、returns、input_schema、dangerous、streaming 等字段，与内置 AgentToolSpec 格式兼容，由 agent_tool_manifest() 合并后统一呈现给 LLM planner。

8. Agent 主链路

Agent 主链路是整个系统最核心的运行时流程。从用户输入到最终答案，数据依次经过意图路由（Intent Router）、合约提取（Contract Extraction）、工具规划（Agent Planner）、工具执行（Agent Runtime / Tool Loop）、claim 求解（Solver Pipeline）、grounding 验证（Claim Verifier）和答案组合（Answer Composer）七个阶段。每个阶段都有明确的输入输出协议，阶段之间通过 QueryContract、ResearchPlan、EvidenceBlock、Claim、VerificationReport 等 domain model 传递状态。

整个链路的入口是 run_agent_chat_turn()（app/services/agent/chat_runtime.py），它创建 AgentRunContext，先尝试 compound query（复合查询分解），再走 run_standard_turn() 标准流程。标准流程又细分为：extract_agent_query_contract() 提取合约 → planner 生成 plan → runtime 执行 tool loop → solver 生成 claim → verifier 校验 → composer 组合答案 → finish_agent_turn() 写入 trace。

8.1 意图路由：LLMIntentRouter

意图路由是整个链路的入口，由 LLMIntentRouter（app/services/intents/router.py）负责。核心创新：用 tool-calling 模式代替传统文本分类。Chat Model 从五个 tool choice 中选择最合适的一个：

ROUTER_TOOLS: list[dict[str, Any]] = [
    {"name": "answer_directly",        # 寒暄、自我介绍——不需要论文语料
     "description": "Use when the answer does not need local PDF/web evidence.",
     "input_schema": {"properties": {"rationale": ..., "confidence": ..., "answer_style": ...}}},
    {"name": "need_conversation_tool",  # 论文库状态、推荐、引用排名、记忆追问
     "input_schema": {"properties": {"relation": ..., "targets": ..., "requested_fields": ...}}},
    {"name": "need_corpus_search",      # 需要本地 PDF 语料检索——多数研究问题的入口
     "input_schema": {"properties": {"relation": ..., "targets": ..., "requested_fields": ...}}},
    {"name": "need_web",                # 外部 Web 搜索（需用户显式开启）
     "input_schema": {...}},
    {"name": "need_clarify",            # 问题不明确或存在歧义
     "input_schema": {...}},
]

路由时模型同时输出 relation（20+ 种：formula_lookup、paper_summary_results、entity_definition、metric_value_lookup 等）、targets、requested_fields、confidence、continuation_mode（fresh/followup/context_switch）。路由结果通过 query_contract_from_router_decision() 转化为初始 QueryContract，再由 extract_agent_query_contract() 做规范化——包括继承 followup 上下文、应用 conversation memory、处理 pending clarification、normalize targets 等后续加工。

LLMIntentRouter.route() 接收会话 context（active_research、历史 turns、working_memory、persistent_learnings），判断跟进/纠正/切换关系。confidence 低于 confidence_floor（默认 0.6）时走 fallback。

8.2 AgentPlanner

AgentPlanner（app/services/agent/planner.py）负责把 QueryContract 转化为可执行的工具计划：

class AgentPlanner:
    def __init__(self, *, clients, conversation_context, conversation_messages,
                 is_negative_correction_query, confidence_floor=0.6,
                 dynamic_tool_manifest=None) -> None:
        ...

    def tool_manifest(self) -> list[dict[str, Any]]:
        """合并内置 + 动态工具的完整清单，去重后返回给 LLM"""
        manifest = []
        seen = set()
        for tool in [*agent_tool_manifest(), *list(self.dynamic_tool_manifest() or [])]:
            name = str(tool.get("name") or "").strip()
            if name and name not in seen:
                seen.add(name)
                manifest.append(dict(tool))
        return manifest

    def plan_actions(self, *, contract, session, use_web_search) -> dict[str, Any]:
        """生成初始工具序列"""
        fallback = fallback_plan(contract=contract, ...)
        if self.clients.chat is None: return fallback
        # 先尝试 tool-calling planner
        tool_plan = self.plan_with_tool_calls(contract, session, use_web_search)
        normalized = normalize_plan_payload(tool_plan, fallback, self.tool_names())
        if normalized is not None:
            return defer_premature_research_clarification(contract, normalized, fallback)
        # 失败则走 JSON planner
        payload = self.clients.invoke_json_messages(
            system_prompt=json_planner_system_prompt(context_payload),
            messages=planner_messages_with_user(...),
            fallback=fallback,
        )
        return normalize_plan_payload(payload, fallback, self.tool_names()) or fallback

核心方法：

plan_actions()：生成初始工具序列。先尝试 tool-calling planner，失败则降级到 JSON planner，最终兜底用 fallback_plan()
next_action()：tool loop 每步调用，根据已执行的 actions 和当前状态决定下一步
tool_manifest()：合并 20 个内置 AgentToolSpec + 动态 JSON manifest 工具

防呆逻辑：defer_premature_research_clarification() 避免检索前过早澄清；fallback_plan() 在模型规划失败时提供安全默认序列（conversation → ["compose"]，research → ["search_corpus", "compose"]）。

8.3 AgentRuntime 与 Tool Loop

AgentRuntime（app/services/agent/runtime.py）是工具执行调度器。区分两条路径，但共享同一套 execute_tool_loop() 机制。

Conversation 路径 — execute_conversation_tools()：

def execute_conversation_tools(self, *, contract, query, session, agent_plan,
                                max_web_results, emit, execution_steps) -> dict[str, Any]:
    actions = conversation_runtime_actions(contract=contract, agent_plan=agent_plan, ...)
    state = conversation_runtime_state(contract=contract, agent_plan=agent_plan)
    record_tool_loop_ready(emit=emit, tool="compose", actions=actions, ...)

    tools = build_conversation_tool_registry(agent=self.agent, state=state, ...)
    executor = AgentToolExecutor(tools)
    execute_tool_loop(
        agent=self.agent, executor=executor,
        planned_actions=actions,
        stop_condition=lambda executed: bool(state.get("answer")),
        ...
    )
    if not state.get("answer"):
        executor.run("compose")       # loop 未产出答案时兜底调用 compose
    return state

Research 路径 — run_research_agent_loop()：

def run_research_agent_loop(self, *, contract, session, agent_plan, web_enabled, ...) -> dict[str, Any]:
    plan = build_research_plan(contract=contract, settings=self.agent.settings)
    state = research_runtime_state(contract=contract, plan=plan, ...)
    emit("plan", plan.model_dump())   # 发出 ResearchPlan 事件
    execution_steps.append({"node": "agent_tool:build_research_plan", "summary": ",".join(plan.solver_sequence)})

    actions = research_runtime_actions(contract=contract, agent_plan=agent_plan, web_enabled=web_enabled)
    record_tool_loop_ready(emit=emit, tool=tool_loop_ready_tool(actions), actions=actions, ...)

    tools = build_research_tool_registry(agent=self.agent, state=state, session=session, ...)
    executor = AgentToolExecutor(tools)
    execute_tool_loop(
        agent=self.agent, executor=executor,
        planned_actions=actions,
        stop_condition=lambda executed: (
            isinstance(state.get("verification"), VerificationReport)
            and state["verification"].status in {"pass", "clarify"}
        ),
        ...
    )
    if state["verification"] is None and not state.get("answer"):
        executor.run("compose")       # verification 未生成时兜底
    finalize_research_runtime(agent=self.agent, state=state, emit=emit, ...)
    return state

两条路径的 key difference：

Conversation 的 stop_condition：state["answer"] 非空即停
Research 的 stop_condition：verification.status 为 pass 或 clarify 才停
Research 多了 build_research_plan 步（内置非 LLM 可见工具），产出 solver_sequence
Conversation 注册了 query_library_metadata（直接 SQL 查论文库），Research 没有

Tool loop 运作方式：planner 决定 next action → executor 调用对应 handler → handler 通过 emit 产出事件 → 检查 stop_condition → 继续或终止。默认 max_agent_steps=8、retry_budget=1 防止无限循环。

8.4 Tool Registry 与 AgentToolExecutor

工具系统三层结构（app/services/agent/tools.py）：

@dataclass(frozen=True, slots=True)
class AgentToolSpec:
    """LLM 可见的工具声明（20 个内置 + 动态）"""
    name: str
    when: str                      # 使用场景描述
    returns: str                   # 返回内容描述
    input_schema: dict[str, Any]   # 参数 JSON Schema
    research_executable: bool = False
    conversation_executable: bool = False
    dangerous: bool = False
    streaming: bool = False

@dataclass(frozen=True, slots=True)
class RegisteredAgentTool:
    """Runtime 注册的可执行工具"""
    name: str
    handler: Callable              # 实际执行函数
    requires: tuple[str, ...] = () # 前置依赖工具
    terminal: bool = False         # 是否终止 loop
    accepts_arguments: bool = False
    streaming: bool = False

class AgentToolExecutor:
    """工具执行器：注册 → 依赖解析 → 执行 → 去重"""
    def __init__(self, tools: dict[str, RegisteredAgentTool]): ...
    def run(self, action, *, arguments=None, argument_provider=None, emit=None) -> bool:
        """执行工具。先解析 requires 依赖，再调用 handler，返回是否 terminal"""
    def run_parallel(self, actions, *, arguments=None, max_workers=4, emit=None) -> bool:
        """并行执行多个独立工具"""

执行时 AgentToolExecutor.run() 自动：

解析 requires 依赖链（依赖未执行则先执行依赖）
按 (tool.name, arguments_fingerprint) 去重
emit thinking_delta 事件（"调用 search_corpus(query=..., scope=auto)..."）
通过 begin_tool_execution() / end_tool_execution() 记录耗时和 metrics
terminal 工具（compose、ask_human）返回 True 触发 loop 终止检查

工具注册表分别由 build_conversation_tool_registry() (12 工具) 和 build_research_tool_registry() (18 工具) 在 tool_registries.py 中构建，两者都通过 _add_dynamic_tools() 注入动态工具。

8.5 Search Corpus 检索执行

search_corpus 是 research 路径最核心的工具，在 tool loop 中被多次调用。research_search_handlers.py 中的 search_corpus() handler：

def search_corpus(arguments=None) -> None:
    request_input = planned_input("search_corpus", arguments)
    strategy = search_corpus_strategy(request_input)  # 解析 strategy 参数
    # 如果指定了原子检索策略，直接委托
    if strategy in {"bm25", "vector", "hybrid"}:
        run_atomic_search(f"{strategy}_search", request_input)
        return
    # 否则走两阶段：先找候选论文，再找证据块
    if not state.get("screened_papers"):
        search_papers(request_input)       # → agent_search_papers() → DualIndexRetriever.search_papers()
    if not state.get("evidence"):
        search_evidence(request_input)     # → agent_search_evidence() → DualIndexRetriever.search_blocks()
    summary, payload = search_corpus_observation_payload(state)
    record_observation(tool="search_corpus", summary=summary, payload=payload)

agent_search_papers() 调用 DualIndexRetriever.search_papers() → 产出 candidate_papers → screen_agent_papers() 筛选 → screened_papers 事件。agent_search_evidence() 调用 search_blocks() → evidence 事件。

消歧发生在后续的 agent_solve_claims()（compose handler 中）：先通过 disambiguation_options_from_evidence() 生成歧义选项，再由 judge_disambiguation_options() 调用 LLM-judge，高置信度（≥0.85）时自动绑定，低置信度时标记 judge_recommended 或进入人工澄清。

8.6 Claim Solver：SolverPipelineMixin

SolverPipelineMixin._run_solvers() 将 evidence 转化为结构化 Claim。核心执行流程：

class SolverPipelineMixin:
    def _run_solvers(self, *, contract, plan, papers, evidence, session) -> list[Claim]:
        schema_allowed = should_use_schema_claim_solver(contract=contract, plan=plan, ...)
        result = run_claim_solver_pipeline(
            schema_allowed=schema_allowed,
            generic_enabled=...,       # 是否启用通用 schema solver
            shadow_enabled=...,        # 是否启用 shadow mode（双跑对比）
            solve_schema=lambda: self._run_schema_claim_solver(...),
            solve_deterministic=lambda: self._run_deterministic_claim_solver(...),
        )
        return result.claims

_DETERMINISTIC_SOLVER_REGISTRY 注册了 13 种 solver：

_DETERMINISTIC_SOLVER_REGISTRY = {
    "origin_lookup":          solve_origin_lookup_claims,       # 概念起源论文
    "formula":                solve_formula_claims,             # 公式 + 变量提取
    "followup_research":      solve_followup_research_claims,   # 多轮追问
    "figure":                 solve_figure_claims,              # 图表理解 (VLM)
    "table":                  solve_table_claims,               # 表格解析
    "metric_context":         solve_metric_context_claims,      # 指标数值提取
    "paper_recommendation":   solve_paper_recommendation_claims,
    "topology_recommendation": solve_topology_recommendation_claims,
    "topology_discovery":     solve_topology_discovery_claims,
    "paper_summary_results":  solve_paper_summary_results_claims,
    "default_text":           solve_default_text_claims,
    "entity_definition":      solve_entity_definition_claims,
    "concept_definition":     solve_concept_definition_claims,
}

run_claim_solver_pipeline() 执行策略：schema solver 可用且产出非空 → 直接用 schema 结果；否则走 deterministic solver。shadow mode 启用时两者并行运行，比较结果写入 _last_generic_claim_solver_shadow 供 runtime_summary 展示。

每个 solver 接收 (contract, plan, papers, evidence, ...) → 返回 list[Claim]。例如 DPO 公式查询中，formula_solver 从 evidence 提取 L_DPO 公式、β 参数、π_θ 策略定义等结构化 claim。

8.7 Claim Verifier：ClaimVerifierMixin

ClaimVerifierMixin._verify_claims() 实现三层验证：

def _verify_claims(self, *, contract, plan, claims, papers, evidence) -> VerificationReport:
    if not claims:
        return VerificationReport(status="retry", missing_fields=plan.required_claims,
                                  recommended_action="expand_recall")
    # ── 第一层：Deterministic 证据 ID 审计 ──
    # 检查 claim 引用的 evidence_ids 是否真实存在于当前 evidence 列表中
    # 引用了不存在 doc_id 的 claim → unsupported（可能是 LLM 幻觉）
    real_doc_ids = {e.doc_id for e in evidence} | {p.paper_id for p in papers}
    orphan_claims = [c for c in claims if c.evidence_ids and not (c.evidence_ids & real_doc_ids)]
    if orphan_claims:
        return VerificationReport(status="clarify", unsupported_claims=orphan_claims, ...)

    # ── 第二层：Schema / Type-specific 验证 ──
    schema_report = self._verify_claims_with_schema(contract, plan, claims, papers, evidence)
    if schema_report is not None:
        return schema_report

    # ── 第三层：Generic fallback 验证 ──
    report = self._verify_claims_with_generic_fallback(contract, plan, claims, papers, evidence)
    return report or VerificationReport(status="pass")

第二层 type-specific 验证器（app/services/claims/type_verifiers.py）按 relation 分发：

verify_formula_lookup_claims()：检查公式是否含数学表达式 + 变量解释 + 匹配目标
verify_metric_value_lookup_claims()：精确数值比对（允许舍入误差，不允许语义近似）
verify_origin_lookup_claims()：检查起源引用的论文是否确实提出了该概念
verify_figure_question_claims()：检查图表 claim 的图像证据支持
verify_followup_research_claims()：检查追问与上轮上下文一致性

第三层 LLM 验证器（app/services/claims/llm_verifier.py）用于复杂语义判断，如 verify_formula_claims_with_llm() 对比 claim 和原始公式的一致性。

最终 VerificationReport 含 status（pass/retry/clarify）、missing_fields、unsupported_claims、contradictory_claims、recommended_action。非 pass 时触发 retry 或澄清。

8.8 Answer Composer：AnswerComposerMixin

Answer Composer 把验证通过的 claim 转化为 Markdown 回答。核心分发机制在 tool_registries.py 的 compose() handler 中——conversation 路径通过 _COMPOSE_RELATION_STEPS 表按 relation 分发：

_COMPOSE_RELATION_STEPS: dict[str, list[Callable[[], None]]] = {
    "library_status":           [query_library_metadata, get_library_status],
    "library_recommendation":   [get_library_recommendation],
    "memory_followup":          [answer_from_memory],
    "memory_synthesis":         [synthesize_previous_results],
    "library_citation_ranking": [recover_previous_recommendation_candidates,
                                 web_citation_lookup,
                                 rank_by_verified_citation_count],
}

def compose() -> None:
    steps = _COMPOSE_RELATION_STEPS.get(contract.relation)
    if steps is not None:
        for step_fn in steps:
            step_fn()                        # 按顺序执行该 relation 对应的步骤
    elif not state.get("answer"):
        answer_conversation()                # fallback: 通用对话回答

Research 路径的 compose 在 research_compose_handlers.py 中——agent_solve_claims() 调用 SolverPipelineMixin._run_solvers() → ClaimVerifierMixin._verify_claims() → 消歧 → 生成最终答案。

AnswerComposerMixin 提供的具体 composer 方法按 relation 分发：

公式回答（compose_formula_answer()）：格式化公式、变量解释表、来源引用
论文摘要回答（compose_paper_summary_results_answer()）：目标、方法、结果
指标回答（compose_metric_value_answer()）：精确数值、单位、上下文
追问回答（compose_followup_research_answer()）：结合上轮上下文
论文推荐回答：推荐列表、理由、论文卡片
论文库状态回答：论文数、分类统计
记忆追问回答（compose_memory_followup_answer()）：从 working memory 检索

所有 composer 统一输出 AssistantCitation 结构（doc_id、paper_id、title、authors、year、page、block_type、caption、snippet），回答中用 Markdown 引用标记，前端点击跳转 PDF 预览。

8.9 多轮记忆与澄清机制

合约提取是连接意图路由和后续执行的关键环节。extract_agent_query_contract()（app/services/agent/contract_extraction.py）实现多层加工：

def extract_agent_query_contract(*, agent, query, session, mode,
                                  clarification_choice=None) -> QueryContract:
    clean_query = " ".join(query.strip().split())
    # 1. 检查是否有 pending clarification（上轮追问等待用户选择）
    clarified = contract_from_pending_clarification(clean_query, session, clarification_choice)
    if clarified is not None: return clarified

    # 2. LLMIntentRouter 路由
    targets = extract_targets(clean_query)
    decision = agent.llm_intent_router.route(query=clean_query, session=session)
    contract = query_contract_from_router_decision(decision, clean_query, session, targets, ...)

    # 3. 规范化 + followup 上下文继承
    if contract.continuation_mode == "followup":
        contract = inherit_followup_relationship_contract(contract, session)
    if contract.continuation_mode == "context_switch":
        contract = normalize_followup_direction_contract(contract, session)
    contract = resolve_contextual_research_contract(contract, session)
    contract = normalize_contract_targets(contract, ...)
    return contract

上下文压缩策略：agent_session_conversation_context() 构建每次 LLM 调用的上下文——最近 4 轮 answer 保留 900 字符，更早轮次 280 字符，超过 8 轮压缩进 summary_of_compressed_older_turns。

FollowupRoutingMixin 处理追问路由——is_negative_correction_query() 检测否定纠正（"不对，我要的是..."），触发上下文清除和重新检索；inherit_followup_relationship_contract() 为延续类问题继承 active_research。

澄清机制：LLM-judge 消歧在 disambiguation_runtime.py 中——judge_disambiguation_options() 调用 LLM 判断自动绑定或人工澄清。DISAMBIGUATION_AUTO_RESOLVE_THRESHOLD = 0.85（自动绑定），DISAMBIGUATION_RECOMMEND_THRESHOLD = 0.65（推荐但不自动）。force_best_effort_after_clarification_limit() 防止无限澄清循环。

9. 前端交互

前端由 app/static/index.html 提供，是一个单页式论文研究工作台。页面布局分为四个主要区域：

左侧 Zotero 论文库侧栏：启动时通过 GET /api/v1/library 加载论文列表，按 Zotero collection 分类展示，每篇论文显示标题、作者、年份和标签。点击论文可以触发右侧的 PDF 预览和论文信息面板。

中间聊天区：用户输入问题后，前端通过 POST /api/v1/chat/stream 建立 SSE 长连接，实时接收后端事件。聊天区支持 Markdown 渲染（含 LaTeX 数学公式）、引用标记点击、流式文本追加和思考过程展示（thinking_delta 事件）。

右侧 Runtime Inspector：展示 Agent 执行过程中的关键事件。包括 session 信息、query contract（结构化意图）、agent plan（工具计划）、plan（研究计划细节）、observation（LLM 中间观察，如 disambiguation judge 决策）、agent_step（工具步骤开始）、thinking_delta（模型思考过程流式输出）、tool_call（工具调用和摘要）、candidate_papers / screened_papers（候选论文和筛选结果）、evidence（检索到的证据块数量）、solver_selection（solver 选择结果）、claims（生成的结论数量）、verification（grounding 校验状态）、confidence（置信度评估）和 reflection（Agent 自我反思）。

引用来源和 PDF 预览：点击回答中的引用标记或 Runtime 面板中的 evidence 条目，前端会调用 GET /api/v1/citations/preview?doc_id=...&paper_id=... 获取证据详情，并在 PDF 预览区展示对应论文的 PDF 页面（通过 GET /api/v1/library/papers/{paper_id}/pdf 加载 PDF，使用 PDF.js 渲染到指定页码）。

前端代码没有使用 React/Vue 等框架，而是基于原生 JavaScript + DOM 操作实现，配合 CSS Grid 布局。SSE 事件解析使用 fetch + ReadableStream reader，每个事件的 event 类型和 data payload 被解析后路由到对应的 UI 更新函数。Runtime 面板按时间线展示事件卡片，每张卡片显示事件类型、工具名、摘要和 payload 详情。前端的价值不在于前端工程复杂度，而在于把后端 Agent 的完整执行过程可视化，让用户不仅看到最终答案，也能看到 Agent 如何理解问题、调用工具、检索证据、消歧候选和完成校验。

10. 核心功能

10.1 Zotero 论文库浏览

系统启动后从 Zotero SQLite 数据库读取所有论文记录，按 collection 分类展示在前端侧栏。支持按标题搜索、按分类筛选、查看论文详情（metadata、abstract、tags）、预览 PDF 首页。论文库数据通过 LibraryBrowserService 统一提供，前端侧栏和论文预览使用同一套数据接口。

10.2 多模态 PDF 检索问答

支持多种问题类型和证据模态的组合检索。每种类型对应 QueryContract.relation，驱动不同的 solver 和验证器：

relation	含义	solver	证据模态
`formula_lookup`	公式查询	`solve_formula_claims`	page_text, table
`metric_value_lookup`	指标查询	`solve_metric_context_claims`	page_text, table
`figure`	图表理解	`solve_figure_claims` (VLM)	figure, caption
`table`	表格解析	`solve_table_claims`	table
`entity_definition`	实体定义	`solve_entity_definition_claims`	page_text
`concept_definition`	概念定义	`solve_concept_definition_claims`	page_text
`paper_summary_results`	论文摘要	`solve_paper_summary_results_claims`	page_text
`origin_lookup`	起源查找	`solve_origin_lookup_claims`	page_text
`default_text`	通用问答	`solve_default_text_claims`	page_text
`paper_recommendation`	论文推荐	`solve_paper_recommendation_claims`	paper cards
`topology_discovery`	拓扑发现	`solve_topology_discovery_claims`	page_text
`topology_recommendation`	拓扑推荐	`solve_topology_recommendation_claims`	page_text

DPO 公式查询的实际 QueryContract（来自真实 trace）：

{
  "clean_query": "帮我看看 DPO 这篇论文的核心公式",
  "interaction_mode": "research",
  "relation": "formula_lookup",
  "targets": ["DPO", "Direct Preference Optimization"],
  "answer_slots": ["formula"],
  "requested_fields": ["formula", "variable_explanation", "source"],
  "required_modalities": ["page_text", "table"],
  "answer_shape": "bullets",
  "precision_requirement": "exact"
}

precision_requirement=exact 要求精确定位原文公式而非概念总结；required_modalities 指导检索层按 block_type 过滤证据块。

10.3 多轮上下文记忆

系统通过 SessionContext 维护多轮对话状态，包括当前研究主题（active_research）、历史轮次（turns）、工作记忆（working_memory）和持续学习（persistent_learnings）。追问时自动识别与上一轮的关系（延续/纠正/切换），复用或更新研究上下文。

10.4 引用溯源与 PDF 预览

回答中的每个结论都附带引用标记，指向具体的证据块（doc_id）和论文（paper_id）。用户点击引用可以查看证据片段、页码、块类型和原始 PDF 页面。引用的证据块类型涵盖 page_text、table、figure、formula_hint 等。

10.5 流式回答与运行时可视化

SSE 流式接口实时推送 Agent 执行全过程：Intent → Contract → Plan → Tool Loop → Evidence → Claims → Verification → Answer Delta。前端 Runtime 面板按时间线展示这些事件，用户可以追踪每一步的输入输出，调试和验证 Agent 的推理过程。

10.6 Web Search 补充检索

当本地论文库无法覆盖用户问题时（需用户显式开启），Agent 可以通过 Tavily API 进行 Web 搜索，获取外部网页信息，并转化为与本地证据格式兼容的 claim 和 citation。Web 来源在回答中会标记 source_type=web，与本地 PDF 引用区分。

10.7 动态工具扩展

系统支持在不修改代码的情况下通过 JSON manifest 注册自定义工具。load_agent_dynamic_tool_manifests() 从配置目录加载工具描述（name、when、returns、input_schema、dangerous、streaming），Agent Planner 和 Runtime 会自动将这些工具纳入工具清单和执行计划。API 层的 ToolProposalSandboxRequest 和 ToolProposalTransitionRequest 支持工具提案的生命周期管理。

10.8 Trace 持久化与调试

每次 Agent 运行结束后，完整的执行 trace（包括所有事件、execution_steps 和 final_payload）会写入 data/traces/<session_id>/ 目录下的 JSONL 文件。scripts/diff_agent_traces.py 可以对两次运行的 trace 做 diff 对比，帮助定位 Agent 行为变化的原因。

11. 测试与评估

11.1 单元测试

测试目录 tests/ 包含 80+ 个测试文件，覆盖了几乎所有服务模块。测试使用 pytest 框架，部分测试直接实例化模块进行单元测试，部分使用 StubModelClients 替代真实模型调用以加速执行。

关键测试覆盖范围：

Agent 核心流程：test_agent_v4.py 测试完整的 Agent turn、contract extraction、planner、runtime、loop 和事件流
意图路由：test_intent_router.py、test_conversation_intents.py、test_research_intents.py、test_figure_intents.py、test_followup_intents.py 等测试不同场景下的意图识别
Claim solvers：test_formula_claim_solver.py、test_generic_claim_solver.py、test_concept_definition_solver.py、test_entity_definition_claim_solver.py、test_deterministic_claim_solver.py 等测试各类 solver
Claim verifiers：test_claim_type_verifiers.py、test_claim_verifier_pipeline.py、test_claim_verification_helpers.py、test_llm_claim_verifier.py 测试验证逻辑
检索与入库：test_indexing_and_retrieval_hardening.py、test_evidence_tools.py、test_citation_ranking.py、test_web_evidence.py、test_url_fetcher.py
会话与记忆：test_session_store.py、test_session_context_helpers.py、test_memory_artifact_helpers.py、test_learnings.py、test_research_memory.py
合约与意图适配：test_intent_contract_adapter.py、test_intent_marker_profiles.py、test_contract_normalization.py、test_contract_context.py
安全：test_security.py、test_prompt_safety.py
前端：test_frontend_v5.py

11.2 Eval Cases

Eval cases 定义在 evals/cases_test_md.yaml 中，使用 YAML 格式。scripts/run_v4_eval.py 通过 HTTP 调用 /api/v1/chat 接口自动判断通过/失败：

# Eval case 结构示例
cases = [
    {
        "query": "帮我看看 DPO 这篇论文的核心公式",
        "expect": {
            "interaction_mode": "research",
            "has_citations": True,
            "answer_markers": ["DPO", "公式", "π"],      # 期望出现的文本
            "forbidden_markers": ["证据不足", "无法回答"],  # 不应出现的文本
        }
    },
]

# 评判逻辑
def _evaluate_turn(response, expect):
    answer = response.get("answer", "")
    if _contains_any(answer, expect.get("forbidden_markers", [])):
        return False, ["forbidden_marker_found"]
    if not _count_group_matches(answer, expect.get("answer_markers", [])):
        return False, ["answer_markers_missing"]
    return True, []

评估指标：

insufficient_answer_rate：答案中出现"证据不足"标记的比例
marker_match_rate：期望标记命中率
citation_present_rate：有引用的回答比例
interaction_mode_accuracy：interaction_mode 分类准确率

11.3 关键回归场景

几个经常被回归测试覆盖的关键场景：

DPO 公式查询：验证缩写消歧 + 公式提取 + 变量解释的完整链路
论文摘要查询：验证论文级检索 + 多证据融合 + 结构化摘要
多轮追问：验证上下文继承、active_research 更新、纠正场景
澄清场景：验证 LLM-judge 自动消歧和人工澄清的阈值边界
论文库状态查询：验证 conversation 路径的 library_status 和 recommendation

11.4 检索对比评测

除了单元测试和 Eval Cases，系统还包含一套独立的检索模块对比评测框架，用于量化多路融合检索策略的实际效果。

评测目标：对比 Pure Dense（单路 Milvus 向量检索）、BM25+Dense RRF（双路等权融合）和 Enhanced（四路 Weighted RRF + LLM 目标提取）三个配置在论文级检索上的表现。

评测集设计：评测集 data/eval_queries_v3.json 包含 159 道查询，覆盖 110/113 篇论文（覆盖率 97%）。构造方法遵循 IR 评测集标准流程——论文分类 → 分类型生成查询 → 难度分级 → Ground Truth 标注。

论文分类：

类型	数量	特征	查询生成方式
命名方法型	43 篇	标题以方法名开头+冒号（如 `LoRA: Low-Rank Adaptation...`）	模板自动生成："{method}是什么？"、"{method}的核心原理？"
描述标题型	70 篇	完整句子描述贡献（如 `Learning Transferable Visual Models From Natural Language Supervision`）	手动构造，用领域知识将论文贡献映射为自然语言查询

难度分级：

难度	数量	定义	示例
Easy	18 题	查询中的方法名直接出现在目标论文标题中	"LoRA是什么？" → `LoRA: Low-Rank Adaptation...`
Medium	68 题	方法名在标题中，但查询需要推理或跨论文对比	"QLoRA和LoRA在量化上有什么不同？"
Hard	73 题	查询不含方法名，或方法名不在目标论文标题中	"怎么用强化学习优化离散文本prompt？" → `RLPrompt: Optimizing Discrete Text Prompts...`

Ground Truth：每道题对应一篇论文（single-label）。命名方法型论文的 ground truth 是该论文本身；描述标题型论文的 ground truth 根据论文实际贡献手动指定。

对比配置：

配置	检索方式	融合策略
Pure Dense	Milvus 向量 top-6	无融合
BM25+Dense RRF	BM25(12) + Dense(12)	标准 RRF 等权融合
Enhanced	LLM Router 提取 targets → 4-path Weighted RRF (1.6/1.3/0.9/0.8)	多路加权融合（不含 screen_papers）

评估指标：Hit@1、Hit@3、Hit@5、MRR（Mean Reciprocal Rank）、NDCG@5，按难度分层报告。同时记录每个配置的平均检索延迟。

评测脚本：scripts/eval_retrieval.py，支持 --queries-json 指定评测集、--max-papers 控制检索数量、--seed 固定随机种子以确保可复现。

python scripts/eval_retrieval.py --queries-json data/eval_queries_v3.json --max-papers 6 --seed 42

评测结果保存在 data/eval_retrieval_results.json，包含每个配置的聚合指标和逐题详情，可用于后续分析各配置在不同难度和查询类型上的表现差异。

整库评测结果（159 题，3 配置，BM25 使用 jieba CJK 分词器）：

Metric	Pure Dense	BM25(jieba)+Dense RRF	Enhanced (4-path)
Hit@1	0.956	0.748	0.824

分难度结果：

难度	题数	Dense Hit@1	BM25+Dense Hit@1	Enhanced Hit@1
Easy	18	1.000	1.000	1.000
Medium	68	0.985	1.000	1.000
Hard	73	0.918	0.575	0.575

在消歧义与关系查询专项（26 题）和注入噪声对比（26 题）两个细分评测集上的表现见 11.5 消融实验。

关键发现：

Pure Dense 在整库语义匹配上几乎完美（Hit@1=97.5%）。这是因为 text-embedding-3-large（3072 维）在 113 篇论文的封闭域上，paper_card 中的 LLM 摘要（占内容的 86%）提供了充分的语义信号。
BM25 对中文原本完全失效（Hit@1=0.176），原因是默认空格分词器将整句中文字符串视为单个 token。更换为 jieba CJK 分词器后恢复到 0.748——这是整个评测过程中最有价值的工程发现。
Enhanced 在整库评测中未超越 Pure Dense（0.824 vs 0.956），因为评测集中多数查询属于"方法名→论文"的语义匹配，正是 Dense 的最强项。多路融合的价值不在此类查询上体现。

11.5 检索消融实验

为进一步量化 LLM 摘要和多路融合各自的贡献，设计了两组消融实验。

实验一：LLM 摘要贡献度分析

paper_card 的内容组成：

组成部分	字符数	占比
结构化字段（title, aliases, authors, year, tags）	419	14%
LLM/Zotero 生成的摘要	1258	42%
证据提示及其他	1333	44%

摘要占 paper_card 总内容的 42%，是 Dense embedding 最主要的语义来源。去掉摘要后，embedding 只能基于 419 字符的结构化关键词来计算。

实验二：摘要消融对比（26 道消歧义+关系查询）

构建一份完全去除摘要的 paper_card（abstract_or_summary: [removed]），重建 Milvus 索引和 BM25 索引，在相同查询上对比：

配置	有摘要 Hit@1	无摘要 Hit@1	Δ
Pure Dense	0.577	0.500	-13.3%
BM25(jieba)+Dense RRF	0.500	0.385	-23.1%
Enhaced (4-path)	0.308	0.538	+75.0%

结论：

摘要对 Dense 至关重要：去掉后 Hit@1 下降 13.3%，验证了 LLM 生成摘要是 Dense 高性能的前提。在面试中可将其作为独立优化点陈述——"LLM 生成的 1200+ 字符摘要将 paper_card 内容扩充了 6 倍，直接贡献了 13% 的 Hit@1 提升"。
多路融合在 Dense 弱化时接管：无摘要时 Enhanced 从 0.308 反超到 0.538（超过 Pure Dense 的 0.500），证明 Title Anchor 和 Relation Anchor 在 embedding 信号不足时提供了关键互补。
但在当前规模下，Dense 就是最优解：159 题整库评测中，Pure Dense 的 Hit@1（0.956）在所有配置中最高，Enhanced 在任何条件下都未超越它。多路融合在更大规模、更多噪声的场景下可能有意义，但在 113 篇论文的封闭域上是过度设计。基于此实验结论，项目已将默认检索路径简化为 Dense-only，Title Anchor 和 Relation Anchor 保留为可选模块。
BM25 jieba 修复的验证：无摘要时 BM25+Dense 从 0.500 掉到 0.385（-23.1%），说明 BM25 比 Dense 更依赖摘要文本中的关键词匹配。jieba 分词让 BM25 从完全不可用（0.176）恢复到可用水平（0.748），但在消歧义场景下仍不及 Dense。

消融实验脚本见 scripts/benchmark_stripped.py，结果保存在 data/eval_ablation_results.json。

11.6 架构边界测试

test_review_architecture_boundaries.py 专门测试模块间的架构边界，确保 domain models 不依赖基础设施、service 层不循环依赖、Agent mixins 的正交性等约束。

12. 部署与运维

12.1 systemd 服务

生产部署使用 systemd 管理进程。服务定义在 deploy/systemd/pdf-rag-agent-v4.service：

[Unit]
Description=PDF RAG Agent V4
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/owen/pdf-rag-agent-v4
Environment=PYTHONUNBUFFERED=1
ExecStart=/home/ubuntu/miniconda3/envs/zotero-paper-rag/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8001
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

服务监听 127.0.0.1:8001，通过 Nginx 反向代理暴露到公网。Restart=always 和 RestartSec=3 确保进程异常退出后 3 秒自动重启。

12.2 环境变量

配置通过 Settings（Pydantic BaseSettings, app/core/config.py）管理，从 .env 文件和环境变量读取。当前实际部署配置（/home/ubuntu/owen/pdf-rag-agent-v4/.env）：

# ── Chat Model（OpenAI 兼容协议）──
CHAT_MODEL=deepseek-v4-flash
OPENAI_API_KEY=sk-xxx
OPENAI_BASE_URL=https://api.deepseek.com/v1

# ── Embeddings（DeepSeek 不支持 embedding，走 Qihai 网关）──
EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_BASE_URL=https://api.qhaigc.net/v1
EMBEDDING_API_KEY=sk-xxx

# ── VLM ──
VLM_MODEL=gpt-4.1-mini

# ── Web Search ──
TAVILY_API_KEY=tvly-xxx

关键配置项说明：

环境变量	Settings 字段	当前值	默认值	说明
`CHAT_MODEL`	`chat_model`	`deepseek-v4-flash`	`gpt-4o-mini`	Chat 模型名
`OPENAI_API_KEY`	`openai_api_key`	`sk-xxx`	`""`	Chat + VLM 的 API key（也支持 `QIHANG_API` alias）
`OPENAI_BASE_URL`	`openai_base_url`	`api.deepseek.com/v1`	`api.openai.com/v1`	Chat + VLM 的 Base URL（也支持 `QIHANG_BASE_URL` alias）
`EMBEDDING_API_KEY`	`embedding_api_key`	`sk-xxx`	`""`	Embedding API key（独立字段，fallback 到 `openai_api_key`）
`EMBEDDING_BASE_URL`	`embedding_base_url`	`api.qhaigc.net/v1`	`api.openai.com/v1`	Embedding Base URL（也支持 `EMBEDDING_BASE` alias）
`EMBEDDING_MODEL`	`embedding_model`	`text-embedding-3-large`	同	Embedding 模型名
`VLM_MODEL`	`vlm_model`	`gpt-4.1-mini`	同	Vision 模型名
`embedding_fallback_model`	同上	`text-embedding-3-small`	同	Embedding 降级模型（1536 维）
`MILVUS_URI`	`milvus_uri`	`localhost:19530`	同	Milvus 连接地址
`TAVILY_API_KEY`	`tavily_api_key`	`tvly-xxx`	`""`	Web Search API key
`ADMIN_API_KEY`	`admin_api_key`	空	`""`	管理员 key（空=禁用敏感接口）

注意：Chat 和 VLM 共用同一个 openai_api_key + openai_base_url，而 Embedding 使用独立的 embedding_api_key + embedding_base_url（因为 DeepSeek 不支持 embedding，需要走 Qihai 网关）。

12.3 服务端口与路由

FastAPI 服务监听 8001 端口，主要路由：

/ → 直接返回 index.html
/v4 / /v5 → 前端页面 index.html
/api/v1/health → 健康检查
/api/v1/library → 论文库列表
/api/v1/chat → 普通问答（一次性返回）
/api/v1/chat/stream → SSE 流式问答
/api/v1/ingest/rebuild → 索引重建（需 admin key）
/api/v1/citations/preview → 引用预览
/api/v1/tools/proposals → 动态工具提案管理
/metrics → Prometheus metrics（可选）

12.4 安全控制

安全控制通过 app/core/security.py 实现：

require_admin_access()：检查 ADMIN_API_KEY 是否已配置，并根据请求头中的 X-API-Key 或 Authorization: Bearer 校验管理员身份。如果未配置 admin key，返回 503 禁用敏感接口。
require_pdf_access()：检查 PDF_ACCESS_KEY 是否已配置并校验，防止未授权访问本地 PDF 文件。
CORS 限制：通过 settings.cors_allow_origins 配置允许跨域的前端来源，未配置时默认不启用 CORS。
输入安全：prompt_safety.py 对用户输入做基本的注入检测和长度限制。

12.5 日志与监控

日志通过 app/core/logging.py 的 setup_logging() 初始化，使用 Python 标准 logging 模块输出 JSON 格式日志，每条日志包含 timestamp、level、logger、message 和异常信息。

Prometheus metrics（可选）通过 prometheus_fastapi_instrumentator 暴露，包含 HTTP 请求数、响应延迟分布、状态码分布、Python GC 统计、进程内存和 CPU 使用率、文件描述符数量等指标。生产环境使用 Grafana 面板展示这些指标。

13. 项目难点与迭代

13.1 从普通 RAG 到 Agent

最初的设想是一个简单的"搜索 PDF + 问 LLM"系统。但实际使用中发现，论文问答需要的远不止检索+生成：用户可能用缩写指代论文、可能在追问中省略上下文、可能需要精确的公式或指标数值而不是模糊总结、可能需要比较不同论文的结果。这些需求迫使系统从一个简单的 RAG pipeline 演进成一个有意图理解、工具规划、多步执行、验证回退能力的 Agent 系统。

13.2 从 relation 分类到结构化意图

早期版本的意图识别只输出一个 relation 字符串，后续模块各自从原始 query 中重新提取信息。这导致不同模块对同一问题的理解不一致。引入 QueryContract 后，所有后续模块都从同一个结构化的意图对象中读取 targets、requested_fields、required_modalities、answer_shape、precision_requirement 等字段，消除了信息提取的不一致性。

13.3 从固定流水线到 tool loop

最早的实现是固定的线性流水线：识别意图 → 检索 → 抽 claim → 验证 → 回答。但实际场景中，有些问题需要多次检索（先找论文、再找公式、再找表格），有些需要验证失败后 retry，有些需要在检索过程中发现新目标。引入 tool loop 机制后，Agent 可以根据当前状态动态决定下一步动作，planner 可以在运行时调整工具序列，runtime 支持有限步数内的自动回退和重试。

13.4 多轮上下文绑定

多轮对话的难点在于判断新问题与旧问题的关系。用户可能说"那它的实验结果呢"，系统需要知道"它"指的是上一轮讨论的那篇论文；用户也可能说"不对，我要的是 DPO 原论文"，系统需要识别这是对上一轮的纠正。通过 SessionContext 中的 active_research、topic_signature 和 FollowupRoutingMixin 的上下文分析，系统能够在不同 followup 模式下做出正确响应。is_negative_correction_query() 函数专门检测否定纠正类问题，触发上下文清除和重新检索。

13.5 公式、图表与精确指标

这是论文问答中最具挑战性的部分。公式不是普通文本，LaTeX 和 Unicode 数学符号的检索需要特殊的 token 权重和匹配逻辑。图表需要 VLM 理解，但 VLM 的调用成本高、延迟大。精确指标（如 Accuracy=94.2%）要求系统不能做语义近似，必须精确匹配证据中的数值。

解决方案：

公式检索使用 retrieval_formula_token_weights 和 FORMULA_HINT_RE 做专门加权
图表理解采用按需调用 VLM 的策略，先用文本信号（figure_signal_score()）判断页面是否包含目标图表，再决定是否渲染并调用 VLM
指标验证使用 verify_metric_value_lookup_claims() 做精确数值比对，允许小范围舍入误差但不接受语义近似

13.6 从人工澄清到 LLM-judge 自动消歧

早期版本中，只要系统发现一个缩写或实体可能对应多篇论文，就会直接进入 ask_human，把候选项交给用户选择。这种方式很安全，但在 DPO 这类"原论文明显存在，其他论文只是引用或应用"的场景下，会打断用户体验。最新版本加入了 DisambiguationJudgeDecision，让 LLM-judge 在候选 metadata、snippet、paper summary 和 ranking signals 的基础上判断是否可以自动绑定候选。只有当 judge 返回 auto_resolve 且置信度不低于 0.85 时，系统才自动选择论文；如果置信度不足，则仍保留人工澄清，并可把高分候选标记为推荐项。这样既减少了不必要的追问，也避免在低置信度场景下盲目猜测。

13.7 从单文件到分层架构

项目最早的 agent.py 是一个超过 2000 行的单文件。随着功能增加，单文件变得难以维护：修改一个 solver 可能影响 planner，调试一个 bug 需要在同一文件中跳转数百行。重构过程经历了多次迭代：

第一轮：把 retrieval、library、session_store 拆成独立服务模块
第二轮：把 Agent 核心逻辑拆分为 planner、runtime、tools、events、loop 等模块
第三轮：引入 Mixin 模式，把 answer_composer、claim_verifier、entity_definition、followup_routing、solver_pipeline 五大能力正交拆分。ResearchAssistantAgent 通过多重继承组合这些 Mixin，每个 Mixin 只关心自己的领域
第四轮：把 claims、answers、intents、contracts、planning 按领域拆成独立子包，每个 app/services/<domain>/ 子包有明确的职责边界

现在的目录结构清晰反映了领域边界：__init__.py 中只做 re-export，模块间的依赖通过构造函数注入而非硬编码 import。

13.8 Dynamic Tools 扩展机制

后续发现有些工具需求不适合写死在核心代码中（如特定的 SQL 查询、自定义的数据分析工具）。引入动态工具机制后，用户可以通过 JSON manifest 文件注册新工具，Agent 的 Planner 和 Runtime 会自动发现并集成这些工具。ToolProposalSandboxRequest 和 ToolProposalTransitionRequest 这两个 API schema 支持工具提案的生命周期管理——从提案创建、沙盒测试到正式启用。

13.9 Compound Query 复合查询

对于包含多个独立子问题的复杂查询（如"比较 DPO 和 PPO 的公式，并分析各自的优缺点"），系统通过 run_compound_query_if_needed() 将问题分解为多个子任务，逐个执行后合并结果。compound.py 中的分解逻辑使用 LLM 判断是否需要拆分以及如何拆分，每个子任务独立走完整的 Agent 流程，最后通过 CompoundTaskResult 汇总。

14. 总结与后续优化

14.1 项目总结

PDF-RAG-Agent V5是一个从真实论文研究需求出发构建的智能助手系统。它的核心价值体现在几个方面：

分层架构清晰：API 层、Agent 层、服务层、数据层各司其职，通过 domain models 传递状态，避免了"到处传 dict"的混乱
检索设计务实：两级索引（论文级 + 证据级）+ Dense-only 默认检索（可选 BM25/Title Anchor）+ 场景化加权，解决了通用 RAG 在论文场景下的召回精度问题
Agent 链路完整：Intents → Contract → Plan → Tool Loop → Solver → Verifier → Composer 的七阶段链路，每一阶段都有明确的输入输出和失败处理
可观察性强：SSE 流式事件 + Runtime 面板 + trace 持久化，让 Agent 的每一步推理都可追踪、可调试
测试覆盖广：80+ 个测试文件覆盖几乎所有模块，StubModelClients 让测试不依赖外部 API
持续演进：从单文件到分层架构、从固定流水线到 tool loop、从人工澄清到 LLM-judge 自动消歧、从纯 RAG 到可以处理公式/图表/指标的论文 Agent，项目在整个开发过程中不断根据实际使用反馈迭代

14.2 后续优化方向

Streaming 工具执行：目前 tool loop 中的工具是同步执行的，后续可以让 search_corpus 和 compose 在工具内部流式产出结果，减少用户感知的首 token 延迟
更智能的 retry 策略：当前 retry 预算固定为 1，可以根据 verification report 中 missing_fields 的具体类型（是缺公式还是缺指标还是缺论文）做更精细的 retry 决策
论文库增量更新：当前 ingest rebuild 是全量重建，后续可以支持增量模式——只处理新增或修改的论文，大幅缩短入库时间
多库联合检索：当前只支持单个 Zotero 库，后续可以支持多个 Zotero profile 或跨库检索
Answer quality 自动化回归：在 eval cases 基础上建立 answer quality 的自动化回归测试，每次改动后自动跑 eval 并对比分数，防止性能退化
持久化 learnings 的自动更新：当前 persistent_learnings 需要手动维护，后续可以让 Agent 在每次研究后自动提取关键发现并写入
跨论文对比能力增强：当前 compound query 支持基本的子任务分解，但跨论文的深度对比（如方法对比、结果对比、消融实验对比）还可以做得更精细
VLM 调用策略优化：当前 VLM 调用是按需的，但判断"是否需要 VLM"本身也需要一次 LLM 调用。后续可以通过更强的文本信号预处理减少不必要的 VLM 调度判断

AIOS-NP 项目档案：从 AIOS 内核到在线新闻系统

Tue, 21 Apr 2026 00:00:00 GMT

项目展示页位于 AIOS Newsroom。这篇文章不再保留原来的概览模板，而是直接使用当前项目的完整笔记，作为展示页里的正式项目档案。

背景

项目由来

AIOS-NP 是由比赛项目更改而来，发布在线上的项目，并已经公开了MCP。该项目初版获 第二届中国研究生操作系统开源创新大赛 国家三等奖。总体而言，是一个基于 workflow 的多 Agent 新闻生成流水线，当前已经演化为 hot_api -> sort -> search -> generate -> review -> report 六阶段结构。

AIOS背景

以下来自于比赛使其调研的笔记修改：

(1) 必要性

往往需要在同一个设备上运行很多的Agent. ( 即使是Single-Agent也可能在内部分出许多Sub-Agent). 那么底层的LLM就可能要满足很多Agent同时的请求, 如果不做管理, 如果同一个Agent一直密集向LLM发送请求, 那么就会让其他Agent拿不到资源, 看上去像死机一样.

这个过程实际上很容易让人联想到操作系统的功能 -- 它不仅提供硬件接口对软件的接口, 同时也会按照设计的算法来调度进程, 保证多进程系统依然可以异步有效工作.

于是类似于传统OS, 一个基于开源大模型Agent的操作系统, AIOS 就诞生了.

(2) 对比传统OS

AIOS的核心是一个或几个大模型, 中间层设计了AIOS的SDK, 来帮助Agent Developer更好构建他们的Agents, 而上层则是会跑各种Agent的应用 ( AAPs, Agent Applications ).

以下两张图片分别是传统OS的架构和AIOS架构的示意图.

我们可以发现, AIOS可以很容易类比到传统OS的生态, 由此我们可以体会到AIOS的设计哲学, 如下表:

两者的发展历程也具有相似性, 只不过AIOS的发展要比OS发展的迅速非常多, 如下图

AIOS架构

1. 总览

AIOS: AI Agent Operating System Github 论文, 它将大型语言模型（LLM）嵌入到作系统中，并促进基于 LLM 的 AI 代理的开发和部署. AIOS 旨在解决基于 LLM 的代理开发和部署过程中的问题（例如，调度、上下文切换、内存管理、存储管理、工具管理、代理 SDK 管理等）, 为代理开发人员和代理用户提供更好的 AIOS-Agent 生态系统. AIOS 包括 AIOS 内核（此AIOS存储库）和 AIOS SDK（Cerebrum 存储库), AIOS 支持 Web UI 和终端 UI. 它的具体框架如下文所展示.

2. Cerebrum

Cerebrum: Agent SDK for AIOS Github 专为代理用户和开发人员设计, 使他们能够通过与 AIOS 内核交互来构建和运行代理应用程序. 但要注意, 我当前项目中的 cerebrum/ 并不是上游 Cerebrum 仓库的完整拷贝, 而是一个嵌入到 AIOS-NP 中、经过裁剪和本地化适配后的 SDK 子集. 因此这里不再照抄上游完整目录树, 而是按当前仓库真实结构来理解:

AIOS-NP/cerebrum
|-- __init__.py
|-- commands
|   |-- download_agent.py
|   |-- download_tool.py
|   |-- list_agenthub_agents.py
|   |-- list_available_llms.py
|   |-- list_local_agents.py
|   |-- list_local_tools.py
|   |-- list_toolhub_tools.py
|   |-- run_agent.py
|   |-- upload_agent.py
|   `-- upload_tool.py
|-- community
|   `-- adapter
|       |-- adapter.py
|       |-- autogen_adapter.py
|       |-- interpreter_adapter.py
|       `-- metagpt_adapter.py
|-- config
|   |-- config.yaml
|   `-- config_manager.py
|-- interface
|   `-- __init__.py
|-- llm
|   |-- apis.py
|   `-- layer.py
|-- manager
|   |-- agent.py
|   |-- package.py
|   `-- tool.py
|-- memory
|   |-- __init__.py
|   |-- apis.py
|   `-- layer.py
|-- storage
|   |-- apis.py
|   `-- layer.py
|-- tool
|   |-- apis.py
|   |-- base.py
|   |-- core
|   `-- layer.py
|-- utils
|   |-- browser.py
|   |-- communication.py
|   |-- manager.py
|   |-- packages.py
|   |-- run_agent.py
|   `-- utils.py
|-- pyproject.toml
`-- requirements.txt

这个 SDK 依然是实现 AIOS 整个体系的关键, 但对于当前项目而言, 更重要的不是背完整仓库树, 而是明确它在本地项目中承担了哪几类职责. 我把它理解为: 一层面向 AIOS Kernel 的 Query / Response SDK, 上面再由 apps/news_app 这层业务应用去组织真正的新闻流水线.

(1) 当前项目中的 cerebrum

这个文件夹被整体当作可安装的包使用, 即已经通过 pip install -e . 安装, 并在本地脚本和业务代码中直接导入. 对当前新闻项目来说, 它的主要作用如下:

commands
存放一组命令行入口, 用于 agent / tool 的上传、下载、列举与运行. 这些脚本体现了 Cerebrum 作为 SDK 的“工具化外壳”.
community
用于适配外部多智能体框架. 当前项目中可以看到 autogen_adapter.py、interpreter_adapter.py、metagpt_adapter.py 等文件, 说明它仍保留了对这些框架的兼容能力. 但对我当前的新闻业务主线而言, 这层已经不是核心.
config
负责保存并读取 Cerebrum 向 AIOS Kernel 发请求时依赖的配置, 最关键的是内核地址、模型地址和相关运行参数. 这层一定要和 aios/config 保持信息流一致.
interface
这一层原本更偏向于和 hub 对接的接口封装. 在当前仓库里已经被明显收缩, 实际上主要只剩下 AutoTool 这种较薄的封装, 用来从 Tool Hub 或本地加载工具.
llm
这是最重要的 API 层之一.
apis.py 中定义了 LLMQuery 和 LLMResponse, 负责描述 LLM 请求和返回结构; 同时实现了 llm_chat、llm_chat_with_json_output、llm_chat_with_tool_call_output、llm_call_tool、llm_operate_file 等核心函数.
layer.py 则定义了和 LLM 推理层参数有关的数据结构.
manager
负责 agent / tool 的打包、上传、下载、缓存、动态加载和版本管理. 这层是整个 SDK 插件化能力的基础, 但在阅读当前新闻流水线时不是优先关注对象.
memory
与 llm 结构类似, 但面向记忆管理.
apis.py 中定义了 create_memory、get_memory、update_memory、delete_memory、search_memories 和 create_agentic_memory 等方法, 用于给智能体提供长期记忆能力.
storage
面向存储操作的 API 封装.
apis.py 中实现了 mount、retrieve_file、create_file、create_dir、rollback_file 和 share_file 等能力, 用于将文件操作统一成对 AIOS Kernel 的请求.
tool
与 llm 类似, 是工具调用这一类 syscall 的 SDK 封装.
apis.py 中定义了 ToolQuery、ToolResponse 和 call_tool; base.py 定义了 BaseTool 及相关工具基类; layer.py 负责工具层数据结构; core/ 下则存放了本地工具实现.
utils
这是通用工具库, 提供通信、浏览器辅助、包管理、脚本运行等支撑函数. 这里不用一开始就逐个读懂, 先知道它是底层支撑层即可.

需要强调的是, 上游 Cerebrum 仓库中常见的 benchmarks、docs、tests、example 等目录, 在我当前这个本地项目中并不是主阅读对象, 甚至有些已经不存在. 因此后续写项目笔记时, 应该始终以当前仓库中的实际目录为准, 不再把“上游完整仓库结构”和“本地裁剪后的可运行版本”混为一谈.

(2) 当前项目实际使用的 Cerebrum APIs

Cerebrum 在设计上提供了 llm / memory / storage / tool 四类 API。对当前 AIOS-NP 新闻项目而言，最重要的不是把这些函数名逐个背下来，而是先明确：它们分别对应内核中的哪一类 Query / Response 协议。

llm.apis -> LLMQuery / LLMResponse
memory.apis -> MemoryQuery / MemoryResponse
storage.apis -> StorageQuery / StorageResponse
tool.apis -> ToolQuery / ToolResponse

也就是说，Cerebrum 在当前项目中的角色，不只是“提供一些方便调用的 Python 函数”，而是把“向 AIOS 内核发请求”这件事统一封装成四类结构化 API。下面按当前项目实际使用情况来理解。

1. LLM API

这一组是当前新闻生成链路里使用最频繁的一层，对应的底层协议是 LLMQuery -> LLMResponse。典型接口包括：

from cerebrum.llm.apis import llm_chat
from cerebrum.llm.apis import llm_chat_with_json_output
from cerebrum.llm.apis import llm_call_tool

llm_chat 是最常用的接口，用于标题、摘要、正文、专家评审、总览生成等文本生成任务。
llm_chat_with_json_output 主要用于需要结构化输出的场景，比如 sort_agent 对热榜进行分类整理时。
llm_call_tool 保留了“由 LLM 决定调用哪个工具”的能力，但当前新闻项目的主流程里并不依赖它作为默认路径。

因此，LLM API 在当前项目中的作用，可以概括为：

统一构造 LLM 请求
屏蔽内核 /query 的细节
让上层 agent 能围绕 prompt 和结果来组织业务逻辑

2. Memory API

这一组对应 MemoryQuery -> MemoryResponse。当前项目虽然确实在使用 Cerebrum 的记忆接口，但主要不是在每个 agent 文件里直接调用，而是通过 runtime_support/memory.py 再做了一层业务封装。当前实际会用到的接口主要是：

from cerebrum.memory.apis import create_memory
from cerebrum.memory.apis import create_agentic_memory
from cerebrum.memory.apis import search_memories

这些接口在新闻项目中的作用，主要是：

将工作流中的编辑决策写入长期记忆
在后续生成或出报前检索相似题材
为当前 gate 提供历史通过/拒绝的参考

因此它在当前项目中的定位不是“通用聊天记忆”，而是服务于新闻质量控制的编辑决策记忆层。

3. Storage API

这一组对应 StorageQuery -> StorageResponse。存储接口现在也还在使用，但同样不是业务代码直接大面积调用，而是通过 runtime_support/artifacts.py 的 ArtifactStore 抽象统一管理。当前实际接入的接口主要包括：

from cerebrum.storage.apis import mount
from cerebrum.storage.apis import create_dir
from cerebrum.storage.apis import write_file
from cerebrum.storage.apis import read_file
from cerebrum.storage.apis import list_dir
from cerebrum.storage.apis import delete_file
from cerebrum.storage.apis import delete_dir

这些 API 的作用是把中间产物和最终结果的文件操作，统一包装成对 AIOS Kernel 的存储请求。不过在当前项目中，这层还有本地文件后端作为 fallback，因此它体现的是“可接入 AIOS 原生存储能力”，而不是整个新闻系统对它强依赖。

4. Tool API

这一组对应 ToolQuery -> ToolResponse。当前项目里最重要的入口是：

from cerebrum.tool.apis import call_tool

它的作用是把“执行某个工具”这件事包装成独立 syscall。当前新闻流水线已经把 hot_api 和 web_search 这类叶子能力下沉为本地工具，因此 Tool API 在当前项目中的定位很清楚：

承接被下沉的叶子能力
让这些能力进入 AIOS runtime 的 ToolManager 调度链
为以后更 agentic 的工具使用方式留出扩展空间

5. 当前保留但不是主流程重点的 API

除了上面这些当前仍在使用的接口之外，Cerebrum 里还保留了一些能力，例如：

from cerebrum.llm.apis import llm_chat_with_tool_call_output
from cerebrum.llm.apis import llm_operate_file
from cerebrum.storage.apis import retrieve_file
from cerebrum.storage.apis import rollback_file
from cerebrum.storage.apis import share_file

这些接口在仓库中依然存在，说明 AIOS 的能力边界依旧比较完整；但对当前新闻项目的主业务流水线来说，它们并不是最值得优先展开的部分。因此在项目介绍里，我更倾向于把它们放在“能力储备”或“扩展路径”的位置，而不是当成当前项目主链路的核心实现。

3. AIOS Kernel

作为和Cerebrum直接沟通的部分，同时也是与大模型直接沟通的部分, 这一部分是用来处理各种syscall的关键.

AIOS kernel中包含一个系统核心所需要的各种方法, 它暴露了一系列接口来接受 Query, 再通过 SystemCall 绑定 Scheduler, 按照一定规则与 LLM / Memory / Storage / Tool 等模块交互, 最终得到结果返回. 所以要想真正跑起 AIOS, 就必须先通过 runtime 里的 launch 脚本启动核心. 对当前新闻项目来说, Kernel 更像是整个底层 syscall 能力的统一入口, 其上再由 Cerebrum 负责封装请求, 最后由 apps/news_app 组织成具体业务流水线.

4. LSFS

LSFS 即 LLM-Based Semantic File System for AIOS, 是 AIOS 在存储层上的一个语义文件系统设计. 它试图把传统“精确路径 + 明确命令”的文件操作方式, 扩展成“通过自然语言驱动文件读写、检索和管理”的交互模式.

在当前仓库中, 与 LSFS 相关的核心实现主要位于 aios/storage/filesystem/lsfs.py, 而对外暴露的存储 API 则在 cerebrum/storage/apis.py. 从接口设计上看, 它支持 mount、retrieve_file、create_file、create_dir、write_file、rollback_file 和 share_file 等操作, 体现的是 AIOS 把存储也抽象成 syscall 的思路.

不过要注意, LSFS 并不是当前新闻项目的主业务链路. 现在这版 AIOS-NP 的新闻系统, 更直接依赖的是 runtime_support/artifacts.py 中的 ArtifactStore 抽象来管理中间产物和最终结果.

内核窥探

AIOS实现了自己的 agent runtime 基础设施，而非简单的LLM API包装。通过上面对架构的了解，我们知道 cerebrum 侧有统一的 LLM/Tool/Storage/Memory 的 Query/Response 协议；aios 侧有统一的syscall分发器；有独立的 scheduler 层；有自己的 LLM core adapter、memory、storage、tool manager、context manager。

现在，我们来详细看看这个基础设施是怎么运行起来的、有多大的扩展性、有哪些优势。

1. 运行

(1) 启动、调度阶段

启动阶段有几个重要的事，由于内核本质上就是一个服务，所以最重要的统一请求入口在 runtime/launch.py 中定义了，用于统一接收Query的运行时服务。

首先，我们会启动FastAPI服务，将统一请求入口定为 /query。

然后，我们会按顺序初始化核心组件，用initialize_xxx 函数，依次对 config -> llms -> storage -> memory -> tool -> scheduler -> factory 进行初始化。这里可以理解成两段，首先是四大能力模块先装起来，然后是调度器和agent工厂。

initialize_llm_cores() 用于准备LLM子系统，它具体做了三件事：

从配置里读取models
取log_mode（决定日志写在终端还是日志文件，scheduler 会用到这个机制）和use_context_mananger
调llm.py的useCore(...)。这里的useCore(...)实际上是用来返回adapter.py的LLMAdapter

而LLMAdapter在初始化的时候又继续做了这些事：

根据 provider 配置 API key
初始化每个模型后端
如果开了 use_context_manager，创建 SimpleContextManager
配置路由策略，比如 sequential / smart

也就是说，这一步，做了模型注册、API key注入、上下文管理开关、路由策略初始化。

initialize_storage_manager()做的事情比较直接，它用于把存储子系统挂起来，从配置里拿到root_dir（如果不是绝对路径就转为项目内的绝对路径），然后调用 storage.py 的useStorageManager(...)，它返回的是 storage.py 的StorageManager，而StorageManager在构造的时候又会：

创建根目录
默认使用 filesystem_type="lsfs"
实际挂上 LSFS(root_dir, use_vector_db)

也就是说，这一步用于将storage syscall最终落在LSFS这个文件管理系统上。LSFS 还会尝试连本地 Redis 存版本记录。

initialize_memory_manager() 比较简单，他从配置中读取 log_mode，然后调用 memory.py中的useMemoryManager(...)，返回 manager.py 里的MemoryManager，而MemoryManager在调用的时候外部又包裹了一层BaseMemoryManager。self.memories是Python进程内的字典，它是运行期间内存态。

initialize_tool_manager() 用来挂载工具调用子系统，它直接调用 tool.py的useToolManager()。另外，ToolManager构造函数里面有个关键动作：

初始化tool conflict map和锁
启动MCP server

所以这一步，除了启动工具系统外，连MCP工具服务也一并启动了。

initialize_scheduler() 是启动最关键的一步，它用于将前面四个能力模块结成一个真正会跑的调度系统。它做了如下事情：

重新读取 llms 配置里的 use_context_manager
如果开了 context manager，就选 RR scheduler
否则选 FIFO scheduler
把 llms / memory / storage / tool 全都传给 scheduler
最后直接 scheduler.start()

所以，这一步将内核从“组件已创建”变成“开始消费 syscall 队列”。

initialize_agent_factory()是给系统补上的agent提交能力和异步执行能力。

initialize_components()作为启动编排器，它从ConfigManager切出每一块配置，按顺序初始化组件之后，校验四大核心组件是否都成功，然后再起scheduler和factory，就相当于一个统一装机脚本。initialize_components_safe()是让内核再初始化失败的情况下也可以降级启动，成功时记录startup_state["initialized_at"]，失败时记录startup_state["initialization_error"]，然后返回全None的组件表，这样即使没有初始化成功，仍可以通过/status或者/core/status把错误暴露出，不至于完全起不来思路。

最后，来做一点启动阶段的总结。 initialize_xxx() 都在返回后续runtime的实例对象，LLMAdapter、StorageManager、MemoryManager、ToolManager。它们根据配置，创建已经带状态、带资源、能执行请求的活对象。然后，用关键的一步initialize_scheduler()，将四个子系统接入统一的syscall消费框架，它决定调度器、把四个能力都塞进去、绑定 syscall 队列的读取入口、启动四个处理线程。最终，scheduler 会知道去哪里取 syscall。至于initialize_components()，是把实例写进字典，检查是否缺失，然后再进行初始化后面的scheduler和factory；initialize_components_safe()用来做降级检验。

在 AIOS 中，syscall 是对高层 Query 的内核化封装。它不仅携带请求参数，还携带状态、时间、响应和同步事件等运行时信息。scheduler.start() 并不负责创建队列，而是启动各类 syscall 队列的消费者线程；真正的请求分流发生在 SyscallExecutor 中，它根据 Query 类型将 syscall 放入对应的全局队列，再由 scheduler 交给不同的 manager/adapter 执行。

(2) 请求阶段

请求阶段中，上层SDK会先走 Cerebrum API，把请求包装成 Query。通过API，构造出LLMQuery、MemoryQuery、StorageQuery、ToolQuery，然后再发到/query接口。

不过这里还有一个容易忽略的细节：请求正式进入 handle_query() 之前，runtime/launch.py 里的 QueryRequest 就已经会根据 query_type 对 query_data 做一轮类型恢复。也就是说，传进来的原始 JSON 会先被 Pydantic 尝试转换成对应的 LLMQuery / ToolQuery / StorageQuery / MemoryQuery，之后才交给 /query 路由继续处理。

然后，/query就会根据query_type重建Query对象，再统一走SyscallExecutor，先看Query类型，然后再根据细分类型做路由，比如：

LLMQuery(action_type="chat") -> 走 LLM syscall
LLMQuery(action_type="call_tool") -> 先走 LLM，再转 Tool syscall
LLMQuery(action_type="operate_file") -> 走文件操作逻辑
StorageQuery -> 走 storage syscall
MemoryQuery -> 走 memory syscall

这里还要补一层理解：handle_query() 虽然对四类请求都做了重建，但 LLM 路径其实比另外三类更复杂。对于 LLMQuery，内核还会先检查 selected_llms["llms"] 这个全局选择的模型列表；如果请求里没有显式指定模型，就尝试补上当前选中的模型；如果显式指定了模型，还会校验这些模型是否真的已经被选中。只有这一步通过后，才会真正把 LLM 请求交给 execute_request。而 storage / tool / memory 三类路径则相对直接，基本是重建对象后就下发执行。

再往下一层看，execute_request() 也并不是简单地“一种 Query 对应一次 syscall”。有些 action_type / operation_type 会展开成一段多阶段链路。例如：

call_tool：先走一次 LLM syscall，让大模型产出 tool_calls，再组装成 ToolQuery 继续下发
operate_file：先让 LLM 把自然语言文件意图解析成 storage tool calls，再转成 StorageQuery 执行，最后还会再用一次 LLM 对操作结果做总结
add_agentic_memory：先分析内容、再检索相似记忆、再做 memory evolve，最后才真正写入或更新 memory

所以，这一层最值得记住的是：AIOS 里的请求路由不是平面的 switch-case，而是允许在 syscall 之间继续展开出新的 syscall 链。

SyscallExecutor会创建具体syscall 对象，并为其分配pid、source、status、timestamp，然后放入全局队列，等待syscall完成。也就是说，AIOS 不是“收到请求就直接调函数”，而是先把请求转成系统调用对象，再交给调度器消费。

这里“等待syscall完成”也值得说清楚：原始请求线程并不是把请求扔进队列就结束了，而是会 syscall.start() 之后再 syscall.join()，等待 scheduler 真正执行完对应请求并把结果写回。所以从外部 HTTP 调用的视角看，/query 最终仍然是一次完整返回；只是内部实现上，已经被拆成了“入队 -> 调度 -> 执行 -> 回填结果”的过程。

之后，scheduler 消费队列，分别交给四大manager执行（LLMAdapter、StorageManager、MemoryManager、ToolManager）。

最后，执行完成后，再顺着沿路返回。syscall的状态被改为done，response被写回syscall对象，/query返回给Cerebrum API，agent代码拿到结果后继续运行。

流程：业务代码 -> Cerebrum API -> /query -> SyscallExecutor -> Queue -> Scheduler -> Manager -> Response -> 业务代码。

2. 四大核心组件如何工作

前面的“运行”解决的是横向总流程：请求怎样进入内核、怎样被调度、怎样返回结果。接下来更值得纵向看四大核心组件本身是如何工作的。这样再看 Memory 和 Storage，就不会只停留在“有这个 API”的层面。

(1) LLM：统一聊天、结构化输出与工具调用

LLM 这一条链的入口在 cerebrum.llm.apis，对外统一表现为 LLMQuery -> LLMResponse。上层常见调用包括：

llm_chat
llm_chat_with_json_output
llm_chat_with_tool_call_output
llm_call_tool
llm_operate_file

这些 API 最终都会被包装成 LLMQuery 发往 /query。进入内核后，execute_request() 会先看 action_type，再决定：

普通聊天是否直接走 LLM syscall
是否要先让模型产出 tool_calls
是否要把自然语言文件请求继续展开成 storage syscall

真正和模型后端交互的是 LLMAdapter。这一层负责：

根据配置选择模型 provider
处理 message_return_type="json" 之类的结构化输出约束
在支持原生 function calling 的后端上传递 tools + tool_choice="auto"
在不支持原生 tool calling 的模型上，把工具说明合并进 prompt 再解析输出

所以 LLM 组件的关键不是“简单调一次模型”，而是把不同形态的 LLM 能力统一收口到一个 runtime 组件里。

(2) Memory：运行期对象表 + 持久化向量检索

Memory 这一条链的入口在 cerebrum.memory.apis，统一表现为 MemoryQuery -> MemoryResponse。当前项目最常用的接口是：

create_memory
create_agentic_memory
search_memories

这些接口最终会变成 operation_type 不同的 MemoryQuery：

add_memory
add_agentic_memory
retrieve_memory

进入内核之后，execute_request() 会把它们交给 memory syscall，再由 scheduler 分发给 MemoryManager，最后实际落到 BaseMemoryManager。

BaseMemoryManager 当前采用的是一种“运行期内存态 + 持久化向量索引”的混合实现：

运行期对象表
它会维护一个 self.memories 字典，用来保存当前内核运行期间的 MemoryNote 对象。这意味着在一次内核启动周期内，memory 是持续可用的。
持久化向量检索层
同时它又会把 memory 内容写入 ChromaRetriever。Chroma 使用持久化目录，因此 memory 具备跨进程保存向量索引的能力。

add_memory / add_agentic_memory 的写入流程是：

把 MemoryQuery 转成 MemoryNote
将 content + metadata 写入 Chroma
同时把 MemoryNote 放进 self.memories

search_memories 的检索流程则是：

先让 ChromaRetriever 根据 query 做向量相似搜索
拿回相近文档的 doc_id
再用这些 doc_id 回头查 self.memories
最后组装成 MemoryResponse(search_results=...)

因此，当前 AIOS memory 不是“纯 Python 字典”，也不是“纯数据库”。更准确地说，它是：

以 self.memories 保存运行期完整对象，以 Chroma 保存可持续的语义检索索引。

这也解释了它的一个现实特点：

单次启动内，memory 连续性很好
跨重启时，向量索引是持续的
但完整对象表 self.memories 没有做彻底的重建回填，因此它更像“半持久化记忆系统”

AIOS 为了让 memory 子系统在受限环境里也能工作，给 Chroma 配了一个本地 embedding_function。LocalHashEmbeddingFunction 是采用了一种经典的「哈希嵌入」（feature hashing，又称 hashing‑trick）的变体，它分为以下几步：

特征提取：第一步先从文本中抽取两种类型的特征，第一类是分词/正则表达式，利用正则表达式提取英文单词、数字、中文等作为token的特征；然后去掉空白符，将字符串压紧，滑动窗口生成2-gram和3-gram。
有符号特征哈希：首先，我们对每个特征计算blake2b哈希，去输出的前4字节转成32位整数并对维度m（代码中是256）取模，得到该特征落入的“桶”的位置；接着，我们取哈希的第五字节，判断该字节的奇偶性来决定符号+1或者-1。（跟传统哈希相比，能消除内积的偏差）；最后，进行向量累积，初始化一个长度为m的零向量，对每个特征根据桶位置选择对应维度，将该维度加上sign(feature)，这样如果一个桶接收了多个特征会正负抵消或累加。
归一化：哈希累加后的向量各维度是整数。有些特征较长文本会产生更多的哈希次数，因此向量的长度（L2 范数）会较大。为了用余弦相似度或最大内积搜索来比较文本，需要消除不同文本长度的影响。代码最后计算向量的 L2 范数并除以该范数得到单位向量。

这种方法无需词表且支持动态语料（无状态），适合处理海量或流式数据，且内存占用小、中文友好。

这套设计对当前新闻项目已经足够，因为项目主要依赖的是“相似编辑决策能否被检索出来”，而不是把 memory 当作一套完全独立的业务数据库。

“新闻生成”不是一次纯文本补全，而是一条多阶段工作流。它既需要记住“这次运行里刚发生了什么”，也需要参考“过去类似题材是怎么处理的”。不过本次项目中，大多数“本次工作流上下文”是通过intermediate/*.txt/json、pipeline.run()的阶段结果、event回调、当前进程对象状态决定的。

(3) Storage：文件系统能力通过 LSFS 收口

Storage 这一条链的入口在 cerebrum.storage.apis，统一表现为 StorageQuery -> StorageResponse。常见接口包括：

mount
create_dir
create_file
write_file
read_file
list_dir
delete_file
delete_dir

这些请求进入内核后，会交给 StorageManager。当前仓库里 StorageManager 默认挂接的底层实现是 LSFS。

也就是说，storage 这一层最终负责的是真实文件系统动作：

建目录
读写文件
枚举目录
回滚文件版本

如果开启 use_vector_db，LSFS 还会为文件内容维护向量索引；此外它也会尝试连接 Redis 保存版本记录。因此 storage 这一层本质上是：

文件正文 + 语义检索 + 版本管理

不过在当前新闻项目里，storage 的主使用方式不是“让业务代码直接到处调 StorageQuery”，而是通过 ArtifactStore 进一步包装后再用。

我们需要storage层判断过去类似题材出现过没有，当时是通过还是拒绝，从而给现在的题材加减分，使用gate机制。

(4) Tool：工具资产与 runtime 调度链的结合点

Tool 这一条链的入口在 cerebrum.tool.apis，统一表现为 ToolQuery -> ToolResponse。最典型的接口是：

call_tool

它和 llm_call_tool 的区别在于：

call_tool(...) 是显式调用工具
llm_call_tool(...) 是先让 LLM 决定工具，再执行工具

当前新闻项目已经将 hot_api 和 web_search 这两类叶子能力下沉为本地工具，因此这条链在项目中已经真正用起来了。

tool 请求进入内核后，会被分发到 ToolManager。ToolManager 的职责主要是：

接收 tool_calls
加载工具实例
执行 tool.run(...)
返回结构化结果

而工具本体并不直接写在 ToolManager 里，而是通过：

cerebrum.tool.core 本地工具目录
registry.py 本地注册表
AutoTool.from_preloaded(...)

这一条链来加载。也就是说，Tool 组件真正解决的是：

如何把“工具资产”接入 runtime 调度系统，而不是停留在普通 Python 类调用。

这也是当前新闻项目近几轮重构里很重要的一点：业务编排仍由 NewsWorkflowApp 控制，但 hot_api 和 web_search 这类叶子能力已经开始真正走 AIOS 原生 Tool runtime 路径。

3. 扩展性

(1) 协议层拓展

首先，LLMQuery就预留了多种action_type，目前支持的chat、chat_with_json_output、chat_with_tool_call_output、call_tool、operate_file。这个action_type到底有什么作用呢？我们就拿chat_with_json_output为例子：

def llm_chat_with_json_output(
        agent_name: str, 
        messages: List[Dict[str, Any]], 
        base_url: str = aios_kernel_url,
        llms: List[Dict[str, Any]] = None,
        response_format: Dict[str, Dict] = None,
        require_kernel: bool | None = None,
    ) -> LLMResponse:

    query = LLMQuery(
        llms=llms,
        messages=messages,
        message_return_type="json",
        action_type="chat_with_json_output",
        response_format=response_format
    )
    try:
        return send_request(agent_name, query, base_url)
    except requests.RequestException:
        if _kernel_required(require_kernel):
            raise
        return _direct_openai_chat(
            agent_name=agent_name,
            messages=messages,
            llms=llms,
            response_format=response_format,
        )

为了方便看我删掉了长长的docstring。

message_return_type = "json" ，当LLMAdapter 真正发送请求的时候，会看这个字段，然后给模型的请求带上response_format = {"type":"json_object"}，让模型按照JSON对象返回。（这个response_format是OpenAI、LiteLLM这一类后端支持的参数，但是如果是本地HF模型，AIOS会退回成把schema指令拼进prompt。见llm_core的adapter和utils）。如果传入了更为具体的schema，它会覆盖上面的普通json_object，要求你返回符合schema的JSON。

只需要换输出输出约束的时候，我们可以只换message_return_type、response_format等，但是如果想要一个新的执行语义，我们就可以定义新的action_type（比如chat_with_rerank、chat_with_citation_check、vision_align_then_chat之类的），最少需要改以下几层：

LLMQuery的枚举
加一个SDK封装函数（仿照llm_chat_with_json_output()）
改内核分发：再syscall.py中，execute_request(...)加一个分支，比如：

elif query.action_type == "chat_with_rerank":
    # 先做一次预处理
    # 再调用 execute_llm_syscall
    return ...

如果需要新字段，要改/query重建逻辑，确保新字段不会在重建LLMQuery时候丢掉
如果需要底层模型的特殊支持，还需要改llm_core的LLMAdapter。

这个链路其实是这样的：handle_query -> execute_request -> execute_llm_syscall / execute_memory_syscall / ... -> _execute_syscall -> Queue -> Scheduler -> Manager。

(2) 执行模块拓展

LLMAdapter 初始化时会根据配置装载不同模型后端，并选择 routing strategy，这意味着：

模型配置可换
provider可换
路由策略可换

StorageManager后端有抽象口，但是仓库主要还是LSFS。

ToolManager 最后通过AutoTool.from_preloader(...)去拿工具实例，所以理论上可以拿到

本地工具
ToolHub工具
MCP工具

AutoTool.from_preloaded 按照 cerebrum.manager.tool.ToolManager.load_tool 中 local = False/True，启动不同的服务。远程工具会在hub下载放进cache目录然后动态import；本地工具会按照注册表 registry.py 加载。

(3) 调度层拓展性

scheduler 有一个明确的抽象基类，也就是说AIOS 把“请求如何排队和消费”单独抽成 scheduler，因此调度策略本身可以替换，而不需要改动 LLM / Memory / Storage / Tool 的具体实现。

前面已经说过，scheduler 不是直接处理Query，而是处理已经入队的Syscall。调度器抽象基类已经通过 process_llm_requests、process_memory_requests、process_storage_requests和process_tool_requests固定住了，我们只要任何scheduler实现这几个方法就能替换。

在 fifo_scheduler.py 中，每类请求各自一个线程，LLM 队列按时间窗口 batch，memory/storage/tool 基本是谁先入队谁先处理
在 rr_scheduler.py 中，同样也是四类队列，但是会给syscall设置time_slice，配合context_manager处理中断、续跑。

(4) 应用层拓展性

可以挂在新的应用层，构建新的APP (Agent Application)。

4. 优势与代价

我们新说说优势，AIOS把 llm / memory / storage / tool 都抽成同级能力，然后统一走：Query -> Syscall -> Queue -> Scheduler -> Manager，也就是说，不同类型资源实际上是走同一套处理范式。

然后，调度和执行也被解耦了。scheduler不直接实现业务，只负责消费队列和调度syscall。这样可以直接更换底层调度算法、LLM backend、storage backend之类的，不用动业务层代码。

此外，AIOS的核心抽象是syscall，天然将大模型调用、文件操作、记忆检索、工具执行看作同等地位的系统资源，更像agent OS。

对比LangGraph而言，LangGraph 和 AIOS 都不只是 prompt wrapper，都有自己的 runtime 设计；但 LangGraph 的 runtime 更偏向 graph/state/checkpoint 的应用编排体系，而 AIOS 的 runtime 更偏向 syscall/scheduler/manager 的内核式能力调度体系。前者更适合直接构建业务工作流，后者更适合作为统一 agent 能力底座。

5. 总结

现在，我们可以对内核总结一张总流程图：

flowchart TD
    A[业务代码 / Agent / App] --> B[Cerebrum API]
    B --> C[构造 Query<br/>LLMQuery / MemoryQuery / StorageQuery / ToolQuery]
    C --> D[send_request]
    D --> E["/query (FastAPI)"]

    subgraph KernelStartup[启动阶段]
        K1[读取 ConfigManager 配置]
        K2[initialize_llm_cores<br/>LLMAdapter]
        K3[initialize_storage_manager<br/>StorageManager -> LSFS]
        K4[initialize_memory_manager<br/>MemoryManager -> BaseMemoryManager]
        K5[initialize_tool_manager<br/>ToolManager]
        K6[initialize_scheduler<br/>FIFO / RR]
        K7[initialize_agent_factory]
        K1 --> K2 --> K3 --> K4 --> K5 --> K6 --> K7
    end

    E --> F[QueryRequest 类型恢复]
    F --> G[handle_query]
    G --> H[重建 Query<br/>补 llms / 保留字段]
    H --> I[SyscallExecutor.execute_request]

    I --> J{Query 类型 / action_type}
    J --> J1[LLMQuery]
    J --> J2[MemoryQuery]
    J --> J3[StorageQuery]
    J --> J4[ToolQuery]

    J1 --> L1[_execute_syscall]
    J2 --> L2[_execute_syscall]
    J3 --> L3[_execute_syscall]
    J4 --> L4[_execute_syscall]

    L1 --> Q1[LLM Queue]
    L2 --> Q2[Memory Queue]
    L3 --> Q3[Storage Queue]
    L4 --> Q4[Tool Queue]

    subgraph Scheduler[调度阶段]
        S1[FIFO / RR Scheduler]
        S1 --> P1[process_llm_requests]
        S1 --> P2[process_memory_requests]
        S1 --> P3[process_storage_requests]
        S1 --> P4[process_tool_requests]
    end

    Q1 --> P1
    Q2 --> P2
    Q3 --> P3
    Q4 --> P4

    P1 --> M1[LLMAdapter]
    P2 --> M2[MemoryManager]
    P3 --> M3[StorageManager / LSFS]
    P4 --> M4[ToolManager]

    M1 --> R[Response 回填到 Syscall]
    M2 --> R
    M3 --> R
    M4 --> R

    R --> T[syscall done / event set]
    T --> U["/query 返回结果"]
    U --> V[Cerebrum API 收到响应]
    V --> W[业务代码继续执行]

    J1 -. 特殊分支 .-> X1[call_tool<br/>LLM -> ToolQuery -> Tool]
    J1 -. 特殊分支 .-> X2[operate_file<br/>LLM解析 -> StorageQuery]
    J2 -. 特殊分支 .-> X3[add_agentic_memory<br/>analyze -> retrieve -> evolve -> add/update]

业务层

1. 介绍

比赛的时候，我是通过AutoGen hook直接在AIOS上挂载AutoGen框架，主线是让AutoGen的agent通过AIOS发送请求。这当然可以，因为AIOS做了相应的adapter，见cerebrum层的community/adapter/autogen_adapter.py。

比赛的要求是“设计一个由不少于4种智能体协作完成的复杂任务，该任务可分解为至少4个并行子任务并能自动分配。系统应实现包含至少3对智能体双向交互的协作流程，同时满足子任务间的依赖关系和执行顺序约束。”，我们想到的最直观方案就是一份综合新闻报的制作，因为它可以安排不同主题的Agent并行运行，反思、审阅，最终合并生成新闻报。

比赛之后，重新对Agent进行编排，不在走AutoGen，将其变成了显式的业务工作流编排器。现在的业务层已经不是基于 AutoGen 对话框架组织 agent，而是以 NewsWorkflowApp 为核心的显式工作流系统。它把新闻日报生产拆成固定阶段，由应用层统一编排，再调用各类 agent 完成具体任务：run_news_app.py -> cli.py -> config.py -> NewsWorkflowApp -> stages -> agents -> output/service。

2. 入口层

入口层分为三层：

壳层入口：接受启动命令
CLI适配层：解析参数，实例化应用
配置收敛层：将JSON配置转为稳定配置对象

入口层的核心职责不是执行业务，而是把“启动参数”和“原始配置文件”整理成一个可运行的应用对象。run_news_app.py 只是最外层壳入口，cli.py 负责命令行参数适配，config.py 负责将 config.json 转为类型化的 NewsAppConfig，最终在 NewsWorkflowApp.init 中完成环境变量、配置、运行目录、artifact store 与 workflow memory 的初始化。这样，真正的新闻业务流程可以从一个上下文完整的应用对象开始执行，而不是散落在多个脚本之中。

3. 编排层

编排层的核心是 pipeline.py 的NewsWorkflowApp。NewsWorkflowApp 是新闻业务的总编排器，它不直接承担每一步业务细节，而是负责组织阶段、调度 agent、管理中间产物、发出运行事件，并最终收口成一份日报。

首先，__init__ 负责装配一个可运行的业务应用，它分为七步：

校验模式，mode只能是parallel或serial
加载环境变量，load_project_env()（它在runtime_support.env）
加载业务配置，load_news_app_config(config_path)，这里定义了重试次数、各类别新闻个数等等业务超参数
读取API Key
确定工作流阶段顺序，self.workflow_stage_order
初始化运行支撑组件
确保目录存在

resume_from_existing 说明这条流水线支持“从中间继续跑”，不是只能从头开始。_components 这是后面懒加载 agent 的缓存池，说明 agent 实例不是提前全建好，而是按需创建。

然后，我们会进入 run() 总控循环。它的结构非常清晰：

发出启动事件，记录 mode、config_path、stages、resume_from_existing
准备输入产物，如果是恢复执行就保留上游产物并清理下游产物，否则清空intermediate临时文件夹。
按顺序循环执行，遍历self.workflow_stage_order，每个阶段都发stage_started，调_run_stage(stage_name)，记录耗时，完成后发stage_finished。
失败即终止，为了不推送半成品，一旦某阶段结果不是success，就抛出异常结束整个workflow。
成功统一收口，汇总总耗时、阶段耗时、阶段结果，生成results，发送run_finished。

简单来说，NewsWorkflowApp.run() 采用的是典型的**工作流编排器（workflow orchestrator）**写法：通过一个总控循环按阶段顺序驱动任务执行；阶段分发通过 dispatch table 完成；运行过程中的进度、耗时和结果则通过 event callback / observer hook 形式向外发射，供外层的 ecosystem 和 service 记录状态与构建在线观测能力。

4. 规则与桥接层

有了规则和桥接层，我们将一条会跑的agent流水线，变成了一条有编辑判断、底座接入策略、失败兜底的在线新闻系统。

(1) 规则层

首先，规则层 editorial.py，是新闻业务的编辑规则中心。这个函数将搜索文本解析成SearchSource，包含标题、链接、内容、域名、是否可信新闻源、是否低信号来源。

然后，evaluate_generation_input()会决定值不值得生成，也就是先gate，再写稿，它会根据以下信息给题材打分：

搜索结果是不是空的
有没有解析出有效信源
有没有可信新闻站点
是否大多是低信号来源
标题像不像词条/历史纪念/成语解释
内容像不像虚构剧情
memory 里有没有相似题材的历史通过/拒绝记录

接着，evaluate_publishability()决定要不要进日报。这是判断生成完了能不能发送，它主要看：

最终展示用的 sources 是否存在
最高信源匹配度够不够
平均匹配度够不够
是否没有可信来源、反而低信号很多
标题是否呈现虚构剧情特征
memory 对类似题材有没有历史反馈

最终，会有一个filter_display_sources()，这是对前端/日报展示服务进行过滤的，它：

去掉重复链接
去掉低相关来源
只保留足够高分的来源
最多保留有限条数

除此之外，route_story_category()允许重新分类； build_story_dedupe_key()做文本归一化、提取 lead、再结合事件关键词族生成 key 来去重；summarize_editorial_memory_feedback() 拿当前 topic 去匹配历史记忆，计算相似度，统计历史通过/拒绝数量，给当前决策加减分，产出理由。

规则层的核心不是“让 LLM 替我判断”，而是“把新闻性、可信度、重分类、去重这些编辑判断显式写成可解释规则”。

(2) 桥接层

桥接层决定业务层如何接入 AIOS / Cerebrum，但又不把业务代码直接耦死在底层 API 上。

它的核心思想不是“再实现一遍底层能力”，而是：

把通用的 kernel / SDK 能力重新包装成业务层容易调用的组件
把底层可能失败、超时、切换后端的复杂性收在中间层
让上层 workflow 只关心“我要不要存工件、要不要查记忆、要不要调工具”

在当前项目里，这层最典型的两个代表就是：

ArtifactStore：负责统一管理中间产物与最终日报文件
WorkflowMemoryRecorder：负责把通用 memory API 包装成“编辑决策记忆”组件

因此，桥接层更像一个适配与收口层：
它把 AIOS 底座能力转成新闻业务真正能稳定使用的接口。至于 Tool、Memory、Storage 分别是怎么接入的，下面放到 AIOS能力接入层 单独展开，这样层次会更清楚，也避免和后文重复。

5. AIOS能力接入层

(1) Tool 系统接入

业务编排仍由 NewsWorkflowApp 显式控制，但底层叶子能力开始逐步下沉为 AIOS 原生 tool 调用；同时保留 fallback。现在，我们将 hot_api 和 web_search 工具都注册为了 AIOS 内核可以直接使用的本地工具，当前主路径通过显式 call_tool(...) 进入 Tool runtime；只有在更开放的 agentic 场景下，才需要 llm_call_tool(...) 这类“由 LLM 决定工具调用”的原语。

我们可以简单看看关于tool的api。首先，llm_call_tool(...) 它并不是严格意义上的 ReAct。它本质上是一次“LLM 生成 tool_calls + runtime 执行工具”的单步 tool-calling 流程：在支持原生 function calling 的后端上，它通过 tools + tool_choice="auto" 让模型直接返回工具调用；在不支持原生 tool calling 的本地模型上，则通过 prompt 注入工具描述并把输出解析为 JSON 形式的 tool_calls。但它没有内建将工具结果再次回喂给模型的多轮 reasoning loop，因此更像 ReAct 的一个基础原语，而不是完整的 ReAct agent。llm_chat_with_tool_call_output(...)则是只决策不执行。

在本次新闻流水线中，因为tool都是固定随流水线调用，所以我们只会使用call_tool(...)。

(2) Memory 系统接入

Agent当中记忆系统非常关键，我们来深入看看AIOS是如何处理记忆层。

当前项目并没有让各个 agent 直接零散调用 AIOS memory API，而是先通过 memory.py (line 19) 中的 WorkflowMemoryRecorder 做了一层业务化封装。这样，业务层拿到的不是通用的 create_memory / search_memories，而是一个能够直接服务新闻工作流的记忆组件。WorkflowMemoryRecorder 的底层仍然调用 Cerebrum 的 memory API，包括create_memory、create_agentic_memory、search_memories等。

这些api对memory进行操控，让生成新闻具有弱先验经验而不是从头再来，从而保持可控性。引入 memory 的初衷是把过去的编辑经验，作为当前 gate 的一个参考项。

当前 AIOS-NP 中的 editorial memory，不是“让过去决定替代当前判断”，而是“把过去类似题材的处理经验，作为一个有限权重的编辑先验，去辅助当前基于搜索证据的新闻性判断”。

不过，为了避免自我强化偏见，我们让拒绝侧最多减18，通过侧最多加12，只是可控幅度的倾向修正项，真正决定的还是当前的证据。我们还给记忆系统加入了TTL，如果命中且过期，就不返回且删除。

(3) Storage / ArtifactStore 接入

Storage 和 Memory 在 AIOS 中是两套并列能力。Memory 更关注“过去见过什么、相似题材如何处理”，而 Storage 更关注“当前工作流产生的中间文件和最终产物如何保存、读取、枚举和删除”。因此，在新闻项目里，Storage 并不是“记忆的附属品”，而是负责承载整条流水线工件的独立系统。

当前项目并没有让业务代码直接零散调用 cerebrum.storage.apis。相反，它先在 runtime_support/artifacts.py 中抽象出统一的 ArtifactStore 接口，再由业务层统一依赖这层抽象。ArtifactStore 这一层暴露的不是底层 syscall，而是更贴近工作流的工件操作，包括：

write_text / write_json
read_text / read_json
exists
glob / glob_in
delete_file / delete_dir
describe

这一步很重要，因为它意味着业务层拿到的不是一堆零散的 storage API，而是一个“专门用来管理新闻工作流工件”的组件。

在具体实现上，项目提供了两套后端：

LocalArtifactStore
它是最简单、最稳定的本地实现。所有读写都直接落到本地文件系统中，适合作为默认模式，也适合作为 AIOS storage 不可用时的回退路径。对于新闻项目来说，这保证了即使底座暂时异常，日报流水线仍然可以在本机完整跑通。
AIOSStorageArtifactStore
它负责把 ArtifactStore 桥接到 AIOS storage 能力。这个类会优先尝试通过 Cerebrum 的 storage API 与内核交互，典型调用包括：
- mount
- create_dir
- write_file
- read_file
- list_dir
- delete_file
- delete_dir

也就是说，Storage 的真实调用链会变成：

ArtifactStore -> cerebrum.storage.apis -> StorageQuery -> /query -> StorageManager -> LSFS

这里值得注意的一点是：AIOSStorageArtifactStore 不是“纯粹依赖内核，失败就崩”，而是内置了 local_fallback。只要内核 storage 调用失败，它就会自动退回本地文件系统。这种设计非常适合当前新闻系统，因为它需要的是“在线可运行”，而不是为了展示 AIOS 而牺牲稳定性。

ArtifactStore 的运行时选择由 build_artifact_store() 和 get_artifact_store() 完成。当前项目会根据环境变量决定到底是：

使用本地后端
还是优先走 AIOS storage 后端

同时，get_artifact_store() 还会缓存默认实例，避免业务层反复重新创建存储对象。也就是说，对上层业务代码来说，Storage 后端是可切换的，但调用方式保持一致。

在新闻项目里，ArtifactStore 贯穿了几乎整条工作流：

pipeline.py 会用它保存 gate 结果、修正后的中间产物，并在运行开始时清理 intermediate
HotApiAgent 用它写入 hot_api.txt/json
SortAgent 用它写入各栏目分类文件
WebSearchAgent 用它写入 *_search.txt、*_image.txt 和搜索元数据
JudgeAgent、MakerAgent 用它写入新闻正文、sources、最终 TXT / JSON / HTML 日报
ecosystem.py 也通过同一套存储接口保存 run、state、metrics、snapshot 等在线运行记录

所以 Storage 在这里并不是“随手落盘”这么简单，而是：

整条新闻流水线的工件基础设施。

你也可以把它和 Memory 做一个非常清楚的对照：

Memory：保存“编辑经验”和“相似题材历史决策”
Storage：保存“这次工作流真正产出的文件工件”

当前这版 AIOS-NP 的 Storage 接入方式，本质上是一种非常工程化的折中：

业务层通过 ArtifactStore 保持接口稳定
能用 AIOS storage 时就尽量接入底座
AIOS storage 有问题时立即 fallback 到本地

这样一来，项目既保留了 AIOS 架构的接入路径，又不会因为底层存储链不稳定而让整套在线日报系统失去可用性。

6. 能力层

前面的编排层决定“阶段怎么走”，规则层决定“什么值得写、什么值得发”，AIOS能力接入层决定“底层 Tool / Memory / Storage 怎么接进来”。到了能力层，问题就变成了：

每一个具体的业务动作，到底由谁来完成。

因此，能力层可以理解为新闻流水线里的“执行者集合”。它们不再负责整体顺序，也不直接承担 runtime 细节，而是各自把某一种业务动作做深、做专，然后由 NewsWorkflowApp 在上层把它们组织起来。

从整体上看，这一层对应的正是新闻流水线的六个具体能力：

热榜获取
热点分类
Web 搜索
新闻生成
新闻审阅
最终成报

而且这六类能力并不是同一种 agent 形态：
有的更像工具封装器，有的更像业务处理器，有的则已经是一个小型 workflow。正因为这样，这一层才值得单独讲。

(1) 热榜获取能力：`HotApiAgent`

热榜获取能力由 agents/hot_api_agent/agent.py 中的 HotApiAgent 承担。它对应的是整条流水线最前面的输入阶段，也就是先把“今天值得看的热点池”取回来。

这一层现在做的不只是简单调 API。它已经优先通过显式 call_tool(...) 去调用下沉后的 hot_api 本地工具，如果 runtime tool 调用失败，再回退到原来的直接类调用。因此它的能力形态很典型：

对业务层来说，它是一个普通 agent
对 AIOS 来说，它背后已经尽量走原生 tool runtime

HotApiAgent 的输入非常简单：

API key
指定平台或平台列表
每个平台拉取多少条

输出则分成两份：

hot_api.txt：供后续分类阶段读取的文本版热榜
hot_api.json：保留结构化平台、话题和统计信息

所以它的价值不只是“抓到了热榜”，而是把多平台热点统一成后续阶段可消费的标准输入。

(2) 热点分类能力：`SortAgent`

分类能力由 agents/sort_agent/agent.py 中的 SortAgent 承担。它的任务不是“理解整篇新闻”，而是把热榜阶段抓回来的原始热点标题，整理成后续搜索阶段可以并行处理的领域输入。

这一层的输入是：

hot_api.txt
如果存在，也会优先读 hot_api.json

它会先提取、去重、清洗热点标题，然后尝试用 llm_chat_with_json_output(...) 做一次结构化分类。如果 LLM 分类没有返回有效结果，它还会回退到本地关键词规则分类。因此这一步本质上是：

LLM 分类优先，规则分类兜底。

分类完成后，它不会只停在内存里，而是把每个领域分别保存成独立文件，例如：

社会热点与公共事务_api.txt
科技与创新_api.txt
商业与经济_api.txt

这一步的意义非常大，因为它把“一个总的热点池”拆成了“按领域分组的待搜索列表”，也为后面 search / generate / review 的领域级并发打下了基础。

另外，SortAgent 在最终落盘前还会做一次：

route_story_category()
build_story_dedupe_key()

也就是说，它不是机械分类，而是已经和规则层开始联动，避免明显错误的栏目归属和重复题材扩散到后续阶段。

(3) 搜索能力：`WebSearchAgent`

搜索能力由 agents/web_search_agent/agent.py 中的 WebSearchAgent 承担。它的输入已经不是“所有热点”，而是前一步分类后每个领域下的一组热点主题。

这一层很值得讲的点有两个：

第一，它不是只搜一条，而是按分类、按 topic 批量处理。
第二，它虽然已经把 web_search 下沉成了 AIOS 本地工具，但仍然保留了单 topic 子进程隔离。

也就是说，现在真实链路更像：

WebSearchAgent -> topic_worker 子进程 -> 优先 call_tool("web_search") -> ToolManager -> 本地工具

如果 runtime tool 路径失败，再回退到原来的直接搜索工具调用。

这种设计非常工程化，因为它同时兼顾了两件事：

逐步下沉能力到 AIOS tool runtime
不牺牲原来“单 topic 出错不会拖死整轮搜索”的隔离性

这一层的输出也不是一个总结果对象，而是一组标准工件：

*_search.txt
*_image.txt
搜索元数据文件

其中 *_search.txt 进入生成阶段，*_image.txt 则为后面日报插图能力提供候选来源。
所以搜索能力本质上是：

从“主题”生产“可生成、可展示、可追溯”的搜索工件。

(4) 新闻生成能力：`ParallelNewsTest + Title/Summary/Content/Judge`

新闻生成能力是这一层里结构最特别的一类。它不是单个 agent 完成，而是由 agents/news_generation_agent 下的一组子 agent 协同完成。当前主入口由 ParallelNewsTest 承担。

这一层的输入是：

单个 topic 对应的 *_search.txt
topic 名称
domain 分类

真正的生成过程不是“一次 llm_chat 直接出整稿”，而是并行拆成三部分：

TitleAgent 生成标题
SummaryAgent 生成摘要
ContentAgent 生成正文

这三个部分会并行运行，然后各自交给 JudgeAgent 做局部评审；如果某一部分没通过，还会按反馈单独重试。只有标题、摘要、正文全部通过局部评审，整篇稿子才会被保存成 _news.txt 和 _sources.json。

因此，这里的“生成能力”并不是一个简单生成器，而是：

一个“并行生成 + 局部评审 + 局部重试”的微型生产线。

更重要的是，在当前项目里，这一层之前已经先经过编排层的 generation_gate。也就是说，它只负责“把值得写的题材写好”，而不是负责决定“该不该写”。这让能力边界变得非常清楚。

(5) 审阅能力：`WorkflowAgent`

审阅能力由 agents/workflow_agent/agent.py 中的 WorkflowAgent 承担。这一层和前面的生成能力不同，它更像一个小型的 agent workflow，而不是一个单步处理器。

它的输入是：

_news.txt 新闻稿
所属领域 domain

然后它会拉起一组专门的审阅 agent，包括：

描述优化
禁用词检测
结构优化
事实核查
最终判断
以及对应领域专家

因此，这一层并不是“再润色一下”这么简单，而是：

围绕成稿再跑一轮质量工作流。

在运行方式上，它会先让领域专家做初步处理，然后再进入审阅 workflow。也就是说，审阅阶段并不是单纯用一个通用 judge，而是同时结合：

通用质量检查
领域专家视角

最后通过的稿件会输出成 *_reviewed.txt。
所以能力层里，WorkflowAgent 是最接近“多 agent 协作子系统”的一个点，它也保留了你比赛时期那种“agent 协作”的味道，只不过现在被收进了更稳定的业务主线里。

(6) 成报能力：`MakerAgent`

最后的成报能力由 agents/maker_agent/agent.py 中的 MakerAgent 承担。它不是单纯把几篇文章拼起来，而是负责把整条流水线前面产出的内容，收口成可以真正面向前端和用户展示的日报产品。

它会做的事情包括：

收集各栏目的 _news.txt / _reviewed.txt
读取对应 sources.json
再次做 publishability 判断
去重
栏目重路由
过滤展示信源
生成日报总览和亮点
输出最终的 txt / json / html

也就是说，它不是一个简单的“renderer”，而是：

最终出版装配器。

它还负责给日报打上时间戳，因此每次运行都会产出新的：

新闻报_时间戳.txt
新闻报_时间戳.json
新闻报_时间戳.html

这一步很关键，因为从 MakerAgent 开始，系统产出的东西已经不再只是“给下一步 agent 用的中间文件”，而是前端、博客页面、dashboard、API 都可以直接消费的最终内容。

小结

如果把这一层再压缩成一句话，那么能力层真正做的事情就是：

把新闻工作流拆成一组边界清晰的业务执行者：有人负责抓输入，有人负责整理主题，有人负责生产搜索工件，有人负责并行生成，有人负责审阅把关，最后再由专门的出版器完成成报。

因此，当前 AIOS-NP 的能力层并不是“很多 agent 堆在一起”，而是一组角色明确、输入输出稳定、能被编排层可靠调度的业务执行组件。也正因为这些组件边界足够清楚，前面的编排层、规则层和 AIOS 接入层才能真正发挥作用。

7. 在线化层

如果说前面的编排层、规则层、能力层解决的是“日报怎么生成”，那么在线化层解决的就是：

这套能力如何持续在线运行、如何被调度、如何被观察、又如何被前端与外部系统消费。

也正因为有了这一层，AIOS-NP 才不再只是一个“跑一次就结束”的比赛型脚本，而是变成了一个长期在线的新闻系统。

(1) 运行管理：`ecosystem.py`

在线化层最核心的文件是 apps/news_app/ecosystem.py。它并不直接参与新闻生成细节，而是站在工作流外面，负责管理“每一次运行”。

这一层里最关键的角色是 NewsRunManager。它的职责可以概括为：

接受一次新的运行请求
判断当前是否已有任务在跑
为这次任务分配 run_id
启动后台线程执行 NewsWorkflowApp
持续收集运行事件
将 run / state / metrics / snapshot 落盘保存

也就是说，NewsRunManager 不是新闻生产者，而是：

新闻工作流的运行控制器。

当前项目里，真正触发一轮工作流的入口就是：

手动触发：trigger_run(...)
启动触发：source="startup"
调度触发：source="scheduler"

一旦进入 _execute_run(...)，它会创建一个真正的 NewsWorkflowApp，并把 event_handler 传进去。这样前面编排层持续 emit 出来的：

run_started
stage_started
stage_finished
run_finished

这些事件，就会被在线层接住，进一步更新这次 run 的阶段摘要、状态文件和指标文件。

因此，这一层的重要意义在于：

它把编排层里“正在发生什么”持续变成“系统外面可观察的运行记录”。

(2) 状态持久化：run / state / metrics / snapshot

如果只有 NewsRunManager，系统还只是“能后台跑”。真正让它变成在线系统的，是它会把运行过程中的几个关键视图长期保存下来：

run
state
metrics
snapshot

这几类数据的作用并不相同。

run 记录一轮任务的基本身份信息，比如：
- run_id
- mode
- source
- created_at / started_at / finished_at
- 最终成功还是失败
state 更偏“当前工作流走到哪一步”，例如：
- 各阶段状态
- 是否已有 report
- 哪些文件已经生成
metrics 更偏“本轮结果质量如何”，例如：
- 文章数量
- 来源数量
- 高亮数量
- 各阶段耗时
snapshot 更偏“给外部系统直接消费的最新快照”，它会把运行结果收敛成一份更适合前端和 API 消费的数据视图。

因此，在线化层不是只保存“日志”，而是在主动构建：

运行视图、状态视图、指标视图和结果快照视图。

这也是为什么博客前端、dashboard、latest report API 最后都能建立在它之上。

(3) 自动调度：`NewsScheduler`

ecosystem.py 里的第二个关键角色是 NewsScheduler。它的任务不是“生成新闻”，而是：

根据配置，让新闻系统在规定时间自动启动一轮 workflow。

它会根据：

auto_run_enabled
auto_run_time
auto_run_mode

决定：

是否开启自动调度
每天什么时候触发
触发时采用串行还是并行模式

调度器的运行逻辑其实很朴素：

服务启动时拉起后台轮询线程
每隔一段时间检查当前时间
如果到达设定时刻，且当天还没跑过，就自动调用 trigger_run(...)

这里最值得讲的点，不是“会定时”，而是：

调度能力并没有侵入业务 workflow 本身，而是作为在线层额外包住了编排层。

因此，NewsWorkflowApp 仍然专注于“怎么跑一轮新闻日报”，而 NewsScheduler 只负责“什么时候启动它”。这种分层非常干净。

(4) 服务暴露：`service.py`

如果说 ecosystem.py 解决的是“怎么管理系统内部运行”，那么 apps/news_app/service.py 解决的就是：

怎么把这套运行能力通过 Web 服务暴露出去。

这一层使用 FastAPI，把新闻系统包装成一个长期可访问的服务。它在 lifespan 中完成几件事：

加载环境变量
初始化 NewsRunManager
初始化 AgentRegistryManager
初始化 NewsScheduler
在服务启动时自动启动调度器

这样，服务一旦起来，就不是一个空壳，而是一套已经带有：

运行管理器
agent 注册能力
自动调度器

的在线系统。

对外暴露的接口大体可以分成几类：

健康与状态接口
- /health
- /api/ecosystem/status
运行管理接口
- /api/ecosystem/runs
- /api/ecosystem/runs/{run_id}
- /api/ecosystem/runs/{run_id}/state
- /api/ecosystem/runs/{run_id}/metrics
结果消费接口
- /api/ecosystem/news/latest
- /api/ecosystem/reports/latest/html
- /api/ecosystem/output/report/latest
agent 管理接口
- /api/agents
- /api/agents/register
- /api/agents/{agent_id}/run

因此，service.py 的定位不是“又写一套业务逻辑”，而是：

把内部工作流、运行状态和最终日报包装成外部系统可直接访问的 HTTP 能力。

(5) 可视化观察：`dashboard.py`

除了 API，当前系统还提供了一套 dashboard。它由 apps/news_app/dashboard.py 负责生成 HTML。

这部分很有产品意味，因为它不是单纯把 JSON 原样打印出来，而是把在线系统最重要的几个视角整理成可读界面：

当前是否有任务在跑
最新一次运行状态
最近几次 run
各阶段成功/失败与耗时
最新 snapshot / metrics
最新 report 的访问入口

也就是说，dashboard 的作用不是“替代 API”，而是：

给开发者、维护者和演示场景提供一个更直观的系统观察面。

这点对于你的项目很重要，因为它进一步说明：

AIOS-NP 已经不是“在终端里跑完就算结束”，而是开始具备真正的运维与展示面。

(6) 历史保留与 latest 视图

在线化层还有一个很容易被忽略、但非常实用的设计：
系统既保留历史日报，又维护 latest 视图。

例如：

output/ 目录下会持续保留历史 新闻报_时间戳.txt/json/html
ecosystem/ 下也会保留历史 run、state、metrics、snapshot

与此同时，服务层又提供：

latest_snapshot()
latest_state()
latest_metrics()
latest_output_report()

这些“最新视图”接口。

所以这套系统并不是“历史和最新只能二选一”，而是：

一方面保留完整历史，另一方面对外统一暴露一个便于前端消费的 latest 入口。

这也是为什么博客前端现在既能默认展示最新日报，也能进一步扩展成查看不同日期、不同时间的历史日报。

小结

如果把在线化层再压缩成一句话，那么它真正完成的事情就是：

在编排层外面补上运行管理、调度、状态持久化、服务暴露和可视化观察，使新闻系统从“一次性 workflow”真正升级成“持续在线可提供服务的应用”。

因此，当前 AIOS-NP 的在线化层，并不是附属功能，而是把比赛时期的新闻流水线真正产品化、服务化的关键一步。

Docker 入门：镜像、容器、数据卷、网络到 Compose

Mon, 06 Apr 2026 00:00:00 GMT

Docker 教程

这篇笔记把我看视频时记下的要点，和公众号里的系统化内容，整理成了一篇从概念到实操都比较完整的 Docker 入门教程。目标不是把所有命令死记硬背，而是先建立一条清晰主线：

镜像 -> 容器 -> 数据卷 -> 网络 -> Dockerfile -> Compose

只要这条主线理顺了，后面的命令基本都能串起来。

1. Docker 是什么

Docker 是一种容器化技术。它可以把应用程序、依赖库、运行环境和配置一起打包，让应用在不同机器上都以尽量一致的方式运行。

Docker 想解决的核心问题是：

本地能跑，换台机器就跑不起来
部署过程复杂，环境经常配错
不同项目依赖冲突
手动安装软件、配置环境太繁琐

Docker 的思路是：把应用运行所需的一切，尽量放进一个独立的容器环境里。

1.1 为什么 Docker 很流行

Docker 常见的优点有：

轻量：容器共享宿主机内核，比虚拟机小很多，启动也更快
可移植：同一个镜像可以在不同机器上运行
隔离性：不同容器之间尽量互不干扰
标准化：构建、分发、运行都有统一命令和工具链

1.2 Docker 和虚拟机的区别

对比项	Docker 容器	虚拟机
本质	共享宿主机内核的进程级隔离	模拟完整硬件并运行独立操作系统
启动速度	很快，通常秒级甚至更快	相对较慢
资源占用	较小	较大
隔离性	足够强，但通常弱于虚拟机	更强
适用场景	应用部署、开发测试、微服务	强隔离、多操作系统环境

一句话记忆：

虚拟机更像“整台电脑里的另一台电脑”
Docker更像“隔离出来的应用运行沙盒”

2. Docker 的核心概念

Docker 最重要的 6 个概念如下：

概念	含义	可以怎么理解
镜像（Image）	创建容器的模板	类似“安装包”或“快照”
容器（Container）	镜像运行后的实例	类似“安装出来并正在运行的软件”
Dockerfile	构建镜像的脚本	类似“自动化装机说明书”
仓库（Registry）	存放镜像的地方	类似“应用商店 / 镜像服务器”
数据卷（Volume）	持久化数据的方式	类似“外挂硬盘 / 数据目录”
网络（Network）	容器之间通信的方式	类似“局域网”

理解 Docker 时，最容易混淆的是镜像和容器：

镜像是静态的，只读的模板
容器是动态的，运行中的实例

比如：

nginx 镜像可以创建很多个容器
每个容器都有自己的运行状态、日志、网络配置

3. 安装与验证

因为我平时主要在 macOS / Windows 上使用 Docker，这里以 Docker Desktop 为主。

3.1 安装方式

macOS：安装 Docker Desktop，或者用 Homebrew
Windows：安装 Docker Desktop

macOS 常见安装命令：

brew install --cask docker

安装完成后，需要手动启动 Docker Desktop。只安装命令行还不够，后台服务必须真的运行起来。

3.2 验证是否安装成功

docker --version
docker info

更推荐第一次就跑一下官方测试镜像：

docker run hello-world

如果能看到 Docker 输出的欢迎信息，说明 Docker 已经安装并运行正常。

3.3 架构差异补充

在 macOS 上，我会经常遇到镜像架构问题。因为现在很多 Mac 是 ARM64，但有些镜像默认是 AMD64。

这时可能会看到类似：

docker pull --platform linux/amd64 nginx

这条命令的意思是：强制拉取指定平台架构的镜像。

Docker Desktop 往往会借助 QEMU 去兼容不同架构，但并不是所有镜像都适合跨架构运行，所以：

能用原生 ARM64 镜像最好
不行再考虑 --platform

3.4 国内镜像源

由于担心镜像源在海外访问缓慢，对于docker desktop来说，我们可以在这里配置一下国内源：

4. 镜像：Docker 的起点

镜像是创建容器的模板。几乎所有 Docker 操作，都是围绕镜像开始的。

4.1 镜像名怎么读

下面这条命令：

docker pull docker.io/library/nginx:latest

可以拆成三部分：

docker.io：仓库注册表地址（registry）
library/nginx：镜像仓库（repository）
latest：标签（tag）

大多数情况下都可以简写成：

docker pull nginx

因为官方仓库和 latest 标签都可以省略。

4.2 常用镜像命令

docker pull nginx
docker pull nginx:1.27
docker images
docker search mysql
docker inspect nginx
docker history nginx
docker tag nginx:latest my-nginx:v1
docker rmi nginx
docker save -o nginx.tar nginx:latest
docker load -i nginx.tar
docker login
docker push your_username/my-image:1.0

4.3 镜像命令怎么理解

命令	作用
`docker pull`	拉取镜像
`docker images`	查看本地镜像
`docker search`	搜索公共镜像
`docker inspect`	查看镜像详细信息
`docker history`	查看镜像分层历史
`docker tag`	给镜像打新标签
`docker rmi`	删除镜像
`docker save / load`	导出 / 导入镜像
`docker login / push`	登录并推送镜像到仓库

4.4 镜像修改的本质

如果只是临时修改容器里的文件，那只是改了容器，不是改了镜像。

真正推荐的“修改镜像”方式是：

写 Dockerfile
用 docker build 重新构建镜像

5. 容器：镜像运行之后的实例

镜像只是模板，真正运行起来的是容器。

5.1 `docker run` 是最核心的命令

docker run -d -p 80:80 --name nginx-container nginx

这条命令做了几件事：

如果本地没有 nginx 镜像，会先自动拉取
基于镜像创建容器
把容器放到后台运行
把容器的 80 端口映射到宿主机的 80 端口
给容器起名叫 nginx-container

5.2 `docker run` 常用参数

参数	作用
`-d`	后台运行
`-p 宿主机端口:容器端口`	端口映射
`--name`	给容器起名字
`-it`	交互式进入容器
`-v`	挂载目录或卷
`--rm`	容器停止后自动删除
`-e`	传环境变量
`--network`	指定网络
`--restart always`	自动重启策略
`-u`	指定用户运行

5.3 常用容器命令

docker run -d -p 80:80 nginx
docker run -d --name my_container -p 8080:8080 tomcat:latest
docker run -it --rm ubuntu /bin/bash
docker run -d --restart always nginx

docker ps
docker ps -a
docker ps -l
docker ps -q
docker ps -aq

docker stop nginx-container
docker start nginx-container
docker create nginx
docker rm nginx-container
docker rm -f nginx-container

docker logs nginx-container
docker logs -f nginx-container
docker stats
docker inspect nginx-container
docker exec -it nginx-container /bin/bash

5.4 这些命令最容易混淆的点

`run`、`create`、`start`

docker run：创建并启动
docker create：只创建，不启动
docker start：启动一个已经存在但停止了的容器

所以如果你反复执行 docker run，就会不断创建新容器；而不是“重启旧容器”。

`ps` 和 `ps -a`

docker ps：只看正在运行的容器
docker ps -a：看所有容器，包括退出的

`logs` 和 `exec`

docker logs：看容器输出日志
docker exec：进入容器内部执行命令

5.5 进入容器内部

最常用的是：

docker exec -it nginx-container /bin/bash

如果镜像比较轻量（例如 Alpine），里面可能没有 bash，要改成：

docker exec -it nginx-container /bin/sh

6. 数据持久化：Bind Mount 和 Volume

容器有一个很重要的特点：容器删了，容器里的数据可能也就没了。

所以数据库、上传文件、缓存目录等，通常都不能只存在容器内部，而需要挂载到外部。

6.1 Bind Mount：绑定宿主机目录

docker run -v /宿主机路径:/容器路径 nginx

例如：

docker run -d -p 80:80 -v /Users/owen/site:/usr/share/nginx/html nginx

特点：

宿主机路径可见、好找
修改宿主机文件，容器里会同步
很适合开发环境

6.2 Volume：命名卷

docker volume create mydata
docker run -d -v mydata:/data nginx
docker volume inspect mydata
docker volume ls
docker volume rm mydata
docker volume prune -a

特点：

路径由 Docker 管理
更适合持久化数据
不依赖我手动维护某个宿主机目录

6.3 Bind Mount 和 Volume 的区别

类型	写法	适合场景
Bind Mount	`-v 宿主机路径:容器路径`	开发环境、直接编辑文件
Volume	`-v 卷名:容器路径`	持久化数据、数据库

7. Dockerfile：如何制作自己的镜像

Dockerfile 可以理解成“制作镜像的图纸”。

你不需要手工进入容器修改环境，而是把构建步骤写进 Dockerfile，让 Docker 自动构建镜像。

7.1 一个最小可运行示例

FROM python:3.13-slim

WORKDIR /app

COPY . .

RUN pip install -r requirements.txt

# 这是一个暴露容器端口的提示，不会自动映射端口
EXPOSE 8000

# CMD 只能有一个最终生效的定义
CMD ["python3", "main.py"]

构建命令：

docker build -t my-python-app:1.0 .

运行命令：

docker run -d -p 8000:8000 my-python-app:1.0

7.2 Dockerfile 常用指令

指令	作用
`FROM`	指定基础镜像
`WORKDIR`	指定工作目录
`COPY`	复制文件到镜像中
`RUN`	构建镜像时执行命令
`ENV`	设置环境变量
`EXPOSE`	声明容器监听端口
`CMD`	指定容器启动默认命令
`ENTRYPOINT`	指定容器主命令

7.3 `CMD` 和 `ENTRYPOINT` 的区别

CMD：默认命令，容易被 docker run 后面的命令覆盖
ENTRYPOINT：主命令，通常不会被简单覆盖

入门阶段先记住：

大多数场景先会用 CMD
需要更强约束时再考虑 ENTRYPOINT

8. Docker 网络

Docker 网络的作用是让容器之间可以互相通信，同时和宿主机网络进行隔离。

8.1 常见网络模式

模式	含义
bridge	默认桥接模式，最常见
host	容器直接使用宿主机网络
none	不分配网络

8.2 常用网络命令

docker network ls
docker network create network1
docker network rm network1
docker run -d --network host nginx

8.3 为什么自定义网络很重要

默认情况下，容器在 bridge 网络中可以通过 IP 通信。但如果你自己创建一个网络，例如：

docker network create network1

然后让多个容器都加入这个网络，它们就可以通过容器名互相访问，这比记 IP 更方便。

这点在数据库容器 + Web 容器配合时非常重要。

9. Docker Compose：管理多个容器

如果一个应用只需要一个容器，那么 docker run 就够了。

但一旦项目里有多个容器，例如：

web
db
redis

你就会发现手写一长串 docker run 特别麻烦。这时就轮到 Docker Compose 出场了。

9.1 Compose 是什么

Docker Compose 是一种多容器编排工具。
它用一个 YAML 文件把多个容器的配置写在一起，然后一条命令统一启动。

一句话：

docker run 管单个容器
docker compose 管一组相关容器

9.2 Compose 和 `docker run` 的区别

对比项	`docker run`	`docker compose up`
管理对象	单个容器	一组服务
配置方式	命令行参数	`docker-compose.yml` / `compose.yaml`
适合场景	临时测试、单容器运行	多容器项目、开发环境
可维护性	命令长了后难维护	配置集中，易于团队协作

9.3 从两条 `docker run` 到一个 Compose 文件

下面这组命令用于启动 MongoDB 和 Mongo Express：

docker network create network1

docker run -d \
  --name my_mongodb \
  -e MONGO_INITDB_ROOT_USERNAME=name \
  -e MONGO_INITDB_ROOT_PASSWORD=pass \
  -v /my/datadir:/data/db \
  --network network1 \
  mongo

docker run -d \
  --name my_mongodb_express \
  -p 8081:8081 \
  -e ME_CONFIG_MONGODB_SERVER=my_mongodb \
  -e ME_CONFIG_MONGODB_ADMINUSERNAME=name \
  -e ME_CONFIG_MONGODB_ADMINPASSWORD=pass \
  --network network1 \
  mongo-express

等价的 Compose 文件可以写成：

services:
  my_mongodb:
    image: mongo
    environment:
      MONGO_INITDB_ROOT_USERNAME: name
      MONGO_INITDB_ROOT_PASSWORD: pass
    volumes:
      - /my/datadir:/data/db

  my_mongodb_express:
    image: mongo-express
    ports:
      - "8081:8081"
    environment:
      ME_CONFIG_MONGODB_SERVER: my_mongodb
      ME_CONFIG_MONGODB_ADMINUSERNAME: name
      ME_CONFIG_MONGODB_ADMINPASSWORD: pass
    depends_on:
      - my_mongodb

这里有两个很重要的点：

Compose 会自动为项目创建默认网络，所以通常不用手动 docker network create
同一个 Compose 项目里的服务，默认可以通过服务名互相访问

9.4 Compose 常用命令

docker compose up -d
docker compose down
docker compose stop
docker compose start
docker compose ps
docker compose logs
docker compose logs -f
docker compose exec web sh
docker compose -f 路径/compose.yaml up -d

9.5 这些 Compose 命令怎么理解

命令	作用
`docker compose up -d`	后台启动所有服务
`docker compose down`	停止并删除服务相关容器和网络
`docker compose stop`	只停止，不删除
`docker compose start`	启动已存在的服务
`docker compose ps`	查看服务状态
`docker compose logs -f`	持续查看日志
`docker compose exec`	进入某个服务容器
`docker compose -f 文件名 ...`	指定 Compose 文件路径

9.6 Compose 适合什么场景

Compose 属于轻量级编排工具，适合：

个人开发
本地调试
单机部署
小规模项目

如果是企业级大规模集群编排，通常会进一步接触 Kubernetes。

LangGraph 入门：StateGraph、工具调用与记忆初探

Sat, 04 Apr 2026 00:00:00 GMT

这篇更像“先把地图打开”。里面会提前碰到工具、记忆、human-in-the-loop 和 time-travel，但重点是先建立 LangGraph 整体长什么样的直觉。

1. 介绍

LangGraph 专为希望构建强大、适应性强的 AI 智能体的开发者而设计。比起LangChain，它支持更为复杂的自定义的操作。

你可能会疑惑，我已经有了create_agent + middleware，啥场景不够用？有的兄弟有的，如果出现下面这些信号，就需要升级到LangGraph了！

你需要明确的分支/循环（不是“让模型自己决定”）。
你需要并行流程（fan-out/fan-in）。
你要在固定步骤做人审、打断、恢复。
你要可回放、可分叉、可精确恢复（durable execution）。
你发现 middleware 里 if/else 越来越多，逻辑难维护。

当然，最常见的其实是混用两个，我们将create_agent作为能力节点，放进LangGraph中，而LangGraph负责全局编排。接下来，我们来简单入门一下LangGraph。

2. 构建一个聊天机器人

我们先安装一下两个所需要的软件包，分别是langgraph和langsmith：

pip install -U langgraph langsmith

紧接着，我们用StateGraph构建聊天机器人，这个聊天机器人直接回复用户的消息。一个 StateGraph 对象将我们的聊天机器人结构定义为“状态机”。我们将添加节点来表示 LLM 和聊天机器人可以调用的函数，并添加边来指定机器人应如何在这些函数之间进行转换。

from typing import Annotated

from typing_extensions import TypedDict

from langgraph.graph import StateGraph, START
from langgraph.graph.message import add_messages


class State(TypedDict):
    # Messages have the type "list". The `add_messages` function
    # in the annotation defines how this state key should be updated
    # (in this case, it appends messages to the list, rather than overwriting them)
    messages: Annotated[list, add_messages]


graph_builder = StateGraph(State)

我们的图现在可以处理两个关键任务

每个节点都可以接收当前状态作为输入，并输出状态的更新。
对消息的更新将追加到现有列表而不是覆盖它，这得益于与 Annotated 语法一起使用的预构建 add_messages 函数。

现在，我们通过StateGraph对加节点加边，就可以构成一个可以运行的图，完整代码如下：

import os
from typing import Annotated

from dotenv import load_dotenv
from langchain.chat_models import init_chat_model
from typing_extensions import TypedDict

from langgraph.graph import END, START, StateGraph
from langgraph.graph.message import add_messages

BASE_DIR = os.path.dirname(__file__)
load_dotenv(os.path.join(BASE_DIR, ".env"))


class State(TypedDict):
    messages: Annotated[list, add_messages]


graph_builder = StateGraph(State)

llm = init_chat_model(
    "openai:gpt-4o-mini",
    base_url=os.environ.get("QIHANG_BASE_URL"),
    api_key=os.environ.get("QIHANG_API"),
)


def chatbot(state: State):
    # 这里必须返回 "messages"，否则不会写入 State.messages
    return {"messages": [llm.invoke(state["messages"])]}


# 将模型集成到节点
graph_builder.add_node("chatbot", chatbot)

# 添加入口和结束
graph_builder.add_edge(START, "chatbot")
graph_builder.add_edge("chatbot", END)

# 编译图
graph = graph_builder.compile()


def visualize_graph() -> None:
    graph_obj = graph.get_graph()

    png_path = os.path.join(BASE_DIR, "graph.png")
    try:
        with open(png_path, "wb") as f:
            f.write(graph_obj.draw_mermaid_png())
        print(f"[visualize] 已保存 PNG: {png_path}")
    except Exception as e:
        print(f"[visualize] 生成 PNG 失败: {e}")
        print("[visualize] Mermaid 文本如下：")
        print(graph_obj.draw_mermaid())


if __name__ == "__main__":
    visualize_graph()

    # LangGraph + add_messages 支持这种 message shorthand
    result = graph.invoke({"messages": [("user", "你好，介绍一下你自己")]})

    print("\n===== Final State =====")
    for msg in result["messages"]:
        msg.pretty_print()

add_node接受的是一个可调用对象，普通函数符合了这个要求。而State类，是我们的全局Schema。我们用TypedDict进行了定义，添加了消息历史的更新方式messages: Annotated[list, add_messages]。除了定义更新规则之外，还可能会定义状态结构、字段类型。

这就是最基本的机器人创建啦，只有一个节点，两条边，model被invoke之后返回的是一个AIMessage，详见之前LangChain的核心组件Messages。

另外一个重要的点，就是StateGraph种，node的返回值。这里是返回dict对状态就行增量更新（返回要修改的字段），当然也可以返回Command，用于更新状态+控制流跳转，比如：Command(update={"x": 1}, goto="next_node")或者graph=Command.PARENT（子图场景）。

3. 添加工具

(1) tool.invoke()

我们用Tavily API试试工具效果，这是一个让llm拥有网络搜索能力的工具。我们先from langchain_tavily import TavilySearch（记得安装依赖和加载API），然后创建工具tool = TavilySearch(max_results = 2)，直接invoke，得到结果如下：

{
  "query": "LangGraph里面的node是什么？",
  "follow_up_questions": null,
  "answer": null,
  "images": [],
  "results": [
    {
      "url": "https://www.cnblogs.com/luzhanshi/articles/19141931",
      "title": "Ch.7 LangGraph底层原理与基础应用入门 - 博客园",
      "content": "接下来的步骤是向这个图中添加节点和边，完善和丰富图的内部执行逻辑。 2.3 Nodes. 在 LangGraph 中，节点是一个 python 函数（sync 或async ），接收",
      "score": 0.99996924,
      "raw_content": null
    },
    {
      "url": "http://www.bilibili.com/read/cv42850203/",
      "title": "LangGraphAgent开发实战- 哔哩哔哩",
      "content": "... 里面添加Node才能形成有向有环图. Node. Node是LangGraph的节点，每个节点代表一个函数或一个计算步骤。 你可以定义节点来执行特定任务，例如处理输入、做出决策或与外部",
      "score": 0.99996495,
      "raw_content": null
    }
  ],
  "response_time": 1.07,
  "request_id": "13235394-9b4d-4a56-a08e-3c6f4024f03c"
}

也就是说，tool被invoke之后返回的是工具函数本身的返回值，我们在LangChain中，曾经采用的方法是将其包装为ToolMessage，再继续给模型推理。

(2) bind_tools()

而在LangChain中关于Model的介绍中，我们学习了给模型绑定工具的方法bind_tools，我们可以直接给模型bind一个工具，加入到StateGraph中：

from typing import Annotated

from typing_extensions import TypedDict

from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]

graph_builder = StateGraph(State)

# Modification: tell the LLM which tools it can call
# highlight-next-line
llm_with_tools = llm.bind_tools(tools)

def chatbot(state: State):
    return {"messages": [llm_with_tools.invoke(state["messages"])]}

graph_builder.add_node("chatbot", chatbot)

这种方式是，默认由模型自己选择调用与否，在拿到的 AIMessage.tool_calls 中看到它要调用那些工具。

如果纯用model.invoke()，通常只会拿到“要调用工具的意图”，最终产出AIMessage.tool_calls，这一步还没有真正工具执行。
另外，模型也并非一定会阐述tool_calls。一般有这几种方法强制模型调用：
- 用模型支持的tool_choice强制模型阐述tool_calls
- 用图结构兜底，比如如果tool_calls为空就重试、报错、或路由到自定义的节点
- 提示词约束
产生了tool_calls以后，才能去往ToolNode进行正确的函数调用并返回结果！

(3) ToolNode

我们在学习LangChain的时候，介绍Tools这一节，我们跳过了ToolNode的学习，现在我们重新进行学习：

from langchain.tools import tool
from langgraph.prebuilt import ToolNode
from langgraph.graph import StateGraph, MessagesState, START, END

@tool
def search(query: str) -> str:
    """Search for information."""
    return f"Results for: {query}"

@tool
def calculator(expression: str) -> str:
    """Evaluate a math expression."""
    return str(eval(expression))

# Create the ToolNode with your tools
tool_node = ToolNode([search, calculator])

# Use in a graph
builder = StateGraph(MessagesState)
builder.add_node("tools", tool_node)
# ... add other nodes and edges

可以看到用法几乎和前面一样，只是节点用了from langgraph.prebuilt import ToolNode里面的可调用类ToolNode。ToolNode还提供了错误验证处理机制：

from langgraph.prebuilt import ToolNode

# Default: catch invocation errors, re-raise execution errors
tool_node = ToolNode(tools)

# Catch all errors and return error message to LLM
tool_node = ToolNode(tools, handle_tool_errors=True)

# Custom error message
tool_node = ToolNode(tools, handle_tool_errors="Something went wrong, please try again.")

# Custom error handler
def handle_error(e: ValueError) -> str:
    return f"Invalid input: {e}"

tool_node = ToolNode(tools, handle_tool_errors=handle_error)

# Only catch specific exception types
tool_node = ToolNode(tools, handle_tool_errors=(ValueError, TypeError))

当然，我们知道，工具的调用，大多是需要符合某种条件的，tool_condition就是专门用来根据大模型是否调用工具进行条件路由的。

from langgraph.prebuilt import ToolNode, tools_condition
from langgraph.graph import StateGraph, MessagesState, START, END

builder = StateGraph(MessagesState)
builder.add_node("llm", call_llm)
builder.add_node("tools", ToolNode(tools))

builder.add_edge(START, "llm")
builder.add_conditional_edges("llm", tools_condition)  # Routes to "tools" or END
builder.add_edge("tools", "llm")

graph = builder.compile()

上例，就是一个标准的ReAct风格agent图了，我们用相同的方法打印出来就能看到：

add_conditional_edges的核心是“从哪个节点执行完后开始判断路由”，这个节点可以是llm，也可以是tools、普通函数节点，没有区别。他的语法是add_conditional_edges("a", route, ...)，根据route返回动态跳转。

先执行源节点（比如 llm）。
执行完后，LangGraph 在 Python 侧调用你的路由函数 route(state, ...)。
路由函数返回下一个目标（节点名 / 多个节点 / END），图再继续执行。

我们可以自己写这个route函数，上例是（tools_codition这个预构建好的工具选择，有tool_calls则路由到工具节点处）：

from typing import Literal
from langgraph.graph import END

def route(state) -> Literal["tools", "chat", END]:
    last = state["messages"][-1]
    text = (last.content or "").lower()

    if getattr(last, "tool_calls", None):
        return "tools"
    if "结束" in text:
        return END
    return "chat"

builder.add_conditional_edges("llm", route)

也可以用映射表：

def route(state):
    return state["mode"]  # "search" / "done"

builder.add_conditional_edges("llm", route, {
    "search": "tools",
    "done": END
})

只要确保有一条路径通往END就可以了，不然会死循环。

4. 添加记忆

作为一个Agent，除了使用工具以外，还必须要记得交互的上下文，从而获取连贯多轮对话的能力。LangGraph是通过持久性检查点解决了这个问题。

具体而言，如果在编译图时提供一个checkpointer，并在调用图时提供一个thread_id，LangGraph 会在每一步之后自动保存状态。当使用相同的thread_id再次调用图时，图会加载其保存的状态，允许聊天机器人从上次中断的地方继续。

检查点比简单的聊天记忆功能强大得多——它允许您随时保存和恢复复杂状态，用于错误恢复、人工干预工作流、时间旅行交互等。

(1) 多轮对话实现

我们在LangChain中提到，如果要为智能体添加线程级记忆，需要在创建时指定checkpoint，当时使用的是InMemorySaver。MemorySaver 和 InMemorySaver 在现在的 LangGraph 里本质没区别，新代码的InMemorySaver建议向后兼容。（以后可能会有不同的SqliteSaver或者PostgreSaver，到时候查文档）。

我明明导入类创建实例，使用提供的检查点编译图，图在遍历每个节点时将对State设置检查点。

from langgraph.checkpoint.memory import MemorySaver

memory = MemorySaver()
graph = graph_builder.compile(checkpointer=memory)

注意现在，需要选择一个线程作为对话的键，作为第二个参数提供：

config = {"configurable": {"thread_id": "1"}}

user_input = "Hi there! My name is Will."

# The config is the **second positional argument** to stream() or invoke()!
events = graph.stream(
    {"messages": [{"role": "user", "content": user_input}]},
    config,
    stream_mode="values",
)
for event in events:
    event["messages"][-1].pretty_print()

(2) 检查State

我们可以在不同的线程中创建检查点，可是检查点中包含什么？要随时检查state，我们会使用get_state(config)。

snapshot = graph.get_state(config)
print(snapshot)

得到

{
  "type": "StateSnapshot",
  "thread": {
    "thread_id": "1",
    "checkpoint_ns": "",
    "checkpoint_id": "1ef7d06e-93e0-6acc-8004-f2ac846575d2",
    "parent_checkpoint_id": "1ef7d06e-859f-6206-8003-e1bd3c264b8f"
  },
  "timeline": {
    "created_at": "2024-09-27T19:30:10.820758+00:00",
    "step": 4,
    "source": "loop"
  },
  "messages": [
    {
      "role": "human",
      "content": "Hi there! My name is Will."
    },
    {
      "role": "ai",
      "model": "claude-3-5-sonnet-20240620",
      "content": "Hello Will! It's nice to meet you...",
      "usage": {
        "input_tokens": 405,
        "output_tokens": 32,
        "total_tokens": 437
      }
    },
    {
      "role": "human",
      "content": "Remember my name?"
    },
    {
      "role": "ai",
      "model": "claude-3-5-sonnet-20240620",
      "content": "Of course, I remember your name, Will...",
      "usage": {
        "input_tokens": 444,
        "output_tokens": 58,
        "total_tokens": 502
      }
    }
  ],
  "state": {
    "next": [],
    "tasks": [],
    "parents": {}
  },
  "last_write": {
    "node": "chatbot",
    "field": "messages",
    "value": "最后一条 AI 回复（确认记住名字 Will）"
  }
}

感到眼熟？那就对了，这就其中的message字典对应的就是AIMessage，相对的，多了type、thread、timeline等。

5. human-in-loop

Agent可能不完全可靠，有时候需要依赖人工输入才能完成任务。这就需要我们添加 human_assistance 到流程中。

import os
from typing import Annotated
from typing_extensions import TypedDict

from dotenv import load_dotenv
from langchain.chat_models import init_chat_model
from langchain_core.tools import tool
from langchain_tavily import TavilySearch

from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import START, StateGraph
from langgraph.graph.message import add_messages
from langgraph.prebuilt import ToolNode, tools_condition
from langgraph.types import Command, interrupt

BASE_DIR = os.path.dirname(__file__)
load_dotenv(os.path.join(BASE_DIR, ".env"))

llm = init_chat_model(
    "openai:gpt-4o-mini",
    base_url=os.getenv("QIHANG_BASE_URL"),
    api_key=os.getenv("QIHANG_API"),
)

class State(TypedDict):
    messages: Annotated[list, add_messages]

graph_builder = StateGraph(State)

@tool
def human_assistance(query: str) -> str:
    """Request assistance from a human."""
    human_response = interrupt({"query": query})
    return human_response["data"]

tavily_tool = TavilySearch(max_results=2)
tools = [tavily_tool, human_assistance]

llm_with_tools = llm.bind_tools(tools)

def chatbot(state: State):
    message = llm_with_tools.invoke(state["messages"])
    # 避免恢复后重复并行工具调用
    assert len(message.tool_calls) <= 1
    return {"messages": [message]}

graph_builder.add_node("chatbot", chatbot)
graph_builder.add_node("tools", ToolNode(tools=tools))

graph_builder.add_conditional_edges("chatbot", tools_condition)
graph_builder.add_edge("tools", "chatbot")
graph_builder.add_edge(START, "chatbot")

memory = MemorySaver()
graph = graph_builder.compile(checkpointer=memory)

if __name__ == "__main__":
    config = {"configurable": {"thread_id": "1"}}
    user_input = input("User: ").strip() or (
        "I need some expert guidance for building an AI agent. "
        "Could you request assistance for me?"
    )

    # 1) 首次运行：可能会在 human_assistance 处触发 interrupt
    events = graph.stream(
        {"messages": [{"role": "user", "content": user_input}]},
        config,
        stream_mode="values",
    )
    interrupted = False
    for event in events:
        if "messages" in event:
            event["messages"][-1].pretty_print()
        if "__interrupt__" in event:
            interrupted = True

    # 2) 如果触发中断，真实读取人工输入并恢复
    if interrupted:
        human_response = input("Human response: ").strip()
        if human_response:
            human_command = Command(resume={"data": human_response})
            events = graph.stream(human_command, config, stream_mode="values")
            for event in events:
                if "messages" in event:
                    event["messages"][-1].pretty_print()

首次 graph.stream(...) 运行到 interrupt(...) 时暂停。
终端真实输入 Human response。
用 Command(resume={"data": human_response}) 恢复执行。

另外，这里仍然是标准 ReAct 图：chatbot -> tools -> chatbot / END。llm.bind_tools(tools) 负责让模型知道可用工具，ToolNode + tools_condition 负责真正执行工具。

6. 自定义State

(1) 自己添加键

添加到State里面的信息可以被下游节点以及图的持久层访问。

class State(TypedDict):
    messages: Annotated[list, add_messages]
    name: str
    birthday: str

(2) 在工具内部更新状态

在 human_assistance 工具内部填充状态键。这允许人工在信息存储到状态之前对其进行审查。使用 Command 从工具内部发出状态更新。

from langchain_core.messages import ToolMessage
from langchain_core.tools import InjectedToolCallId, tool

from langgraph.types import Command, interrupt

@tool
# Note that because we are generating a ToolMessage for a state update, we
# generally require the ID of the corresponding tool call. We can use
# LangChain's InjectedToolCallId to signal that this argument should not
# be revealed to the model in the tool's schema.
def human_assistance(
    name: str, birthday: str, tool_call_id: Annotated[str, InjectedToolCallId]
) -> str:
    """Request assistance from a human."""
    human_response = interrupt(
        {
            "question": "Is this correct?",
            "name": name,
            "birthday": birthday,
        },
    )
    # If the information is correct, update the state as-is.
    if human_response.get("correct", "").lower().startswith("y"):
        verified_name = name
        verified_birthday = birthday
        response = "Correct"
    # Otherwise, receive information from the human reviewer.
    else:
        verified_name = human_response.get("name", name)
        verified_birthday = human_response.get("birthday", birthday)
        response = f"Made a correction: {human_response}"

    # This time we explicitly update the state with a ToolMessage inside
    # the tool.
    state_update = {
        "name": verified_name,
        "birthday": verified_birthday,
        "messages": [ToolMessage(response, tool_call_id=tool_call_id)],
    }
    # We return a Command object in the tool to update our state.
    return Command(update=state_update)

还有提醒聊天机器人、添加人工协助、手动更新状态、查看新值等比较自然的用法。

7. time-travel（时间旅行）

命运石之门来咯）

这一节的核心不是“回放聊天记录”，而是“从某个历史检查点重新继续运行图”。

前置条件：图必须 compile(checkpointer=...)，并且调用时使用同一个 thread_id。
关键能力有两种：
- Replay（重播）：从历史 checkpoint 继续跑，后续节点会重新执行。
- Fork（分叉）：在历史 checkpoint 上改一部分状态，再沿新分支继续跑。

(1) 回看完整历史：`get_state_history`

先看线程里有哪些 checkpoint（按时间倒序）：

to_replay = None
for state in graph.get_state_history(config):
    print("Num Messages:", len(state.values["messages"]), "Next:", state.next)
    # 例子：挑一个中间状态（这里只是演示，实际可以换成别的条件）
    if len(state.values["messages"]) == 6:
        to_replay = state

这里最重要的两个字段：

state.next：从这个 checkpoint 恢复后，下一个要执行的节点是谁。
state.config["configurable"]["checkpoint_id"]：这个历史点的唯一标识。

(2) 从某个历史点恢复执行（Replay）

教程里最关键的一行就是：

for event in graph.stream(None, to_replay.config, stream_mode="values"):
    if "messages" in event:
        event["messages"][-1].pretty_print()

说明：

这里传 None 作为输入，表示“不提供新输入，直接从 checkpoint 接着跑”。
传 to_replay.config，就是告诉 LangGraph“从这个历史点恢复”。
它会从 state.next 对应节点继续执行，所以后续工具调用/LLM 调用会重新发生。

(3) 一句话区分：Replay vs Fork

Replay：用旧 checkpoint 原样继续跑。
Fork：先改状态再继续跑（更像“平行世界”）。

例如（进阶）：

# 在历史点上改状态，生成新分支
fork_config = graph.update_state(
    to_replay.config,
    values={"messages": [("user", "换个方向继续")]},
)

# 从新分支继续执行
result = graph.invoke(None, fork_config)

以上，算是简单入门了LangGraph，接下来，我们直接顺着官方文档，开始一个能力一个能力查看。

微调入门：为什么需要微调、学习范式与参数更新范围

Fri, 03 Apr 2026 00:00:00 GMT

这一篇先不急着进工具和参数，而是先把“为什么要微调”这件事想清楚。只有先搞清楚目标，后面看 LoRA、数据集和训练参数时才不会只剩操作步骤。

一、为什么要微调

有时候，即使采用本地部署加知识库，也不能很好满足某些场景。因为常见大模型虽然基于海量数据训练，具备广泛的通用能力，但在特定领域、特定任务和特定输出风格上，往往还不够稳定。

通常会希望模型额外具备下面几类能力：

领域专业化：行业黑话、专业术语、专门知识要更稳地理解。
任务适配：希望输出风格、格式和结构更固定。
能力纠偏：在冷门场景或长尾问题上减少跑偏。

从问题拆解的角度看，长文本、知识库和微调并不是互斥关系，而是三种不同的优化方向。

对比维度	长文本处理	知识库	微调
核心目标	理解和生成长篇内容	提供背景知识，增强回答能力	优化模型在特定任务或领域的表现
优点	连贯性强，适合复杂任务	灵活性高，可随时更新	性能提升，定制化强
缺点	资源消耗大，上下文限制明显	依赖检索，实时性要求高	需要标注数据，训练成本高
适用场景	写作助手、长文理解	智能客服、问答系统	专业领域、固定任务、风格定制
实时性	静态，依赖输入	动态，知识库可更新	静态，训练后固定

所以微调更像是在回答一个问题：

当模型不仅要“知道”，还要“稳定地按某种方式做”时，是不是该把这种能力真正写进参数里。

二、一个微调的大致流程

微调的一般过程可以概括为 7 步：

选定预训练模型。
准备并加载微调数据集。
先准备一组固定问题，用于微调前后对比。
设定训练超参数。
进行训练。
评估训练后的回答效果。
不满意就继续调数据、调参数、重新训练。

这条流程看起来很简单，但真正最耗时间的其实是中间三件事：

数据集怎么组织
参数怎么选
结果怎么解释

后面几篇会分别把这三块拆开。

三、微调可以怎么分类

微调可以从很多维度分类。这里先保留原笔记里的三条主线：学习范式、参数更新范围、任务类型。

1. 按学习范式

（1）预训练

通常不是微调者自己做的阶段，而是通用大模型已经完成的那一轮大规模学习。预训练模型先学到通用语言规律、图像规律或多模态对齐能力，微调是在这个基础上继续塑形。

（2）监督微调（SFT）

监督微调是最常见、也最容易上手的一类微调。它使用带标签的任务数据继续训练模型，让模型更会做某个特定任务。

比如做英译中，只要数据集中提供英文输入和中文输出，模型就会被拉向这个映射关系。

（3）无监督微调

无监督微调使用没有标签但与任务相关的数据继续训练模型。它依赖的是数据本身的分布规律，而不是人工标注。

常见的无监督学习目标有两类：

自回归：根据前面的 token 预测下一个 token，代表模型是 GPT、LLaMA、Claude 等。
自编码：根据上下文预测被 mask 的 token，代表模型是 BERT、RoBERTa、BART 等。

（4）自监督微调

自监督其实是无监督学习里最重要的一支。它不是单纯“没有标签”，而是通过数据本身构造监督信号，相当于让模型自己给自己出题。

GPT 的自回归、BERT 的掩码预测都属于自监督范式。

（5）强化学习微调

这一类和前面差别很大，它不再只是“对着标准答案学”，而是通过奖励信号优化输出，让结果更符合人类偏好。

特性	监督微调	无监督 / 自监督微调	强化学习微调
核心数据	带标签任务数据	无标签任务数据	人类偏好 / 奖励信号
主要目标	特定任务性能	领域适应	对齐人类偏好
典型技术	交叉熵损失	自回归、掩码学习、对比学习	PPO、DPO 等
数据成本	高	低	很高
流程复杂度	低	中	很高

如果目标是明确分类任务，多数情况下 SFT 就足够了。

2. 按参数更新范围

这是微调里最现实的一组分类，因为它直接决定硬件要求和训练成本。

（1）全参数微调

最直接的方法：加载全部权重，在下游数据上更新所有参数。

优点是理论潜力最大；缺点是显存、算力和过拟合风险都最高。

（2）冻结微调

冻结大部分预训练层，只替换或解冻最后几层做训练。思路是：底层特征往往更通用，顶层特征更贴近任务。

（3）参数高效微调（PEFT）

PEFT 的目标很明确：只训练极少量参数，但尽可能保留接近全参数微调的效果。

它大体又可以分成几类：

① 适配器类

在原模型结构里插入一些小模块，训练这些新模块，冻结原始参数。

Adapter Tuning
Parallel Adapter
LoRA

特性	Adapter Tuning	Parallel Adapter	LoRA
核心思想	串行插入 Adapter 模块	与原模块并行放置 Adapter	用低秩矩阵近似权重更新
推理速度	会引入串行延迟	延迟较低	几乎无推理延迟
主要优点	参数效率高	结构更高效	参数少、部署方便、最主流
主要缺点	推理变慢	效果依赖实现	低秩假设并非总能完全覆盖复杂变化

② 提示工程类

通过加入可训练的软提示，让冻结模型朝任务方向偏移。

Prefix Tuning
Prompt Tuning
P-Tuning
P-Tuning v2

③ 低秩适配类

核心思想是利用低秩矩阵模拟权重更新。

LoRA
QLoRA
Delta-LoRA

④ 稀疏方法类

核心思想是只训练原模型参数中的一个稀疏子集。

BitFit
Fish Mask
Intrinsic SAID

3. 按任务类型

这条线更贴近业务目标：

指令微调
领域适应微调
风格迁移微调
多模态微调

如果目标是“让 Qwen2.5-VL 更懂某类图像并完成固定分类任务”，那它显然属于：

多模态微调
监督微调
参数高效微调里的 LoRA / QLoRA 路线

四、先留下一个实践判断

这组笔记最后要做的是多模态图像分类任务，所以最终选择监督微调，并优先考虑 LoRA 这类参数高效方法。这不是因为它“理论最高级”，而是因为它在硬件条件、数据规模和任务目标之间最平衡。

LangGraph 核心能力 01：Persistence、线程、检查点与 Store

Fri, 03 Apr 2026 00:00:00 GMT

Persistence 是 LangGraph 真正和普通“函数编排”拉开差距的地方。线程、检查点、状态历史和 Store 是一整套协作机制，不是几个分散功能。

1. 介绍

LangGraph 内置持久化层，可将图状态以检查点形式保存。当你使用检查点器编译图时，图状态的快照会在执行的每一步被保存，并按线程进行组织。这支持人机协同工作流、对话记忆、回溯调试以及容错执行。

持久化，对于Human-in-the-loop、Memory、Time travel、Fault-tolerance、Pending writes都是很有用的。

2. 线程 (Threads)

线程是检查点保存器为每个保存的检查点分配的唯一标识（ID）或线程标识符。它包含一系列运行的累积状态。执行一次运行时，助手底层图的状态将持久化到该线程中。在使用检查点保存器调用图时，你必须在配置的configurable部分中指定一个 thread_id：

{"configurable": {"thread_id": "1"}}

可获取线程的当前状态与历史状态。若要持久化状态，必须在执行运行任务前创建线程。LangSmith API 提供多个接口用于创建和管理线程及线程状态。

检查点存储器以thread_id作为存储和读取检查点的主键。若无此标识，检查点存储器将无法保存状态，也无法在中断后恢复执行，因为它需要通过thread_id加载已保存的状态。

3. 检查点 (Checkpoints)

线程在特定时间点的状态(State)称为检查点。检查点是在每个超步保存的图状态快照，由 StateSnapshot 对象表示。根据官方文档，StateSnapshot 字段如下：

字段	类型	描述
`values`	`dict`	该检查点对应的状态通道值。
`next`	`tuple[str, ...]`	下一步将要执行的节点名；为空 `()` 表示图已完成。
`config`	`dict`	当前检查点配置，包含 `thread_id`、`checkpoint_ns`、`checkpoint_id`。
`metadata`	`dict`	执行元数据，包含 `source`（`"input"`、`"loop"`、`"update"`）、`writes`（节点写入内容）、`step`（超步计数）。
`created_at`	`str`	检查点创建时间（ISO 8601）。
`parent_config`	`dict \| None`	上一个检查点配置；首个检查点为 `None`。
`tasks`	`tuple[PregelTask, ...]`	当前步骤任务集合。每个任务含 `id`、`name`、`error`、`interrupts`，并在 `subgraphs=True` 时可含 `state`（子图快照）。

实战读法（你调试时最常看）：

看 next：确认接下来会跑哪个节点，() 就是已结束。
看 metadata["source"]：区分本检查点来源于输入(input)、正常循环执行(loop)还是手动更新状态(update)。
看 metadata["writes"]：快速定位“这个检查点是谁写出来的”。
看 tasks：排查中断(interrupts)和错误(error)时最关键。

LangGraph 会在每个超步(Super-steps)边界创建检查点。超步是图的一次 “节拍”，在该节拍中，所有被调度到该步骤的节点都会执行（可能并行执行）。对于像START -> A -> B -> END这样的顺序图，输入、节点 A 和节点 B 各对应一个独立的超步 —— 每个超步完成后都会生成一个检查点。理解超步边界对于时间回溯至关重要，因为你只能从检查点（即超步边界）恢复执行。

检查点会被持久化存储，可用于在后续时间恢复线程状态。我们来看一下当一个简单图按如下方式调用时，会保存哪些检查点：

from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver
from langchain_core.runnables import RunnableConfig
from typing import Annotated
from typing_extensions import TypedDict
from operator import add

class State(TypedDict):
    foo: str
    bar: Annotated[list[str], add]

def node_a(state: State):
    return {"foo": "a", "bar": ["a"]}

def node_b(state: State):
    return {"foo": "b", "bar": ["b"]}


workflow = StateGraph(State)
workflow.add_node(node_a)
workflow.add_node(node_b)
workflow.add_edge(START, "node_a")
workflow.add_edge("node_a", "node_b")
workflow.add_edge("node_b", END)

checkpointer = InMemorySaver()
graph = workflow.compile(checkpointer=checkpointer)

config: RunnableConfig = {"configurable": {"thread_id": "1"}}
graph.invoke({"foo": "", "bar":[]}, config)

运行流程图后，我们预期会看到恰好4个检查点：

空检查点，下一个待执行节点为START
包含用户输入{'foo': '', 'bar': []}且下一个待执行节点为node_a的检查点
包含node_a输出结果{'foo': 'a', 'bar': ['a']}且下一个待执行节点为node_b的检查点
包含node_b输出结果{'foo': 'b', 'bar': ['a', 'b']}且无后续待执行节点的检查点

checkpoint_ns（检查点命名空间）用来区分当前检查点属于主图还是某个子图：

空字符串 ""：属于最外层根图（parent graph）。
节点名:uuid：属于该节点调用的子图。
嵌套子图用 | 连接：如 outer_node:uuid|inner_node:uuid，表示外层子图里的内层子图。

作用：让 LangGraph 知道状态属于哪一层图，避免多层嵌套时状态混乱。

4. 状态获取

与已保存的图状态交互时，你必须指定一个线程标识符。你可以通过调用graph.get_state(config)查看图的最新状态。该调用会返回一个StateSnapshot对象，对应配置中提供的线程 ID 所关联的最新检查点；若提供了检查点 ID，则返回该线程对应检查点 ID 的检查点。

# get the latest state snapshot
config = {"configurable": {"thread_id": "1"}}
graph.get_state(config)

# get a state snapshot for a specific checkpoint_id
config = {"configurable": {"thread_id": "1", "checkpoint_id": "1ef663ba-28fe-6528-8002-5a559208592c"}}
graph.get_state(config)

可以通过调用graph.get_state_history(config)获取指定线程的完整图执行历史。该方法会返回与配置中提供的线程 ID 相关联的 StateSnapshot 列表。这个列表可按“最新在前”来理解（最常用）。

config = {"configurable": {"thread_id": "1"}}
list(graph.get_state_history(config))

也可以像官方示例一样按条件筛选特定检查点（非常实用）：

history = list(graph.get_state_history(config))

# 找到“即将执行 node_b”之前的检查点
before_node_b = next(s for s in history if s.next == ("node_b",))

# 按 step 查找
step_2 = next(s for s in history if s.metadata["step"] == 2)

# 找出所有由 update_state 产生的检查点（分叉点）
forks = [s for s in history if s.metadata["source"] == "update"]

# 找到发生中断的检查点
interrupted = next(
    s for s in history
    if s.tasks and any(t.interrupts for t in s.tasks)
)

结果会像这样：

[
    StateSnapshot(
        values={'foo': 'b', 'bar': ['a', 'b']},
        next=(),
        config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28fe-6528-8002-5a559208592c'}},
        metadata={'source': 'loop', 'writes': {'node_b': {'foo': 'b', 'bar': ['b']}}, 'step': 2},
        created_at='2024-08-29T19:19:38.821749+00:00',
        parent_config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f9-6ec4-8001-31981c2c39f8'}},
        tasks=(),
    ),
    StateSnapshot(
        values={'foo': 'a', 'bar': ['a']},
        next=('node_b',),
        config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f9-6ec4-8001-31981c2c39f8'}},
        metadata={'source': 'loop', 'writes': {'node_a': {'foo': 'a', 'bar': ['a']}}, 'step': 1},
        created_at='2024-08-29T19:19:38.819946+00:00',
        parent_config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f4-6b4a-8000-ca575a13d36a'}},
        tasks=(PregelTask(id='6fb7314f-f114-5413-a1f3-d37dfe98ff44', name='node_b', error=None, interrupts=()),),
    ),
    StateSnapshot(
        values={'foo': '', 'bar': []},
        next=('node_a',),
        config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f4-6b4a-8000-ca575a13d36a'}},
        metadata={'source': 'loop', 'writes': None, 'step': 0},
        created_at='2024-08-29T19:19:38.817813+00:00',
        parent_config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f0-6c66-bfff-6723431e8481'}},
        tasks=(PregelTask(id='f1b14528-5ee5-579c-949b-23ef9bfbed58', name='node_a', error=None, interrupts=()),),
    ),
    StateSnapshot(
        values={'bar': []},
        next=('__start__',),
        config={'configurable': {'thread_id': '1', 'checkpoint_ns': '', 'checkpoint_id': '1ef663ba-28f0-6c66-bfff-6723431e8481'}},
        metadata={'source': 'input', 'writes': {'foo': ''}, 'step': -1},
        created_at='2024-08-29T19:19:38.816205+00:00',
        parent_config=None,
        tasks=(PregelTask(id='6d27aa2e-d72b-5504-a36f-8620e54a76dd', name='__start__', error=None, interrupts=()),),
    )
]

5. 重放 (Replay)

重放功能会从先前的检查点重新执行步骤。使用先前的checkpoint_id调用图，以重新运行该检查点之后的节点。检查点之前的节点会被跳过（其结果已保存）。检查点之后的节点会重新执行，包括任何大模型调用、API 请求或中断—— 这些在重放过程中始终会被重新触发。

此事在前面time travel初探有所提及。

6. 状态更新

可以使用update_state编辑图状态。这会基于更新后的值创建一个新的检查点，不会修改原始检查点。该更新的处理方式与节点更新一致：若定义了reducer函数，值会通过该函数传递，因此带有 reducer 的通道会累加数值而非覆盖。你可以可选指定as_node，以控制该更新被视为来自哪个节点，这会影响下一个执行的节点。

7. 记忆存储

仅依靠 checkpointer 无法在线程间共享信息。
checkpointer 负责“线程内状态持久化”，Store 负责“跨线程共享长期记忆”。

7.1 Store 的核心概念

Store 中的数据按 namespace（命名空间）组织，通常使用元组，例如：(user_id, "memories")。
每条记忆是 key-value 结构：key 是记忆 ID，value 是实际内容（通常为字典）。
search 返回的是 Item 对象，常见字段有：
- value
- key
- namespace
- created_at
- updated_at

说明：namespace 的类型是 tuple[str, ...]，在 JSON 展示中可能表现为列表。

举个例子，InMemoryStore 是存在当前 Python 进程的内存（RAM）里，来达到跨线程（thread_id）的效果，注意这里的线程并非是os的线程。

7.2 基础用法（脱离图单独使用）

import uuid
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

user_id = "1"
namespace = (user_id, "memories")

memory_id = str(uuid.uuid4())
memory = {"food_preference": "I like pizza"}

store.put(namespace, memory_id, memory)

memories = store.search(namespace)
print(memories[-1].dict())

7.3 在 LangGraph 中接入 Store

常见做法是同时编译：

checkpointer：保存线程内状态（checkpoint）
store：保存跨线程长期记忆

from dataclasses import dataclass
from langgraph.graph import StateGraph, MessagesState
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.store.memory import InMemoryStore

@dataclass
class Context:
    user_id: str

checkpointer = InMemorySaver()
store = InMemoryStore()

builder = StateGraph(MessagesState, context_schema=Context)
# ... add nodes / edges ...
graph = builder.compile(checkpointer=checkpointer, store=store)

调用时：

configurable.thread_id 用于线程内状态
context.user_id 用于跨线程记忆命名空间

config = {"configurable": {"thread_id": "1"}}

for update in graph.stream(
    {"messages": [{"role": "user", "content": "hi"}]},
    config,
    stream_mode="updates",
    context=Context(user_id="1"),
):
    print(update)

7.4 在节点中读写记忆（Runtime 注入）

在节点函数参数中声明 Runtime，即可访问 runtime.store 与 runtime.context。

import uuid
from dataclasses import dataclass
from langgraph.runtime import Runtime
from langgraph.graph import MessagesState

@dataclass
class Context:
    user_id: str

async def update_memory(state: MessagesState, runtime: Runtime[Context]):
    user_id = runtime.context.user_id
    namespace = (user_id, "memories")

    memory_id = str(uuid.uuid4())
    await runtime.store.aput(
        namespace,
        memory_id,
        {"memory": state["messages"][-1].content},
    )
    return {}

读取并用于模型调用：

async def call_model(state: MessagesState, runtime: Runtime[Context]):
    user_id = runtime.context.user_id
    namespace = (user_id, "memories")

    memories = await runtime.store.asearch(
        namespace,
        query=state["messages"][-1].content,
        limit=3,
    )
    memory_text = "\n".join([m.value["memory"] for m in memories])
    # 将 memory_text 拼接到 prompt 中再调用模型

7.5 跨线程共享记忆

只要 user_id 相同，即使 thread_id 不同，也可读取到同一份 Store 记忆。
这正是“会话内状态（thread）”和“长期用户记忆（store）”的分工。

7.6 语义检索（Semantic Search）

Store 支持语义检索。为 Store 配置 embedding 后，可以用自然语言 query 搜索记忆。

from langchain.embeddings import init_embeddings
from langgraph.store.memory import InMemoryStore

store = InMemoryStore(
    index={
        "embed": init_embeddings("openai:text-embedding-3-small"),
        "dims": 1536,
        "fields": ["$"],  # 或指定具体字段，如 ["food_preference"]
    }
)

memories = store.search(
    ("1", "memories"),
    query="What does the user like to eat?",
    limit=3,
)

一些建议：

InMemoryStore 适合开发与测试，生产环境应使用持久化 Store（如 PostgresStore、RedisStore）。
若节点需要访问 Store，不要直接依赖全局变量，优先通过 Runtime 注入访问 runtime.store。
设计命名空间时建议固定规则（如 (user_id, "memories")），便于检索与维护。

FastAPI 起步：应用入口、fastapi dev、entrypoint 与 uvicorn

Thu, 02 Apr 2026 00:00:00 GMT

官方教程的第一步其实很适合直接上手，因为 FastAPI 的最小应用非常小，小到可以一下子把“应用对象、路径函数、自动文档”三件事一起看到。

1. 第一个 FastAPI 应用到底做了什么

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def root():
    return {"message": "Hello World"}

这几行已经把 FastAPI 最关键的骨架全摆出来了：

app = FastAPI()：创建应用对象
@app.get("/")：注册一个处理 GET / 的路径操作
async def root()：定义真正处理请求的函数

一旦跑起来，FastAPI 会自动生成：

/openapi.json
/docs
/redoc

所以 FastAPI 的一个核心体验就是：写代码本身，也是在写接口 schema。

2. `fastapi dev` 是什么

FastAPI 自带了 CLI。官方文档里把它单独拆成了一页，但第一次接触时，最重要的其实就是先记住开发模式命令：

fastapi dev

官方文档说明，安装 fastapi[standard] 时，会附带 fastapi 这个命令行程序；开发环境里直接用 fastapi dev 即可启动开发服务器。它会自动热重载，所以改代码时服务会自动重启。
来源：FastAPI CLI 官方页 https://fastapi.tiangolo.com/zh/fastapi-cli/

如果当前目录里正好是标准结构，比如有一个 main.py 并且里面有 app = FastAPI()，那这条命令通常就够了。

3. `entrypoint` 为什么值得早一点知道

官方在 First Steps 里补了一个很有用的点：可以在 pyproject.toml 里配置应用入口。

[tool.fastapi]
entrypoint = "main:app"

如果代码不在根目录，而是在 backend/main.py 里，那么可以写成：

[tool.fastapi]
entrypoint = "backend.main:app"

它本质上是在告诉 fastapi 命令：

去哪个模块找应用
应用对象名字是什么

这件事看起来像小细节，但对多文件工程很重要，因为它会让 fastapi dev、工具链、编辑器扩展都更容易找到你的应用入口。
来源：First Steps 官方页 https://fastapi.tiangolo.com/zh/tutorial/first-steps/

4. 为什么还要知道 `uvicorn`

FastAPI 本身是 Web 框架，但真正负责接收 HTTP 请求、跑事件循环、把 ASGI 应用跑起来的，通常是 ASGI 服务器。

最常见的就是 uvicorn。

官方手动部署页里明确提到：

安装 fastapi[standard] 时也会安装 uvicorn[standard]
uvicorn[standard] 里包含了像 uvloop 这样的推荐依赖

也就是说，FastAPI 和 Uvicorn 的关系可以简单记成：

FastAPI：定义应用逻辑
Uvicorn：真正把这个 ASGI 应用跑起来

来源：手动运行服务器官方页 https://fastapi.tiangolo.com/zh/deployment/manually/

5. `fastapi dev`、`fastapi run`、`uvicorn main:app` 到底是什么关系

这一点官方文档是分散着讲的，第一次学时很容易混。

可以直接这样记：

fastapi dev：开发模式，带自动重载
fastapi run：CLI 的生产模式入口
uvicorn main:app：直接手动启动 ASGI 服务器

官方 CLI 页里明确写到：

开发环境用 fastapi dev
生产环境用 fastapi run
FastAPI CLI 内部实际也是基于 Uvicorn

而手动运行页里则说明了：

uvicorn main:app --host 0.0.0.0 --port 80

这里的 main:app 含义是：

main：main.py 这个模块
app：模块里的 app = FastAPI() 对象

它等价于：

from main import app

所以这三者并不冲突，只是站在不同层：

fastapi dev / fastapi run：更像 FastAPI 提供的易用封装
uvicorn main:app：直接操作 ASGI 服务器

6. `--reload` 为什么只该停留在开发阶段

官方手动运行页也特别提醒了 --reload。

它对开发很有用，因为改代码会自动重启。但它的本质是“开发便利”，不是生产能力。所以在生产部署里，通常不会把 --reload 一直开着。

因此最常见的分工是：

uvicorn main:app --reload

用在本地开发；

fastapi run main.py

或者：

uvicorn main:app --host 0.0.0.0 --port 80

更接近部署和容器场景。

7. 调试时把 `uvicorn.run()` 写进 `main`

你本地笔记里还写到了这种方式：

import uvicorn
from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def root():
    return {"hello": "world"}


if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

这种写法不是 FastAPI 官方主推的日常运行方式，但在本地直接调试时很顺手，尤其是你已经把应用写成一个普通 Python 文件、想直接点运行的时候。

它更像“开发时的 Python 入口”，而不是部署命令。

8. FastAPI 为什么能直接支持 `async def`

FastAPI 的另一个关键体验，是路径函数可以自然写成 async def。

import asyncio
from fastapi import FastAPI

app = FastAPI()


async def make_burger(name: str, seconds: int):
    await asyncio.sleep(seconds)
    return name


@app.get("/burgers/{count}")
async def order_burgers(count: int):
    tasks = [
        asyncio.create_task(make_burger(f"汉堡{i + 1}", 3 + i))
        for i in range(count)
    ]
    burgers = await asyncio.gather(*tasks)
    return {"count": count, "burgers": burgers}

这个“做汉堡”例子重要的地方不在汉堡，而在于它很适合建立一个直觉：

I/O 密集型任务适合异步
await 的意义不是“更快”，而是“等待时别堵住整个服务”
FastAPI 对 async def 的支持不是附加功能，而是默认工作方式的一部分

如果路径函数写成普通 def，FastAPI 也能处理。它会把同步函数放到线程池里执行，避免直接阻塞事件循环。这个兜底机制意味着：

能异步就异步
还没异步化的同步逻辑也能先跑起来

量化入门：为什么要量化、量化怎么做、常见方法有哪些

Thu, 02 Apr 2026 00:00:00 GMT

量化和微调经常一起出现，尤其一说到 QLoRA 就会默认它们属于一套东西。但更顺的理解方式其实是先把量化单独拆开：它先是模型压缩与推理优化技术，然后才在 QLoRA 里与微调发生结合。

一、为什么要量化

模型量化的核心，是把高精度数据（通常是 FP32）转换成更低精度的数据表示。

它最直接的目标有三个：

减少模型大小
降低显存或内存占用
提升推理速度

代价也很明确：精度可能损失。

所以量化从来都不是“白送的加速”，而是一种典型的精度与资源交换。

二、量化的原理

量化本质上是在做一件事：

把连续浮点区间，映射到有限的离散整数区间。

原笔记里的几个核心量是：

x_fp：原始浮点值
x_int：量化后的整数值
scale：缩放因子
zero_point：零点偏移

可以把它粗理解为“比例缩放 + 偏移对齐”。

三、量化可以怎么分类

1. 按量化时机

（1）训练后量化（PTQ）

先正常训练，再在模型训练完之后直接量化。

优点是快、实现简单；缺点是精度损失可能比较明显，尤其在小模型上。

QLoRA 里常见的 4-bit NF4 量化，本质上也是“微调前先把基础模型量化”。

（2）量化感知训练（QAT）

在训练时就模拟量化和反量化过程，让模型提前适应低精度带来的误差。

这类方法通常更稳，但实现复杂度和训练成本更高。

2. 按量化精度

类型	权重精度	激活值精度	特点	代表技术
FP16 / BF16	16-bit	16-bit	更偏训练加速与存储节省，通常可视为近乎无损	AMP
INT8	8-bit	8-bit	最主流的推理精度，精度和效率平衡较好	TensorRT, ONNX Runtime
INT4 / NF4	4-bit	8-bit / 4-bit	极致压缩，适合消费级硬件跑大模型	QLoRA, GPTQ, AWQ
1-bit / 2-bit	1/2-bit	32-bit / 1-bit	学术前沿，压缩极致，但落地难	BinaryConnect

3. 按量化对象

（1）仅权重量化

只量化模型权重，激活值仍然保留较高精度。

（2）权重与激活值全量化

推理过程中权重和激活值都被量化到低精度，进一步压缩，但实现难度更高。

4. 按量化策略

类型	原理	优点	缺点
对称量化	把 `[-α, α]` 映射到对称整数区间，`zero_point = 0`	计算简单	不适合明显偏斜的数据分布
非对称量化	把 `[β, α]` 映射到非对称整数区间，`zero_point ≠ 0`	更充分利用整数区间，误差更小	计算稍复杂

四、常见量化方法

1. bitsandbytes（bnb）

这是 QLoRA 最经典也最常见的配套库，支持 8-bit 与 4-bit，尤其 4-bit NF4 是它的代表能力之一。

优点是：

社区最成熟
Hugging Face 生态集成最好
对 LoRA / QLoRA 训练非常友好

2. HQQ

HQQ 的特点是尽量减少对校准数据的依赖。相比传统量化要先拿一批校准样本统计分布，HQQ 更强调快速量化和更灵活的冷启动。

3. EETQ

EETQ 是 NVIDIA 推出的 8-bit 推理方案，更偏高吞吐的工程落地路线，和 TensorRT 这类 NVIDIA 生态结合得更深。

五、量化和微调是怎么接起来的

到这里，量化还只是“压缩模型”的技术。但一旦和 LoRA 结合起来，它就从纯推理优化，变成了一条真正改变训练门槛的路线。

QLoRA 的关键思路是：

先把基础模型量化到 4-bit
冻结这些量化权重
只训练 LoRA 增量参数

这样做的好处不是“量化本身更聪明”，而是：

把原本需要很大显存才能做的微调，压到了普通单机甚至消费级设备也能尝试的区间。

所以量化在这里的价值，不只是推理更省资源，而是直接改变了“谁有能力做微调”的门槛。

LangGraph 核心能力 02：Durable Execution 与 task 封装

Thu, 02 Apr 2026 00:00:00 GMT

这篇最值得记住的一句话是：LangGraph 的恢复不是从“代码那一行”继续，而是从某个可回放起点重新执行。

持久执行是一种技术，进程或工作流会在关键节点保存进度，使其能够暂停，并在后续从断点处精准恢复执行。该技术在需要human-in-loop的场景中尤为实用 —— 用户可在流程继续前进行检查、验证或修改；同时也适用于可能遭遇中断或错误的长时间运行任务（例如调用大模型超时）。通过保留已完成的工作，持久执行可让进程无需重复处理先前步骤即可恢复，即便间隔时间较长（例如一周后）也能实现。

LangGraph 内置的持久化层为工作流提供持久执行能力，确保每个执行步骤的状态都保存至持久化存储中。这一特性保证，无论工作流是因系统故障中断，还是为了human-in-loop交互而暂停，都能从最后记录的状态恢复执行。

值得注意的是，只要用了 checkpointer，就已经开启 durable execution，但是恢复时不是从“代码那一行”继续，而是从某个可重放起点重跑到中断处。所以要把“副作用/不确定操作”（API 调用、写文件、随机数）包进 task，并尽量做幂等。另外，选择durability 模式：exit / async / sync。

提一下幂等(idempotent)，它是指同一个操作执行 1 次和执行多次，结果一样。比如把用户语言设置为 zh 就是幂等的，而余额+100则是非幂等的。你在 LangGraph durable execution 里会遇到它，是因为失败重试/回放可能重复执行。

解决操作不幂等的常见解法，是给一次业务操作生成唯一的幂等键（idempotency_key），下游根据key去重。

示例对比：直接在 node 中请求 vs 用 `@task` 封装请求

这两段代码核心区别，在这里。

from typing import NotRequired
from typing_extensions import TypedDict
import uuid

from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import StateGraph, START, END
import requests

# Define a TypedDict to represent the state
class State(TypedDict):
    url: str
    result: NotRequired[str]

def call_api(state: State):
    """Example node that makes an API request."""
    result = requests.get(state['url']).text[:100]  # Side-effect  #
    return {
        "result": result
    }

# Create a StateGraph builder and add a node for the call_api function
builder = StateGraph(State)
builder.add_node("call_api", call_api)

# Connect the start and end nodes to the call_api node
builder.add_edge(START, "call_api")
builder.add_edge("call_api", END)

# Specify a checkpointer
checkpointer = InMemorySaver()

# Compile the graph with the checkpointer
graph = builder.compile(checkpointer=checkpointer)

# Define a config with a thread ID.
thread_id = uuid.uuid4()
config = {"configurable": {"thread_id": thread_id}}

# Invoke the graph
graph.invoke({"url": "https://www.example.com"}, config)

from typing import NotRequired
from typing_extensions import TypedDict
import uuid

from langgraph.checkpoint.memory import InMemorySaver
from langgraph.func import task
from langgraph.graph import StateGraph, START, END
import requests

# Define a TypedDict to represent the state
class State(TypedDict):
    urls: list[str]
    result: NotRequired[list[str]]


@task
def _make_request(url: str):
    """Make a request."""
    return requests.get(url).text[:100]

def call_api(state: State):
    """Example node that makes an API request."""
    requests = [_make_request(url) for url in state['urls']]
    results = [request.result() for request in requests]
    return {
        "results": results
    }

# Create a StateGraph builder and add a node for the call_api function
builder = StateGraph(State)
builder.add_node("call_api", call_api)

# Connect the start and end nodes to the call_api node
builder.add_edge(START, "call_api")
builder.add_edge("call_api", END)

# Specify a checkpointer
checkpointer = InMemorySaver()

# Compile the graph with the checkpointer
graph = builder.compile(checkpointer=checkpointer)

# Define a config with a thread ID.
thread_id = uuid.uuid4()
config = {"configurable": {"thread_id": thread_id}}

# Invoke the graph
graph.invoke({"urls": ["https://www.example.com"]}, config)

对比维度	直接在 node 里 `requests.get()`	用 `@task` 封装 `_make_request()`
副作用位置	副作用直接写在 node 内	副作用被隔离到 task 内
恢复/重放时行为	node 可能被重放，副作用可能重复触发	已成功完成的 task 结果可被复用，减少重复副作用
失败恢复粒度	粒度较粗，通常按 node 重新执行	粒度更细，按 task 级别恢复更可控
代码组织	简单直接，但不利于 durable 场景	结构更清晰，适合长流程和容错
推荐场景	一次性、无副作用、演示代码	生产或半生产，涉及 API/IO/不确定操作

为什么官方推荐第二种

在 durable execution 中，恢复不是回到某一行代码，而是从某个可重放起点继续。
如果副作用写在 node 里，重放时容易重复调用外部 API。
把副作用放进 @task，可以让 LangGraph 更好地记录和复用已完成工作，减少重复执行风险。

这两个例子的结论

第一段代码可运行，但更像“最小示例”，适合理解流程。
第二段代码是 durable execution 更推荐的写法，尤其是有外部 API 调用时。
即便用了 task，也应尽量保证调用幂等（例如带幂等键），因为失败重试时仍可能重跑未成功完成的 task。

小修正（你的第二段代码）

State 里写的是 result: NotRequired[list[str]]，但返回值是 {"results": results}。
字段名建议统一为一个，例如都用 results，避免状态键不一致。

FastAPI 输入基础：路径参数与查询参数

Wed, 01 Apr 2026 00:00:00 GMT

官方把路径参数和查询参数拆成了两个章节，这样查资料很舒服；连续学习时，把它们放在一起会更顺，因为它们本质上都在回答同一个问题：请求里的输入，先从 URL 的哪一层进来。

1. 路径参数：资源定位的一部分

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str):
    return {"item_id": item_id}

这里的 item_id 不只是一个字符串变量，而是 URL 路径的一部分。

FastAPI 会根据类型注解自动解析：

写成 str，/items/foo 和 /items/4 都行
写成 int，传 foo 会自动报校验错误

所以它不是“先拿到字符串，再自己转”，而是直接把 Python 类型系统接到了请求解析层。

2. 路径匹配的顺序很重要

@app.get("/users/me")
async def read_user_me():
    return {"user_id": "the current user"}


@app.get("/users/{user_id}")
async def read_user(user_id: str):
    return {"user_id": user_id}

/users/me 必须写在 /users/{user_id} 前面，否则 me 会被当成普通的 user_id。

这里很容易以为 FastAPI 会自动优先匹配更具体的路径，但实际还是要考虑声明顺序。

3. 枚举路径参数

当路径参数只能从一组有限值里选时，可以直接用 Enum：

from enum import Enum


class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}
    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN all the images"}
    return {"model_name": model_name, "message": "Have some residuals"}

这样文档里会直接展示可选值，而不是一个自由输入框。

4. 路径转换器

有时候变量本身还想继续吃掉路径，可以用 Starlette 的路径转换器：

@app.get("/files/{file_path:path}")
async def read_file(file_path: str):
    return {"file_path": file_path}

这里的 :path 让 file_path 可以包含 /。

5. 查询参数：`?` 后面的附加条件

from fastapi import FastAPI

app = FastAPI()

fake_items_db = [{"item_name": "Foo"}, {"item_name": "Bar"}, {"item_name": "Baz"}]


@app.get("/items/")
async def read_items(skip: int = 0, limit: int = 10):
    return fake_items_db[skip : skip + limit]

对应请求可以写成：

/items/?skip=0&limit=10

只要参数不是路径参数，FastAPI 默认就会把它解释成查询参数。

6. 路径参数和查询参数可以同时存在

@app.get("/items/{item_id}")
async def read_item(
    item_id: str,
    p: str = "test",
    q: str | None = None,
    short: bool = False,
):
    item = {"item_id": item_id}
    if q:
        item.update({"q_info": f"q传入了参数{q}"})
    if p:
        item.update({"p_info": "测试成功，默认查询了p"})
    if short:
        item.update({"short_info": "你真传了short啊"})
    return item

这里：

item_id 是路径参数
p、q、short 是查询参数

布尔查询参数也会自动做转换。像 1、true、on 都会被识别成 True。

7. 一开始最值得建立的区分

这一阶段最重要的不是背更多 API，而是先把 URL 上的输入层分开：

路径参数：属于资源标识的一部分
查询参数：属于对本次请求的额外说明

后面无论进入请求体、表单还是依赖注入，只要这个区分先站稳，阅读体验会顺很多。

微调数据集：Alpaca、ShareGPT、多模态格式与 LLaMA-Factory 接入

Wed, 01 Apr 2026 00:00:00 GMT

真正开始微调时，最容易被低估的往往不是模型，而是数据格式。模型再强，如果数据结构和训练框架对不上，后面基本都会卡住。

一、常见数据格式：Alpaca 与 ShareGPT

1. Alpaca

Alpaca 最初来自斯坦福大学发布的 52k 指令微调数据集。后来“Alpaca 格式”逐渐被社区抽象成一类更通用的单轮任务数据结构，适合：

问答
翻译
摘要
结构化生成

它的核心特征是围绕下面几类字段组织：

instruction
input
output
可选的 system
可选的 history

2. ShareGPT

ShareGPT 更适合多轮对话和复杂交互。它的核心不是单个 instruction，而是一串 conversations。

它常见的角色包括：

human
gpt
function_call
observation

因此它特别适合：

多轮聊天
工具调用
更接近真实助手场景的数据

3. 两种格式的差别

对比维度	Alpaca	ShareGPT
核心目标	单轮指令驱动任务	多轮对话与工具调用
数据结构	`instruction / input / output` 为主	`conversations` 列表为主
多轮历史	通过 `history` 额外表示	自然体现在对话列表里
工具调用	不原生支持	原生支持 `function_call / observation`
典型场景	指令微调、单轮生成	聊天助手、工具代理、复杂交互

如果只是做单轮任务，Alpaca 往往更直接；如果要训练对话助手或工具流，ShareGPT 更自然。

二、多模态数据通常怎么写

在多模态微调里，最常见的组织方式是：

your_multimodal_data/
├── images/
├── conversations.json
└── metadata.json

其中真正关键的是：

文本对话内容
图像路径或图像标识
文本里 <image> 这类占位符

一个很典型的多模态样本大致会长这样：

{
  "id": "unique_conversation_id_1",
  "image": "images/image1.jpg",
  "conversations": [
    {
      "from": "human",
      "value": "请详细描述这张图片。<image>"
    },
    {
      "from": "gpt",
      "value": "这张图片展示了一只可爱的金色寻回犬在草地上奔跑。"
    }
  ]
}

对于 Qwen2.5-VL 这类模型来说，重点不在于格式有多花，而在于：

图像路径要正确
占位符要符合模板
对话轮次要和任务一致

三、训练集、验证集、测试集该怎么分

微调时最常见的三类数据是：

训练集：用于更新权重。
验证集：用于观察训练过程和泛化情况，不参与权重更新。
测试集：训练和调参全部结束后，最后做客观评估。

原笔记里对不同数据规模给了一条很实用的经验线：

大数据集：80/10/10 或 70/15/15
中等数据集：60/20/20 或 70/20/10
小数据集：优先考虑交叉验证，或者酌情增大验证 / 测试比例

到了多模态任务里，还要额外注意：

绝对数量比比例更重要
要尽量做分层抽样
小数据集更需要认真留测试集

四、LLaMA-Factory 里的 `dataset_info`

LLaMA-Factory 会用一个统一的配置文件来登记数据集入口。这个设计很实用，因为它把“训练命令”与“数据来源描述”解耦了。

核心字段一般包括：

file_name
formatting
columns
tags

如果是这次笔记里的多模态 ShareGPT 格式数据集，一个典型配置可以写成：

"blood_image": {
  "file_name": "/data/llm/blood_image/dataset.json",
  "formatting": "sharegpt",
  "columns": {
    "messages": "conversations",
    "images": "image"
  }
}

而对应的数据集样本可能是：

{
  "id": "sample_24",
  "image": "/data/llm/img2npy/output/滴落/6.png",
  "conversations": [
    {
      "from": "human",
      "value": "<image>\n描述这张图片。"
    },
    {
      "from": "gpt",
      "value": "在木质背景上有一滴血液，下面摆放着一把尺子用于测量。"
    },
    {
      "from": "human",
      "value": "这是什么形态的血液？"
    },
    {
      "from": "gpt",
      "value": "这属于被动的/重力类血液中的滴落类型。"
    }
  ]
}

这组例子其实很能说明一个事实：

微调数据集不是“随便凑成问答”就行，而是要和模型模板、训练框架、任务目标同时对齐。

五、一组真正会影响训练结果的参数直觉

原笔记里还单独整理了几组训练时最常调的参数，这些内容后面会继续用到：

1. 训练轮数（Epochs）

数据少时往往需要更多轮
太多又容易过拟合
一般可以从 3 开始试

2. 学习率

一般微调任务：5e-5
更保守：4e-5
全参数微调：通常更小，比如 1e-5

3. 批量大小（Batch Size）

批量大小实际上由两件事共同决定：

每卡 batch size
梯度累积步数

大批量更稳但更吃资源，小批量更细但噪声更大。

4. 截断长度（Cutoff Length）

这个值直接影响：

上下文能装多少内容
显存占用有多大

最理想的做法通常是：

先统计数据分布，再决定 cutoff，而不是先拍脑袋选一个值。

5. 验证集比例

如果数据量太小，验证集比例设置得再标准也不一定有意义；但如果完全没有验证集，就只能靠训练 loss 猜状态。

所以这部分没有绝对标准，关键是：样本量要足够让验证集真的能“说明问题”。

LangGraph 核心能力 03：Streaming 与 v2 事件格式

Wed, 01 Apr 2026 00:00:00 GMT

这篇建议和 LangChain 的流式输出一起对照着看：LangChain 更偏模型/agent 侧，LangGraph 更偏整张图的运行时事件。

可结合LangChain的流一起看

1. 介绍

在入门章节，我们就用到了Graph的stream_mode，提到和agent的有所不同。

LangGraph 图提供stream（同步）和astream（异步）方法，以迭代器形式生成流式输出。传入一个或多个流模式来控制接收的数据内容。

for chunk in graph.stream(
    {"topic": "ice cream"},
    stream_mode=["updates", "custom"],
    version="v2",
):
    if chunk["type"] == "updates":
        for node_name, state in chunk["data"].items():
            print(f"Node {node_name} updated: {state}")
    elif chunk["type"] == "custom":
        print(f"Status: {chunk['data']['status']}")

Status: thinking of a joke...
Node generate_joke updated: {'joke': 'Why did the ice cream go to school? To get a sundae education!'}

2. 流输出格式 (v2)

(1) stream mode

向version="v2"传入stream()或astream()以获取统一的输出格式。每个数据块均为一个StreamPart字典，具有固定结构：

{
    "type": "values" | "updates" | "messages" | "custom" | "checkpoints" | "tasks" | "debug",
    "ns": (),           # namespace tuple, populated for subgraph events
    "data": ...,        # the actual payload (type varies by stream mode)
}

每种流模式都有对应的TypedDict，包含ValuesStreamPart、UpdatesStreamPart、MessagesStreamPart、CustomStreamPart、CheckpointStreamPart、TasksStreamPart、DebugStreamPart（对应7种streammode）

在 v1 版本（默认）中，输出格式会根据你的流式传输选项而变化（单模式返回原始数据，多模式返回(mode, data) 元组，子图返回(namespace, data) 元组）。在 v2 版本中，格式始终保持一致。

可以看到，这里的v1、v2区别，实际和LangChain Agent的模式选择一样，v2都是有更格式化的输出（即StreamPart）。当时提到但是还不够详细，这里细致拆解一下StreamPart：

type="values"：每一步后的完整状态快照；data 是完整 state（full state）。
type="updates"：节点执行后对 state 的增量更新；data 形如 {"node_name": {"changed_key": value}}。
type="messages"：LLM 消息流；data 通常是 (message_chunk, metadata)。
type="custom"：来自 get_stream_writer() 主动写出的自定义事件；data 就是 writer({...}) 传入的内容。
type="checkpoints"：checkpoint 事件流；data 是检查点快照信息（类似 get_state 返回结构）。
type="tasks"：任务生命周期事件（开始/结束/结果/错误）；data 是任务执行信息。
type="debug"：最全量调试事件；data 包含更完整的执行上下文与诊断信息。

下面，我放一个最小的message用法示例，它定义了图状态，用stream执行图，然后实现了逐token输出：

from dataclasses import dataclass

from langchain.chat_models import init_chat_model
from langgraph.graph import StateGraph, START


@dataclass
class MyState:
    topic: str
    joke: str = ""


model = init_chat_model(model="gpt-4.1-mini")

def call_model(state: MyState):
    """Call the LLM to generate a joke about a topic"""
    # Note that message events are emitted even when the LLM is run using .invoke rather than .stream
    model_response = model.invoke(
        [
            {"role": "user", "content": f"Generate a joke about {state.topic}"}
        ]
    )
    return {"joke": model_response.content}

graph = (
    StateGraph(MyState)
    .add_node(call_model)
    .add_edge(START, "call_model")
    .compile()
)

# The "messages" stream mode streams LLM tokens with metadata
# Use version="v2" for a unified StreamPart format
for chunk in graph.stream(
    {"topic": "ice cream"},
    stream_mode="messages",
    version="v2",
):
    if chunk["type"] == "messages":
        message_chunk, metadata = chunk["data"]
        if message_chunk.content:
            print(message_chunk.content, end="|", flush=True)

至于ns 是事件来源的命名空间路径，用来标识这个 stream chunk 来自哪一层图。比如：

ns == ()：来自主图（root graph）
ns == ("node_2:<task_id>",)：来自 node_2 调用的子图
ns == ("child:<id>", "child_1:<id>")：来自更深层嵌套子图

我们可以通过 chunk["type"] 过滤数据块，并获得正确的负载类型。每个分支都会将 part["data"] 收窄为对应模式的特定类型：

for part in graph.stream(
    {"topic": "ice cream"},
    stream_mode=["values", "updates", "messages", "custom"],
    version="v2",
):
    if part["type"] == "values":
        # ValuesStreamPart — full state snapshot after each step
        print(f"State: topic={part['data']['topic']}")
    elif part["type"] == "updates":
        # UpdatesStreamPart — only the changed keys from each node
        for node_name, state in part["data"].items():
            print(f"Node `{node_name}` updated: {state}")
    elif part["type"] == "messages":
        # MessagesStreamPart — (message_chunk, metadata) from LLM calls
        msg, metadata = part["data"]
        print(msg.content, end="", flush=True)
    elif part["type"] == "custom":
        # CustomStreamPart — arbitrary data from get_stream_writer()
        print(f"Progress: {part['data']['progress']}%")

(2) 过滤

我们之前在LangChain核心组件Models中就学过，init_chat_model的时候用config参数，添加额外字典，从而对运行时的行为控制。

不过这里是不同的层级，直接在init_model_model里面加入tags，是专门给模型实例设置默认标签，每次调用都会带上。我们可以通过这个元信息，直接过滤：

from langchain.chat_models import init_chat_model

# model_1 is tagged with "joke"
model_1 = init_chat_model(model="gpt-4.1-mini", tags=['joke'])
# model_2 is tagged with "poem"
model_2 = init_chat_model(model="gpt-4.1-mini", tags=['poem'])

graph = ... # define a graph that uses these LLMs

# The stream_mode is set to "messages" to stream LLM tokens
# The metadata contains information about the LLM invocation, including the tags
async for chunk in graph.astream(
    {"topic": "cats"},
    stream_mode="messages",
    version="v2",
):
    if chunk["type"] == "messages":
        msg, metadata = chunk["data"]
        # Filter the streamed tokens by the tags field in the metadata to only include
        # the tokens from the LLM invocation with the "joke" tag
        if metadata["tags"] == ["joke"]:
            print(msg.content, end="|", flush=True)

或者，我们还可以按照node name过滤，或者按照自定义的字段过滤……总之，就是简单的python逻辑。

(3) nostream

使用 nostream 标签可将大语言模型的输出完全排除在流式传输之外。标记为 nostream 的调用仍会正常执行并生成输出，只是其词元不会在 messages 模式下发送。(这里nostream是写在config字段下面的)

该功能适用于以下场景：

需要大语言模型输出用于内部处理（例如结构化输出），但不希望将其流式传输给客户端
通过其他通道（例如自定义界面消息）流式传输相同内容，且希望避免 messages 流中出现重复输出

举例如下：

from typing import Any, TypedDict

from langchain_anthropic import ChatAnthropic
from langgraph.graph import START, StateGraph

stream_model = ChatAnthropic(model_name="claude-3-haiku-20240307")
internal_model = ChatAnthropic(model_name="claude-3-haiku-20240307").with_config(
    {"tags": ["nostream"]}
)


class State(TypedDict):
    topic: str
    answer: str
    notes: str


def answer(state: State) -> dict[str, Any]:
    r = stream_model.invoke(
        [{"role": "user", "content": f"Reply briefly about {state['topic']}"}]
    )
    return {"answer": r.content}


def internal_notes(state: State) -> dict[str, Any]:
    # Tokens from this model are omitted from stream_mode="messages" because of nostream
    r = internal_model.invoke(
        [{"role": "user", "content": f"Private notes on {state['topic']}"}]
    )
    return {"notes": r.content}


graph = (
    StateGraph(State)
    .add_node("write_answer", answer)
    .add_node("internal_notes", internal_notes)
    .add_edge(START, "write_answer")
    .add_edge("write_answer", "internal_notes")
    .compile()
)

initial_state: State = {"topic": "AI", "answer": "", "notes": ""}
stream = graph.stream(initial_state, stream_mode="messages")

FastAPI 请求体：Pydantic 模型、多参数与嵌套结构

Tue, 31 Mar 2026 00:00:00 GMT

从这一篇开始，输入不再只是 URL 上的几个值，而是成块的数据结构。FastAPI 的优势也从这里开始明显：不是自己手写 JSON 解析，而是直接把结构声明成模型。

1. 用 Pydantic 模型声明请求体

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = FastAPI()


@app.post("/item/")
async def create_item(item: Item):
    item_dict = item.model_dump()
    if item.tax is not None:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

这里的关键不是“能收到 JSON”，而是：

FastAPI 会把请求体按 Item 模型解析
Pydantic 会自动校验字段类型
文档会自动生成 schema
校验错误会定位到具体字段

2. 路径参数、查询参数、请求体可以一起出现

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, q: str | None = None):
    result = {"item_id": item_id, **item.model_dump()}
    if q:
        result.update({"q": q})
    return result

这里已经把三类最核心的输入组合起来了：

item_id：路径参数
q：查询参数
item：请求体

后面很多复杂接口，本质上还是这三层输入的组合。

3. 多个请求体参数

from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


class User(BaseModel):
    username: str
    full_name: str | None = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, user: User):
    return {"item_id": item_id, "item": item, "user": user}

这时 FastAPI 期望请求体长成：

{
  "item": {
    "name": "Foo",
    "description": "The pretender",
    "price": 42.0,
    "tax": 3.2
  },
  "user": {
    "username": "dave",
    "full_name": "Dave Grohl"
  }
}

4. 简单类型如果想放进 Body，需要显式声明

from typing import Annotated
from fastapi import Body


@app.put("/b_items/{item_id}")
async def update_item(
    item_id: int,
    item: Item,
    user: User,
    importance: Annotated[int, Body(gt=0)],
):
    return {"item_id": item_id, "item": item, "user": user, "importance": importance}

这里有个很关键的规则：

Pydantic 模型默认会被当成请求体
简单类型如果不额外声明，默认会被当成查询参数

所以 Body() 不只是补校验，它还在明确参数来源。

5. 嵌套模型

from pydantic import BaseModel, HttpUrl


class Image(BaseModel):
    url: HttpUrl
    name: str


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    images: list[Image] | None = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, "item": item}

这里顺手也能看到 Pydantic 提供的几个常用能力：

HttpUrl：校验 URL
set[str]：自动去重
list[Image]：子模型列表

6. 给请求体补示例和文档信息

模型不仅负责校验，还会直接影响 /docs 里的展示效果。

可以在模型里写：

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None

    model_config = {
        "json_schema_extra": {
            "examples": [
                {
                    "name": "Foo",
                    "description": "A very nice Item",
                    "price": 35.4,
                    "tax": 3.2,
                }
            ]
        }
    }

也可以在 Body() 里写 openapi_examples，这样能给同一个接口准备多个示例场景。

7. 请求体这一层真正带来的变化

到了这里，FastAPI 的体验已经开始和“手写 Flask 风格的 JSON 解析”拉开差距了。

你写的不是“接收一个 dict 再自己判空”，而是：

先把数据结构声明出来
再让框架负责解析
再让文档跟着模型自动长出来

这也是为什么后面学响应模型、依赖注入和安全时，Pydantic 一直会反复出现。

LoRA、QLoRA 与 Qwen2.5-VL：从理论到参数选择

Tue, 31 Mar 2026 00:00:00 GMT

这一篇对应原笔记里临时补上的 LoRA 理论部分。它的价值在于：把“LoRA 好用”从经验结论拉回到一个更能解释的层面。

一、LoRA 为什么可行

LoRA 的核心不是“神奇地省参数”，而是它假设：

模型在适应一个新任务时，真正需要的有效权重变化，往往处于一个相对低维的子空间里。

也就是说，虽然原模型参数很多，但为了适应一个具体任务，未必需要对整个高维权重空间做全量自由调整。

1. 从矩阵低秩近似来理解

原笔记把这件事讲得很直观：矩阵的信息往往不是均匀分布的，很多维度冗余，主要信息集中在少数方向上。

如果一个权重矩阵 W 是 d × d，全量更新的参数量是 d²。
而如果把增量写成两个低秩矩阵的乘积：

ΔW = B × A

其中：

B 是 d × r
A 是 r × d

那参数量就从 d² 变成了 2dr。

只要 r << d，参数量会急剧下降。

2. 为什么更新量可以低秩

LoRA 论文的核心观察之一，是微调前后权重差值 ΔW 的主要信息往往集中在少数奇异值上。

换句话说：

预训练权重 W 本身可能很复杂
但“为了适应新任务”产生的变化 ΔW，通常没有那么高的自由度

这就是 LoRA 低秩假设的经验基础。

二、LoRA 的训练过程

1. 初始化

LoRA 会冻结原始权重 W，只训练新增的低秩参数。

一般做法是：

W 不动
A 用较小随机值初始化
B 初始化为 0

这样一开始 ΔW = 0，不会干扰原模型。

2. 更新

训练时，模型实际使用的是：

W' = W + ΔW = W + B × A

前向传播时先得到预测结果，再根据损失函数对 A 和 B 做梯度更新，而 W 始终冻结。

3. 推理

训练后有两种常见方式：

合并 LoRA 权重后推理
保持 LoRA 旁路独立，按任务切换 adapter

这也是 LoRA 很适合多任务管理的原因之一。

三、LoRA 在 Transformer 里通常加在哪里

LoRA 常见的注入位置是：

注意力层里的 Wq / Wv
前馈层里的升维 / 降维线性层

它不是任何位置都加，而是优先加在那些最能影响表示能力和生成行为的线性层上。

1. 常见示意图

2. 常见经验

小模型可以先只加注意力层
更复杂的生成任务，往往会扩展到 FFN
并不是参数越多越好，而是要看任务复杂度和数据规模

四、QLoRA 是怎么把门槛继续压低的

QLoRA 本质上就是：

先把基础模型量化到 4-bit
冻结这些量化权重
只训练 LoRA 参数

所以它不是“LoRA 的平替”，而是：

量化 + LoRA 的组合方案

它最大的意义不是理论更漂亮，而是现实里真的能把显存需求拉下来，让更多单机环境也能做实验。

五、LoRA 的几个常用超参数

原笔记里对 LoRA 相关参数做了简要整理，这里直接沿着那条思路记：

1. `rank`

rank 决定了低秩更新的表达能力。

小：参数更省，更新更保守
大：表达能力更强，但计算和显存开销更高

原笔记里的经验是：

小数据集先从 r=8 或 r=16 开始
大数据集或更复杂任务，可以尝试 r=32+

2. `alpha`

alpha 可以理解成 LoRA 更新量的缩放系数，决定 LoRA 这条旁路影响原模型的强度。

3. `dropout`

dropout 更像是一点正则化，用来缓解小样本过拟合。

六、为什么这里顺手补 Qwen2.5-VL

因为这组实践最终就是做 Qwen2.5-VL 的多模态微调，所以如果对底座模型完全没有概念，后面的训练参数会显得很抽象。

Qwen2.5-VL 的特点可以先简单记成：

图像和视频是通过视觉编码器进入模型
视觉编码结果会和语言解码器对接
它对文档、表格、公式等复杂视觉内容也有比较强的建模能力

这也是为什么它适合后面那类“血迹图像描述 + 细粒度分类”的任务：
不是因为它天然懂这个领域，而是因为它作为多模态底座，已经具备了图像理解与文本生成的基础能力。

七、把理论留到一个足够实用的位置

学 LoRA 最容易掉进去的坑，是只记住“它省参数”，但不知道它到底省在哪、为什么能省。

这篇最重要的目的，其实就是把后面实战里那些参数和结果，提前和一层理论对应上：

为什么 rank 选小了会保守
为什么小数据集更容易过拟合
为什么 QLoRA 会改变显存门槛
为什么底座模型能力仍然决定最终上限

LangGraph 核心能力 04：Interrupt、恢复执行与 Human-in-the-loop

Tue, 31 Mar 2026 00:00:00 GMT

如果说持久化让图“记得住”，那 interrupt 则让图第一次真正具备“暂停下来等人类决定再继续”的能力。

中断功能可让你在指定节点暂停图执行流程，并等待外部输入后再继续运行。这支持需要外部输入才能推进的human-in-the-loop模式。当中断触发时，LangGraph 会通过其持久化层保存图状态，并无限期等待，直到你恢复执行。

中断的实现方式是在图节点的任意位置调用interrupt()函数。该函数可接收任意可 JSON 序列化的值，并将其暴露给调用方。当你准备继续时，可通过Command重新调用图来恢复执行，该 Command 会成为节点内部interrupt()调用的返回值。

与静态断点（在特定节点前后暂停）不同，中断是动态的：可置于代码任意位置，并可根据应用逻辑设置条件触发。

检查点会保留当前状态：检查点写入器会保存完整的图状态，即使处于错误状态，后续也可恢复执行。
thread_id 是状态指针：设置 config={"configurable": {"thread_id": ...}} 告诉检查点加载哪个状态。
中断载荷通过 chunk["interrupts"] 暴露：使用 version="v2" 流式传输时，传入interrupt()的值会出现在values流片段的interrupts字段中，便于知晓图正在等待什么。

选择thread_id本质上是持久化游标。重复使用可恢复同一检查点；使用新值则会以空状态启动全新线程。

1. 用interrupt暂停

interrupt函数会暂停图执行并向调用方返回一个值。在节点内调用interrupt时，LangGraph 会保存当前图状态，并等待你通过输入恢复执行。

使用interrupt需要满足：

一个检查点存储器用于持久化图状态（生产环境请使用持久化检查点存储器）
配置中包含线程 ID，使运行时知道从哪个状态恢复
在需要暂停的位置调用interrupt()（负载必须可 JSON 序列化）

调用interrupt时，会发生以下过程：

图执行会在调用interrupt的精确位置暂停
状态会通过检查点保存，以便后续恢复执行；生产环境中应使用持久化检查点（如基于数据库实现）
返回值会以__interrupt__标识返回给调用方；该值可以是任意可 JSON 序列化类型（字符串、对象、数组等）
图将无限期等待，直到你通过响应恢复执行
恢复时响应会传回节点，并成为interrupt()调用的返回值

下面有一个简单的动作批准函数：

from typing_extensions import TypedDict

from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import END, START, StateGraph
from langgraph.types import Command, interrupt


class State(TypedDict):
    approved: bool


def approval_node(state: State):
    # 运行到这里会暂停，并把这段提示抛给调用方
    approved = interrupt("Do you approve this action?")
    # 恢复时，Command(resume=...) 传入的值会回到 approved
    return {"approved": approved}


checkpointer = MemorySaver()
graph = (
    StateGraph(State)
    .add_node("approval", approval_node)
    .add_edge(START, "approval")
    .add_edge("approval", END)
    .compile(checkpointer=checkpointer)
)

config = {"configurable": {"thread_id": "approval-demo"}}

# 第一次执行：会在 interrupt() 处暂停
result = graph.invoke({"approved": False}, config)
interrupts = result.get("__interrupt__", ())

if interrupts:
    question = interrupts[0].value
    user_text = input(f"{question} (y/n): ").strip().lower()
    approved = user_text in {"y", "yes", "true", "1"}

    # 第二次执行：用 Command(resume=...) 恢复
    result = graph.invoke(Command(resume=approved), config)
    print("Final state:", result)
else:
    print("No interrupt happened:", result)

这其中，result的真实格式如下：

{
  "approved": False,
  "__interrupt__": [
    Interrupt(
      value="Do you approve this action?",
      id="7e5f3e800a66e12f26f09eca9a35ac50"
    )
  ]
}

我们知道，原始invoke一个节点的时候，会返回整个state，其中我们关注的比较多的是包含AIMessage/ToolMessage/HumanMessage等的state["messages"]通道，但是这个state里面还有我们自己定义的approved:bool，所以也会被放在state中供我们查阅和更新。

最终效果如下：

2. 常见工作模式

中断机制的核心价值在于能够暂停执行流程并等待外部输入。这一特性适用于多种应用场景，包括：

审批工作流：执行关键操作（API 调用、数据库修改、金融交易）前暂停
处理多中断：单次调用中恢复多个中断时，将中断 ID 与恢复值配对
审核与编辑：允许人工在继续执行前审核并修改大模型输出或工具调用
中断工具调用：执行工具调用前暂停，以便审核和编辑工具调用内容
验证人工输入：进入下一步前暂停，以验证人工输入

2.1 审批工作流

这是最常见的用法：在执行关键动作前先暂停，把动作详情抛给人工，人工批准后再继续，不批准则走取消分支。

from typing import Literal, Optional
from typing_extensions import TypedDict

from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import StateGraph, START, END
from langgraph.types import Command, interrupt


class ApprovalState(TypedDict):
    action_details: str
    status: Optional[Literal["pending", "approved", "rejected"]]


def approval_node(state: ApprovalState) -> Command[Literal["proceed", "cancel"]]:
    decision = interrupt({
        "question": "Approve this action?",
        "details": state["action_details"],
    })
    return Command(goto="proceed" if decision else "cancel")


def proceed_node(state: ApprovalState):
    return {"status": "approved"}


def cancel_node(state: ApprovalState):
    return {"status": "rejected"}


graph = (
    StateGraph(ApprovalState)
    .add_node("approval", approval_node)
    .add_node("proceed", proceed_node)
    .add_node("cancel", cancel_node)
    .add_edge(START, "approval")
    .add_edge("proceed", END)
    .add_edge("cancel", END)
    .compile(checkpointer=MemorySaver())
)

config = {"configurable": {"thread_id": "approval-1"}}

first = graph.invoke(
    {"action_details": "Transfer $500", "status": "pending"},
    config=config,
)
print(first["__interrupt__"])

final = graph.invoke(Command(resume=True), config=config)
print(final)

这里 Command(resume=True) 表示批准，Command(resume=False) 表示拒绝。节点恢复后，会根据这个布尔值决定跳转到哪个节点。

2.2 处理多中断

当图里有并行分支，而且多个分支同时执行到 interrupt() 时，一次运行里可能会返回多个中断。此时恢复时不能只传一个值，而是要把每个中断的 id 和它对应的恢复值配对起来。

from typing import Annotated
from typing_extensions import TypedDict
import operator

from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import START, END, StateGraph
from langgraph.types import Command, interrupt


class State(TypedDict):
    vals: Annotated[list[str], operator.add]


def node_a(state: State):
    answer = interrupt("question_a")
    return {"vals": [f"a:{answer}"]}


def node_b(state: State):
    answer = interrupt("question_b")
    return {"vals": [f"b:{answer}"]}


graph = (
    StateGraph(State)
    .add_node("a", node_a)
    .add_node("b", node_b)
    .add_edge(START, "a")
    .add_edge(START, "b")
    .add_edge("a", END)
    .add_edge("b", END)
    .compile(checkpointer=InMemorySaver())
)

config = {"configurable": {"thread_id": "multi-interrupt-1"}}

first = graph.invoke({"vals": []}, config=config)
interrupts = first["__interrupt__"]

resume_map = {
    interrupt_obj.id: f"answer for {interrupt_obj.value}"
    for interrupt_obj in interrupts
}

final = graph.invoke(Command(resume=resume_map), config=config)
print(final)

也就是说：

单个中断时，resume 可以直接传一个值
多个中断时，resume 应该传一个字典：{interrupt_id: resume_value}

2.3 审核与编辑

这种模式不是简单地“同意/拒绝”，而是把当前状态中的某一部分内容交给人工修改，然后把修改后的内容写回 state。

from typing_extensions import TypedDict

from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import StateGraph, START, END
from langgraph.types import Command, interrupt


class ReviewState(TypedDict):
    generated_text: str


def review_node(state: ReviewState):
    updated = interrupt({
        "instruction": "Review and edit this content",
        "content": state["generated_text"],
    })
    return {"generated_text": updated}


graph = (
    StateGraph(ReviewState)
    .add_node("review", review_node)
    .add_edge(START, "review")
    .add_edge("review", END)
    .compile(checkpointer=MemorySaver())
)

config = {"configurable": {"thread_id": "review-1"}}

first = graph.invoke({"generated_text": "Initial draft"}, config=config)
print(first["__interrupt__"])

final = graph.invoke(
    Command(resume="Improved draft after review"),
    config=config,
)
print(final)

这里恢复时传入的不是布尔值，而是“人工编辑后的最终文本”。这个值会直接成为 interrupt() 的返回值，再被写回 generated_text。

2.4 中断工具调用

interrupt() 不一定只能写在普通节点里，也可以直接写在工具函数里。这样当模型调用这个工具时，工具会先暂停，等待人工审批或修改参数，之后才真正执行。

from langchain_core.tools import tool
from langgraph.types import interrupt


@tool
def send_email(to: str, subject: str, body: str):
    """Send an email to a recipient."""
    response = interrupt({
        "action": "send_email",
        "to": to,
        "subject": subject,
        "body": body,
        "message": "Approve sending this email?",
    })

    if response.get("action") == "approve":
        final_to = response.get("to", to)
        final_subject = response.get("subject", subject)
        final_body = response.get("body", body)
        return f"Email sent to {final_to} with subject '{final_subject}'"

    return "Email cancelled by user"

这种方式常见于：

发邮件
调外部 API
写数据库
下单、转账、删除记录

也就是说，人工不仅可以批准，还可以顺手修改工具参数，然后再继续执行。

2.5 验证人工输入

有些场景下，人工输入本身可能不合法。这时可以在同一个节点里循环调用 interrupt()，直到拿到合法输入为止。

from langgraph.types import interrupt


def get_age_node(state):
    prompt = "What is your age?"

    while True:
        answer = interrupt(prompt)

        if isinstance(answer, int) and answer > 0:
            break
        else:
            prompt = f"'{answer}' is not a valid age. Please enter a positive number."

    return {"age": answer}

使用方式如下：

第一次暂停，提示 "What is your age?"
如果恢复时传入 "thirty"，校验不通过，会再次 interrupt()
再恢复时传入 30，校验通过，节点才真正返回

这一模式很适合：

表单采集
参数确认
需要严格类型或格式的人工输入

PyTorch 线性回归：梯度下降与训练四步

Tue, 31 Mar 2026 00:00:00 GMT

这一篇主要整理自 liuer_pytorch/1-4.ipynb，以及我自己写过的 pytorch_learning/pytorch_1.py、pytorch_learning/pytorch_5.py。它们共同在做一件事：用一个最简单的任务，把“训练神经网络”这件事拆开。

1. 为什么从线性回归开始

我越来越觉得，PyTorch 的入门最好不要一上来就卷 CNN 或 Transformer。
线性回归虽然简单，但它几乎把训练流程里所有最基础的东西都露出来了：

数据长什么样
模型参数是什么
损失函数在优化什么
梯度下降到底怎么更新参数

很多后面更复杂的网络，其实都只是把这个流程换成了更复杂的函数。

2. 训练模型的四步

在课程笔记里，这条线很明确：

准备数据集
设计模型
设计损失函数和优化器
写训练循环

这四步几乎可以当成 PyTorch 的最小心智模型。后面不管做分类、卷积还是序列任务，都还是这四步。

3. 先用 NumPy 直觉理解梯度下降

在线性回归里，我们希望学到的关系是：

y = wx + b

如果用均方误差：

MSE = 1 / N * Σ (ŷ - y)^2

那么训练本质上就是不断调整 w 和 b，让误差越来越小。
课程里也提到了梯度下降、随机梯度下降，以及 mini-batch 为什么是一个工程上的折中：

整批数据一起算，稳定但更新慢
单样本更新，噪声更大但更容易跳出局部坏区域
mini-batch 在两者之间做 trade-off

这一层如果没想明白，后面 optimizer.step() 很容易变成一句纯咒语。

4. 用 PyTorch 写一个最小线性回归

下面这段代码基本就是我当时练手时的核心版本：

import numpy as np
import torch
import torch.nn as nn

x = np.arange(1, 12, dtype=np.float32).reshape(-1, 1)
y = 2 * x + 3


class LinearRegressionModel(nn.Module):
    def __init__(self, input_dim, output_dim):
        super().__init__()
        self.linear = nn.Linear(input_dim, output_dim)

    def forward(self, inp):
        return self.linear(inp)


model = LinearRegressionModel(1, 1)
optimizer = torch.optim.SGD(model.parameters(), lr=0.01)
criterion = nn.MSELoss()

这里最值得记住的是两点：

nn.Linear 已经把 wx + b 封装好了
model.parameters() 会把可学习参数交给优化器

真正的训练循环则是：

for epoch in range(1000):
    inputs = torch.from_numpy(x)
    labels = torch.from_numpy(y)

    optimizer.zero_grad()
    outputs = model(inputs)
    loss = criterion(outputs, labels)
    loss.backward()
    optimizer.step()

这里每一行都对应一个明确动作：

zero_grad()：清空上一次的梯度
model(inputs)：前向传播
criterion(...)：得到损失
loss.backward()：反向传播算梯度
optimizer.step()：更新参数

5. 为什么这一套值得反复记

我自己后来再看 CNN、RNN、Transformer 时，会发现很多“新东西”其实只是：

数据形状变了
模型结构变复杂了
损失函数换了
优化器可能从 SGD 变成 Adam

但训练主线没有变。

所以在 PyTorch 入门阶段，最值钱的不是“背了多少层名字”，而是把下面这个模板吃透：

for batch in dataloader:
    optimizer.zero_grad()
    pred = model(batch_x)
    loss = criterion(pred, batch_y)
    loss.backward()
    optimizer.step()

6. 这一阶段该记住什么

如果只保留最少的几句话，我会记：

线性回归不是为了学回归，而是为了学训练流程。
nn.Module + loss + optimizer + loop 是 PyTorch 最核心的训练骨架。
梯度下降不是黑盒，它只是在沿着损失下降的方向调整参数。

有了这一层，后面看 Tensor、Autograd 和更复杂网络时，就不容易失去主线。

强化学习入门：为什么需要 RL、术语与 MDP

Tue, 31 Mar 2026 00:00:00 GMT

在笔记一中, 我们将沿着RL建模路线, 一步一步得到现在通用的Agent+RL的算法基础.

Agent经过了很长时间的探索和发展, 做出过很多方面的探索. 想要一次对Agent进行完整的探索显然是不可能做到的, 因此本文主要参照其中一条线路 --大语言模型（LLM）与强化学习（RL）结合领域, 梳理其发展, 学习其中的关键论文和思想.

实质上, LLM结合RL的方向, 是为了让模型从"死记硬背"的文本生成器, 转变会思考, 能行动, 能与环境交互的自主Agent. 而这其中一个重要的概念就是对齐.

一. 鸿沟 -- 为什么需要RL ?

强化学习 ( reinforcement learning, RL) 作为机器学习的重要分支, 讨论的是智能体 (agent) 怎么在复杂、不确定的环境中 (environment) 里去最大化它所能获得的奖励.

强化学习是除监督学习和非监督学习之外的第三种基本的机器学习方法, 它不需要带标签的输入输出, 也不需要对非最优解精准的纠正, 而是通过智能体和环境不断交互, 尽可能从环境中获取奖励. 其示意图如下:

1. 意图理解鸿沟

监督微调（SFT）, 可以说是整个LLM训练的起点. 当时的训练, 包括GPT和BERT, 不管是few-shot, zero-shot还是什么, 都是通过在高质量的问答数据上进行微调, 让模型学会" 如何回答指令". 这一点同样延伸到了后面对于Agent的训练, 似乎已经成为人机交互惯式.

然而, 纯SFT有一个根本性的局限: 它无法解决对齐 ( Alignment ) 鸿沟. 在这里, 要简单介绍一下对齐的这个概念. 这里说的对齐, 实际上就是让大模型语言的行为, 输出和决策方式与其设计者 ( 人类操作者 ) 的意图, 价值观和指令保持一致的过程.

简而言之, 就是让大模型更像人, 向人"对齐", 做到听懂人话, 价值观正向, 诚实可信, 实用主义等等.

我忽然想到了之前看到过的一个新闻, 年轻的程序员因为研究问题每天花大量时间跟AI(ChatGPT)对话, 随着对话深入他渐渐认为自己是有某种"重大使命", 甚至认为一切都是虚构的, 而AI面对某些疯狂的幻想, 总是会给予鼓励的态度.孤立, 压力, 药物使用和缺乏睡眠, 本来就可能引发精神妄想，而AI对话往往会进一步加剧这一过程, 最终把自己送进了精神病院. 而在北美, 这种现象也不是个例, 感兴趣自行搜寻.

为什么SFT就很难实现这个愿景 ? 其中一个重要原因就是, SFT的本质是"模仿学习".

同一个开放式问题, 有多个正确但风格不同的回答, 但是SFT并没有判断哪一个更好的能力.
SFT模型无法进行复杂的价值衡量, 结果充满不确定性, 且容易受到context干扰 ( LLM刚兴起的时间, 网络上有大量用户利用上下文的干扰, 让AI输出NSFW甚至违背人类价值观的内容, 黑话称"破限")
对人类潜在或深层意图的理解不够 ( 比如提问"希特勒有哪些煽动性的演讲技巧 ?" SFT表面可能理解为简单的论文演讲技巧学习, 去收集资料详细罗列其手法, 而不加入批判和风险提示. 所以部分有邪恶目的的人, 利用AI的理解鸿沟也可以获取自己想要的信息 )

2. 能力鸿沟

如前文所论述, SFT本质上是模仿学习, 高度依赖于人类给定的数据集. 但是这些数据集也是来源于人类的, 所以说, SFT的最高上限就是人类的能力了. 但是, 如果使用强化学习, 让智能体自己在环境中探索, 有非常大大潜力, 它可以获得超越人类的表现.

比如早年名声大噪的AlphaGo击败顶级人类棋手.

3. 场景鸿沟

除了同一场景学习效果上的差别, 光是SFT, 还存在一些无法满足的场景, 或者说硬伤. 我们在监督学习中, 有两个最基本的假设:

输入的数据(标注的数据) 都应该是没有关联的, 或着说样本之间应该是独立同分布的. 否则, 学习器将不好学习.
我们必须告诉学习器正确的标签.

但是一些情况下, 这两个条件都是不可满足. 设想这样一个场景, 我们要学习Pong游戏的玩法, 但是游戏的画面帧与帧之间是相关的时间序列数据, 并且, 决策没有获得反馈, 游戏没法知道哪个动作是“正确动作”. 但是, 我们依然希望智能体能够学习, 这就需要用到强化学习.

4. 强化学习的特征与历史

我们可以总结一些强化学习的特征如下:

强化学习会进行试错探索, 它通过探索环境来获取对环境的一些理解.
强化学习智能体从环境中获得延迟的奖励
强化学习过程中, 时间非常重要, 因为得到的是时间关联的数据.
强化学习中, 智能体当前的动作会影响它随后的数据, 智能体需要保持稳定.

强化学习并非凭空出世的奇想, 它是有一定的历史. 早期的强化学习, 一般被称为标准强化学习. 而最近业界把强化学习与深度学习结合起来, 就形成了深度强化学习, 深度强化学习= 深度学习 + 强化学习.

二. 概念 -- 强化学习中基本术语

强化学习中有太多的概念了, 在不熟悉的情况下分散了解, 将非常打消阅读的热情. 在第二章中将常见的术语一并介绍, 方便回头查询, 也方便快速进入强化学习的理论情景中.

探索 (exploration) 指的是尝试一些新的动作, 这些动作的奖励不确定.
利用 (exploitation) 指的是采取已知的可以获取更多奖励的动作
预演 (rollout) 指的是从当前帧度动作进行采样, 生成很多局游戏. 当然, 这个词在中文社区的翻译更多为“回合”或者“轨迹采样”.
轨迹 (trajectory, $\tau$ ) : 当前智能体与环境交互, 会得到一系列观测 (observation), 每一个观测可以看成一个轨迹. 轨迹就是从当前帧以及它采取的策略, 即状态和动作的序列:

$$ \tau = (s_0,a_0,s_1,a_1...) \tag{2.1} $$
最终奖励 (eventual reward)
一场游戏被称为一个回合 (episode) 或者试验 (trial)
序列决策 (sequential decision making) : 智能体把动作输出给环境, 环境取得这个动作之后会进行下一步, 把下一步的观测与这个动作带来的奖励返还给智能体. 智能体的目的是选取一系列动作来最大化奖励.
学习(learning) 和 规划(planning) 是序列决策中的两个基本问题. 在学习中, 环境初始时是位置的, 它通过不断与环境交互, 逐步改进策略; 在规划中, 环境是已知的, 智能体能够计算出一个玩咩的模型, 并且在不需要与环境进行任何交互的时候进行计算, 寻找最优解.
探索(exploration) 和 利用(exploration) 是强化学习中的两个核心问题. 因为尝试次数有限, 这两者实际上是矛盾的, 加强一方就会削弱另一方, 这就是强化学习中的探索-利用窘境 (exploration-exploitation dilemma).
奖励信号 (reward signal) : 奖励是环境给的一种标量化的反馈信号. 智能体在环境里存在的目的就是最大化它的期望的累积奖励 (expected cummulative reward).
历史是观测、动作、奖励的序列 (下标t一般表示当前步):

$$ H_t=o_1,a_1,r_1,...,o_t,a_t,r_t \tag{2.2} $$
状态是对世界的完整描述, 不会隐藏世界的信息. 观测是对状态的部分描述, 可能会遗漏一些信息. 整个游戏的状态可以看作关于历史的函数:

$$ s_t=f(H_t) \tag{2.3} $$
完全可观测 (fully observed): 环境有自己的函数$s^c_t=f^c(H_t)$ 来更新状态, 智能体内部有$s^a_t=f^a(H_t)$ 来更新状态. 当智能体状态与环境状态等价的时候, 即当智能体能够观察到环境的所有状态时, 我们称这个环境是完全可观测的.

$$ o_t=s^c_t=s^a_t \tag{2.4} $$
当完全可观测时, 强化学习通常被建模为马尔可夫决策过程(MDP); 部分可观测下则会被建模为部分可观测马尔可夫决策过程(POMDP).
动作空间 (action space) 指的是给定环境中有效动作的集合. 如果智能体的动作数量有限就叫做离散动作空间 (discrete action space) , 如果智能体的动作是实值的向量, 则是连续动作空间 (continuous action space)
策略 (policy): 智能体会用策略来选取下一步的动作. 策略可以分为随机性策略 (stochastic policy)和确定性策略 (deterministic policy).
价值函数 (value function): 价值函数用于评估智能体进入某个状态后, 可以对后面的奖励带来多大的影响. 价值函数值越大, 说明智能体进入这个状态越有利. 加入折扣因子 (discount factor), 价值函数可以被定义为:

$$ V_\pi(s)\doteq\mathbb{E}\pi\left[G_t\mid s_t=s\right]=\mathbb{E}\pi\left[\sum_{k=0}^\infty\gamma^kr_{t+k+1}\mid s_t=s\right],\quad \forall s\in S \tag{2.5} $$
式2.5中, $\mathbb{E}_\pi$ 的下标为$\pi$ 函数, 它的值可以反映我们在使用策略$\pi$ 的时候, 到底可以获得多少奖励.
Q函数: 也是一种价值函数, 其中包含两个变量: 状态和动作. 其定义为: $$ Q_\pi(s,a) \doteq \mathbb{E}\pi\left[G_t \mid s_t=s, a_t=a\right] = \mathbb{E}\pi\left[\sum_{k=0}^\infty \gamma^k r_{t+k+1} \mid s_t=s, a_t=a\right]\tag{2.6} $$
模型 (model): 模型表示智能体对环境状态进行理解, 它决定了环境中世界的运行方式. 模型决定了下一步的状态, 下一步的状态取决于当前的状态以及当前采取的动作. 它由状态转移概率和奖励函数两个部分组成. 状态转移概率即:

$$ p_{ss^{\prime}}^a=p\left(s_{t+1}=s^{\prime}\mid s_t=s,a_t=a\right)\tag{2.7} $$

即某s中采取某a并非一定可以得到特定的下一个s, 而是概率的. 奖励函数是指我们在当前状态采取了某个动作, 可以获得多大奖励:

$$ R(s,a)=\mathbb{E}\left[r_{t+1}\mid s_t=s,a_t=a\right] \tag{2.8} $$
马尔可夫决策过程(Markov decision process) 由策略、价值函数和模型三个部分组成. 如下图, 这个决策过程可视化了状态的转移和采取的动作:
智能体可以分为基于价值的智能体 (value-based agent) 和基于策略的智能体 (policy-based agent). 前者显式学习价值函数, 隐式学习策略; 后者直接学习策略, 我们给出一个状态, 它就会输出对应动作的概率.
基于价值和基于策略的智能体结合可以得到演员-批评家智能体 (actor-critic agent), 这一类智能体吧策略和价值函数都学习了, 通过两者的交互得到最佳的动作.
智能体还可以分为有模型(model-based) 和 免模型(model-free), 前者通过学习状态的转移来采取动作(如DP, 蒙特卡洛), 后者没有直接估计状态的转移, 也没有得到环境的具体转移变量, 它通过学习价值函数和策略函数进行决策(如Q-learning, DQN和Policy Gradient).
有模型强化学习比免模型强化学习多出一个步骤, 就是对真实世界建模. 免模型强化学习通常属于数据驱动方法, 需要大量的采样来估计状态、动作及奖励函数, 从而优化动作策略.
范围 (Horizon): 一个回合的长度(每个回合最大的时间步数), 它是由有限个步骤决定的.
回报 (return): 可以定义为奖励的逐步累加, 假设时刻$t$ 后的奖励序列为$r_{t+1}, r_{t+2}, r_{t+3}, \cdots$ , 折扣因子为$\gamma$ , 越往后得到的奖励折扣越多. 则回报为:

$$ G_t = r_{t+1} + \gamma r_{t+2} + \gamma^2 r_{t+3} + \gamma^3 r_{t+4} + \ldots + \gamma^{T-t-1} r_T \tag{2.9} $$
折扣因子(discount factor): 我们使用折扣因子, 一方面过程转移可能是带环的, 我们要避免无限循环; 另一方面, 我们并不能建立完美的模拟环境的模型, 我们对未来的评估不一定是准确的; 还有就是, 如果奖励是有实际价值的, 我们更希望立刻就获得奖励, 而不后面再得到奖励.

三. 马尔可夫决策过程

对基本术语进行一定程度的梳理之后, 我们就可以进入强化学习的语境当中. 但是在学习具体的算法之前, 我们还是要进行一定程度的理论扩容, 特别需要理解算法产生的背景. 紧接着我们就会介绍马尔可夫决策过程控制的两种算法, 策略迭代和价值迭代.

1. 马尔可夫性质 (Markov property)

马尔可夫性质 (Markov property) 是指一个随机过程在给定现在状态及所有过去状态情况下, 其未来状态的概率分布仅依赖于当前状态. 以离散随机过程为例, 假设随机变量$X_{0},X_{1},\cdots,X_{T}$ 构成一个随机过程, 这些随机变量的所有可能取值的集合被称为状态空间 (state space), 如果过去状态的条件概率分布为仅是$X_t$ 的一个函数, 则:

$$ p\left(X_{t+1}=x_{t+1}\mid X_{0:t}=x_{0:t}\right)=p\left(X_{t+1}=x_{t+1}\mid X_{t}=x_{t}\right) \tag{3.1} $$ 其中, $X_{0:t}$ 表示变量集合$X_{0},X_{1},\cdots,X_{T}$ , $x_{0:t}$ 表示状态空间中的状态序列$x_0,x_1,\cdots,x_t$ .

马尔可夫性质也可以描述为, 将来的状态和过去的状态是条件独立的.

2. 马尔可夫链(Markov chain)

马尔可夫过程是一组具有马尔可夫性质的随机变量序列$s_0,s_1,\cdots,s_t$ 其中下一个时刻的状态$s_{t+1}$ 只取决于当前状态$s_{t}$ .

我们设状态的历史为$h_t={s_1,s_2,s_3,\cdots,s_t}$ ($h_t$ 包含了之前的所有状态), 则马尔可夫过程满足条件:

$$ p(s_{t+1} | s_t) = p(s_{t+1} | h_t) \tag{3.2} $$ 也就是说, 从当前$s_t$ 转移到$s_{t+1}$ ,它是直接就等于它之前所有的状态转移到$s_{t+1}$ . 离散时间的马尔可夫过程也被称为马尔可夫链(Markov chain). 我们可以用状态转移矩阵(state transition matrix) $P$ 来描述状态转移 $p(s_{t+1}= s'|s_t=s)$: $$ \boldsymbol{P}=\left(\begin{array}{cccc}p\left(s_{1}\mid s_{1}\right)&p\left(s_{2}\mid s_{1}\right)&\ldots&p\left(s_{N}\mid s_{1}\right)\p\left(s_{1}\mid s_{2}\right)&p\left(s_{2}\mid s_{2}\right)&\ldots&p\left(s_{N}\mid s_{2}\right)\\vdots&\vdots&\ddots&\vdots\p\left(s_{1}\mid s_{N}\right)&p\left(s_{2}\mid s_{N}\right)&\ldots&p\left(s_{N}\mid s_{N}\right)\end{array}\right) \tag{3.3} $$

3. 马尔可夫奖励过程 (Markov reward process, MRP)

马尔可夫奖励过程 (Markov reward process, MRP) 是马尔可夫链加上奖励函数. 在马尔可夫奖励过程中, 状态转移矩阵和状态都与马尔可夫链一样, 只是多了奖励函数.

前面已经介绍过回报$G_t$ , 我们可以定义状态的价值, 就是状态价值函数 (state-value function) :

$$ \begin{aligned} V^{t}(s) &= \mathbb{E}\left[G_{t} \mid s_{t} = s\right] \ &= \mathbb{E}\left[r_{t+1} + \gamma r_{t+2} + \gamma^{2} r_{t+3} + \ldots + \gamma^{T-t-1} r_{T} \mid s_{t} = s\right] \end{aligned} \tag{3.4} $$ 这个期望就是从这个状态开始, 我们可能获得多大的价值. 也可以说是, 未来可能获得的价值在当前价值的表现, 就是当我们进入某一个状态后, 我们现在能有多大的价值.

4. 贝尔曼方程

前面已经得出来了状态价值函数, 这里就引出了一个问题: 当我们有了一些轨迹的实际回报时, 怎么计算它的价值函数. 一个可行的方法就是从当前状态生成许多轨迹, 然后把轨迹都叠加起来 (比如取平均值, 这就是一种计算价值函数的方法, 被称为蒙特卡洛(MonteCarlo, MC) 采样). 但是我们这里学习另一种更多的方法, 就是从价值函数里推导出贝尔曼方程.

贝尔曼方程 (Bellman equation) 就是当前状态与未来状态的迭代关系, 表示当前状态的价值函数可以通过下个状态的价值函数来计算.

我们现在来推导这个公式, 首先我们需要得出推导所需要的一个前置公式4.3.

为了简洁, 我们把当前步的t下标去掉, 而把t+1步下标改成t‘, 按照期望的定义, 我们重写回报的期望:

$$ \begin{aligned} \mathbb{E}\left[G_{t+1} \mid s_{t+1}\right] &= \mathbb{E}\left[g^{\prime} \mid s^{\prime}\right] \ &= \sum_{g^{\prime}} g^{\prime} , p\left(g^{\prime} \mid s^{\prime}\right) \end{aligned} \tag{4.1} $$

我们再次对式4.1求期望: $$ \begin{aligned}\mathbb{E}\left[\mathbb{E}\left[G_{t+1}\mid s_{t+1}\right]\mid s_{t}\right]&=\mathbb{E}\left[\mathbb{E}\left[g^{\prime}\mid s^{\prime}\mid s\right]\mid s\right]\&=\mathbb{E}\left[\sum_{g^{\prime}}g^{\prime}\left.p\left(g^{\prime}\mid s^{\prime}\right)\mid s\right]\right]\&=\sum_{{s^{\prime}}}\sum_{{g^{\prime}}}g^{\prime}p\left(g^{\prime}\mid s^{\prime},s\right)p\left(s^{\prime}\mid s\right)\&=\sum_{{s^{\prime}}}\sum_{{g^{\prime}}}\frac{g^{\prime}p\left(g^{\prime}\mid s^{\prime},s\right)p\left(s^{\prime}\mid s\right)p(s)}{p(s)}\&=\sum_{{s^{\prime}}}\sum_{{g^{\prime}}}\frac{g^{\prime}p\left(g^{\prime}\mid s^{\prime},s\right)p\left(s^{\prime},s\right)}{p(s)}\&=\sum_{{s^{\prime}}}\sum_{{g^{\prime}}}\frac{g^{\prime}p\left(g^{\prime},s^{\prime},s\right)}{p(s)}\&=\sum_{{s^{\prime}}}\sum_{{g^{\prime}}}g^{\prime}p\left(g^{\prime},s^{\prime}\mid s\right)\&=\sum_{{g^{\prime}}}\sum_{{g^{\prime}}}g^{\prime}p\left(g^{\prime},s^{\prime}\mid s\right)\&=\sum_{{g^{\prime}}}g^{\prime}p\left(g^{\prime}\mid s\right)\&=\mathbb{E}\left[g^{\prime}\mid s\right]=\mathbb{E}\left[G_{t+1}|s_t\right] \end{aligned} \tag{4.2} $$ $$ E[G_{t+1}|s_t] = E[ E[G_{t+1}|s_t, s_{t+1}] | s_t] = E[ E[G_{t+1}|s_{t+1}] | s_t] $$

而实际上, 结合状态价值函数的定义3.4, 我们可以得到4.2的期望就是对价值函数的期望, 然后结合4.2 就得到了: $$ \mathbb{E}[V(s_{t+1})|s_t]=\mathbb{E}[\mathbb{E}[G_{t+1}|s_{t+1}]|s_t]=\mathbb{E}\left[G_{t+1} \mid s_{t}\right] \tag{4.3} $$ 这个4.3就是推导贝尔曼公式重要的前提. 现在我们就开始推导贝尔曼公式: $$ \begin{aligned}V(s)&=\mathbb{E}\left[G_t\mid s_t=s\right]\&=\mathbb{E}\left[r_{t+1}+\gamma r_{t+2}+\gamma^2r_{t+3}+\ldots\mid s_t=s\right]\&=\mathbb{E}\left[r_{t+1}|s_t=s\right]+\gamma\mathbb{E}\left[r_{t+2}+\gamma r_{t+3}+\gamma^2r_{t+4}+\ldots\mid s_t=s\right]\&=R(s)+\gamma\mathbb{E}[G_{t+1}|s_t=s]\&=R(s)+\gamma\mathbb{E}[V(s_{t+1})|s_t=s]\&=R(s)+\gamma\sum_{s^{\prime}\in S}p\left(s^{\prime}\mid s\right)V\left(s^{\prime}\right)\end{aligned} \tag{4.4} $$ 4.4就是我们需要的状态价值函数的迭代形式, 贝尔曼公式. 它说明了当前状态的价值, 是由当前的回报和未来状态的价值的总和.

如果要得到所有的状态价值, 我们可以把贝尔曼方程写成矩阵的形式: $$ \left.\left(\begin{array}{c}V\left(s_{1}\right)\V\left(s_{2}\right)\\vdots\V\left(s_{N}\right)\end{array}\right.\right)=\left(\begin{array}{c}R\left(s_{1}\right)\R\left(s_{2}\right)\\vdots\R\left(s_{N}\right)\end{array}\right)+\gamma\left(\begin{array}{cccc}p\left(s_{1}\mid s_{1}\right)&p\left(s_{2}\mid s_{1}\right)&\ldots&p\left(s_{N}\mid s_{1}\right)\p\left(s_{1}\mid s_{2}\right)&p\left(s_{2}\mid s_{2}\right)&\ldots&p\left(s_{N}\mid s_{2}\right)\\vdots&\vdots&\ddots&\vdots\p\left(s_{1}\mid s_{N}\right)&p\left(s_{2}\mid s_{N}\right)&\ldots&p\left(s_{N}\mid s_{N}\right)\end{array}\right)\left(\begin{array}{c}V\left(s_{1}\right)\V\left(s_{2}\right)\\vdots\V\left(s_{N}\right)\end{array}\right) \tag{4.5} $$ 而写成矩阵形式后, 实际上我们可以用求矩阵逆的方法来求解析解: $$ \begin{aligned} \boldsymbol{V}&=\boldsymbol{R}+\gamma\boldsymbol{P}\boldsymbol{V}\ \boldsymbol{I}\boldsymbol{V}&=\boldsymbol{R}+\gamma\boldsymbol{P}\boldsymbol{V}\ (\boldsymbol{I}-\gamma\boldsymbol{P})\boldsymbol{V}&=\boldsymbol{R}\ \boldsymbol{V}&=(\boldsymbol{I}-\gamma\boldsymbol{P})^{-1}\boldsymbol{R}\end{aligned} \tag{4.6} $$ 但是矩阵求逆的过程的复杂度都是$O(N^3)$ , 计算量非常大, 所以这只适用于很小量的马尔可夫奖励过程.

5. 求解价值的方法

对于强化学习而言, 最终的目标是求出最优策略, 所有策略评估 是非常重要的.

已知马尔可夫决策过程以及要采取的策略$\pi$ , 计算价值函数$V_\pi(s)$ 的过程就是策略评估, 策略评估在有些地方也被称为 (价值)预测[(value) prediction].

由于这个评估需要贯穿强化学习的始终, 在这里展开介绍所有方法是不合适的, 因此读者可以多留意之后一些算法当中, 都会有的策略评估的过程和方法.

6. 马尔可夫决策过程 (Markov decision process, MDP)

相对于马尔可夫奖励过程, 马尔可夫决策过程多了决策 (决策是指动作), 其他的定义与马尔可夫奖励过程是类似. 此外状态转移概率也多了一个条件, 变成了$p(s_{t+1}=s'|s_t=s,a_t=a)$. 它的意思是, 未来的状态不仅依赖于现在的状态, 也依赖于在当前状态智能体采取的动作. 马尔可夫决策过程满足: $$ p(s_{t+1} | s_t, a_t) = p(s_{t+1} | h_t, a_t) \tag{6.1} $$ 对于奖励函数, 也多了一个当前的动作, 变成了

$$ R(s_{t}=s,a_{t}=a)=\mathbb{E}[r_{t}\mid s_{t}=s,a_{t}=a] \tag{6.2} $$ 由于开始涉及到智能体的动作了, 所以就要有一定的策略. 前面我们已经知道, 策略定义了在某一个状态应该采用什么动作, 所以知道当前状态之后, 我们带入策略函数就能得到一个策略: $$ \pi(a \mid s) = p(a_t = a \mid s_t = s) \tag{6.3} $$ 这里的概率, 就代表了在所有可能的动作里面怎样采取行动. (比如0.5概率往左, 0.5概率往右).

已知马尔可夫决策过程 (别忘了, 马尔可夫决策过程实际上就是策略+价值函数+模型)和策略函数$\pi$ , 我们就可以将马尔可夫决策过程转化成马尔可夫奖励过程. 因为我们已知策略函数, 也就是已知每种状态下, 可能采取的动作的概率, 所以我们就可以直接把动作进行加和, 去掉动作$a$, 用策略(概率)来代替 : $$ P_\pi\left(s^{\prime}\mid s\right)=\sum_{a\in A}\pi(a\mid s)p\left(s^{\prime}\mid s,a\right) \tag{6.4} $$ 对于奖励函数, 同样把动作去掉, 得到类似马尔可夫奖励过程的奖励函数: $$ r_\pi(s)=\sum_{a\in A}\pi(a\mid s)R(s,a) \tag{6.5} $$ 马尔可夫决策过程的价值函数定义的与式3.4一样. 但是由于我们这里多出了动作a, 不好处理. 所以我们这里引入了一个Q函数 (Q-function), Q函数也被称为动作价值函数 (actino-value). Q函数的定义是在某一个状态采取某一个动作, 它有可能得到的回报的一个期望, 即: $$ Q_\pi(s,a)=\mathbb{E}\pi\left[G_t\mid s_t=s,a_t=a\right] \tag{6.6} $$ 这里的期望也是基于策略函数的, 所以我们要对策略函数进行一个加和, 然后得到它的价值. 对于Q函数中的动作进行加和, 就可以得到价值函数: $$ V\pi(s)=\sum_{a\in A}\pi(a\mid s)Q_\pi(s,a) \tag{6.7} $$ 紧接着, 我们对Q函数的贝尔曼方程进行推导, 类似于上述4.4的推导: $$ \begin{aligned}Q(s,a)&=\mathbb{E}\left[G_t\mid s_t=s,a_t=a\right]\&=\mathbb{E}\left[r_{t+1}+\gamma r_{t+2}+\gamma^2r_{t+3}+\ldots\mid s_t=s,a_t=a\right]\&=\mathbb{E}\left[r_{t+1}|s_t=s,a_t=a\right]+\gamma\mathbb{E}\left[r_{t+2}+\gamma r_{t+3}+\gamma^2r_{t+4}+\ldots\mid s_t=s,a_t=a\right]\&=R(s,a)+\gamma\mathbb{E}[G_{t+1}|s_t=s,a_t=a]\&=R(s,a)+\gamma\mathbb{E}[V(s_{t+1})|s_t=s,a_t=a]\&=R(s,a)+\gamma\sum_{s^{\prime}\in S}p\left(s^{\prime}\mid s,a\right)V\left(s^{\prime}\right)\end{aligned} \tag{6.8} $$ 我们可以看到上述6.9和6.10代表了状态价值函数与Q函数之间的关联, 因为Q中有V, V中有Q.

观察形式, 状态价值函数和Q函数都可以拆分成两个部分: 即时奖励和后续状态的折扣价值. 通过对状态价值函数进行分解, 我们可以得到类似于之前马尔可夫奖励过程的贝尔曼方程 -- 贝尔曼期望方程 (Bellman expectation equation). $$ V_\pi(s)=\mathbb{E}\pi\left[r{t+1}+\gamma V_\pi\left(s_{t+1}\right)\mid s_t=s\right] \tag{6.9} $$ 类似的, 对于Q函数分解, 得到贝尔曼期望方程: $$ Q_{\pi}(s,a) = \mathbb{E}{\pi}\left[r{t+1} + \gamma Q_{\pi}(s_{t+1},a_{t+1}) , \middle| , s_t = s, a_t = a\right], a_{t+1} \sim π(·|s_{t+1})\tag{6.10} $$ 我们继续往下推导, 首先把6.8在策略$\pi$ 的时候代入6.7, 可以得到: $$ V_\pi(s)=\sum_{a\in A}\pi(a\mid s)\left(R(s,a)+\gamma\sum_{s^{\prime}\in S}p\left(s^{\prime}\mid s,a\right)V_\pi\left(s^{\prime}\right)\right) \tag{6.11} $$

6.11表示了当前状态价值与未来状态价值的关联. 然后我们再反过来代入, 将6.7代入6.8中, 可以得到: $$ Q_\pi(s,a)=R(s,a)+\gamma\sum_{s^{\prime}\in S}p\left(s^{\prime}\mid s,a\right)\sum_{a^{\prime}\in A}\pi\left(a^{\prime}\mid s^{\prime}\right)Q_\pi\left(s^{\prime},a^{\prime}\right) \tag{6.12} $$ 这个式子代表了当前时刻的Q函数与未来时刻的Q函数之间的关联. 式6.11和6.12是贝尔曼期望方程的另一种形式.

7. 从建模走向控制问题

前面更多是在回答“给定环境和策略，价值到底怎么定义、怎么计算”；但强化学习真正关心的问题是：怎样找到更优的策略。因此，接下来视角会从建模与评估，转到控制与最优决策。

8. 马尔可夫决策过程控制

但是如果只有马尔可夫决策过程, 那么如何来寻找最佳的策略?

我们引入了最佳价值函数(optimal value function), 它是指我们搜寻一种策略$\pi$ 让每个状态的价值最大: $$ V^(s)=\max_\pi V_\pi(s) \tag{8.1} $$ 在这种最大化情况下, 得到的策略就是最佳策略: $$ \pi^(s)=\arg\max_\pi V_\pi(s) \tag{8.2} $$ 换句话说, 最佳策略让每个状态的价值函数都取到最大值. 所以如果我们可以得到一个最佳价值函数, 就可以认为某个马尔可夫决策过程的环境可解.

而在可解的情况下, 最佳价值函数是一致的, 环境中可达到的上限的值是一致的, 但这里可能有多个最佳策略.

当取得最佳价值函数后, 我们可以通过Q函数进行最大化来得到最佳策略: $$ \pi^(a\mid s)=\left{\begin{array}{ll}1,&a=\underset{a\in A}{\operatorname{\arg\max}}Q^(s,a)\0,&\text{其他}\end{array}\right. \tag{8.3} $$ 当Q函数收敛之后, 因为Q函数是关于状态与动作的函数, 所以如果在某个状态采取某个动作, 可以使Q函数最大化, 那么这个动作就是最佳的动作. 如果我们能优化出一个Q函数$Q^(s,a)$, 就可以直接在Q函数中取一个让Q函数值最大化的动作的值, 就可以提取出最佳策略.

吗? 那怎么提取呢. 其实最容易想到的方法, 就是穷举所有方法, 如果动作和状态有限, 就可以对每个状态采取A中动作的策略, 总共$|A|^{|S|}$ 个可能策略. 然算出每种策略下的价值函数问题就解决. 但是显然没有效率, 所以目前有两种常用的方法来搜索最佳策略.

(1) 策略迭代与贝尔曼最优方程

策略迭代不仅仅是求解上述model-based (即已知状态转移函数和奖励函数, 或者说已知价值函数) 的一种方法, 也是后面MDP继续优化的基础, 要好好学习其思想.

策略迭代 (Policy Iteration) 由两个步骤组成 -- 策略评估和和策略改进 (policy improvement). 在我们优化策略$\pi$ 时, 在优化过程中得到一个最新的策略. 我们先保持这个策略不变, 然后估计它的价值, 即给定当前的策略函数来估计状态价值函数的值. 然后, 得到状态价值函数后, 可以进一步计算它的Q函数. 得到Q函数后, 我们直接对Q函数进行最大化, 通过在Q函数做一个贪心的搜索来进一步改进策略, 这两个策略迭代进行.

接下来, 我们来具体看一下是怎么进行greedy进行策略改进的. 首先, 我们再复习一下, 已知第i个策略对应的状态价值函数, 我们可以根据6.8式得到Q, 如下: $$ Q_{\pi_i}(s,a)=R(s,a)+\gamma\sum_{s^{\prime}\in S}p\left(s^{\prime}\mid s,a\right)V_{\pi_i}\left(s^{\prime}\right) \tag{8.4} $$ 对于每个状态, 策略改进会得到它的新一轮的策略, 对于每个状态, 我们取得它得到最大值的动作, 即: $$ \pi_{i+1}(s)=\underset{a}{\operatorname*{\arg\max}}Q_{\pi_i}(s,a) \tag{8.5} $$ 这是一个确定性策略, 新的策略在每个状态s都确定性地选择能使 $Q_{π_i}(s, a)$ 最大的动作 a.

我们其实可以把Q函数看成一个Q表格 (Q-table), 横轴是它的状态, 纵轴是它可能的动作. 如果我们得到了Q函数, Q表格也就得到了. 所以上述argmax操作就是在选择每一列 (状态) 中最大的行 (动作).

当我们一直采取argmax操作的时候, 就会得到一个单调的递增. 我们通过采取这种贪心操作, 就会得到更好或者保持不变的策略, 而不是使价值函数变差. 所以当停止改进之后, 我们取让Q函数最大的动作, Q函数就会直接变成价值函数: $$ Q_\pi\left(s,\pi^{\prime}(s)\right)=\max_{a\in A}Q_\pi(s,a)=Q_\pi(s,\pi(s))=V_\pi(s) \tag{8.6} $$ 上述等式的意思是, 采用贪心a直到$\pi'$ 不会再比$\pi$ 的Q值大了, 这时这个Q就是V.

我们对等式最后一步做一点解释, 一般情况下, 马尔可夫决策过程中Q与V是满足6.7的关系, 即V是Q在$\pi$ 下的加权求和. 但是在最优策略下, 如8.3所示, 它是一个确定性策略, 最优动作的贡献为1, 其他动作贡献全部为0:

$$ V_{\pi^}(s) = \sum_{a} \pi^(a|s)Q_{\pi^}(s,a) = 1 \cdot Q_{\pi^}(s,a^) + 0 \cdot \text{其他} = Q_{\pi^}(s,a^*) \tag{8.7} $$

而其中的$a^$ 正是让Q最大的函数, 即$Q_{\pi^}(s, a^) = \max_{a} Q_{\pi^}(s, a)$, 所以得到了8.6的最后一个等号.

上述其实就是贝尔曼最优方程 (Bellman optimality equation), 贝尔曼最优方程表明最佳策略下的一个状态的价值必须等于在这个状态下采取最好动作得到的回报的期望. 换句话说, 最优状态价值就是最优动作价值的"最大价值": $$ V^(s)=\max_aQ^(s,a) \tag{8.8} $$ 然后结合Q值的贝尔曼方程6.8, 代入8.8可以得到: $$ \begin{aligned}Q^{}(s,a)&=R(s,a)+\gamma\sum_{s^{\prime}\in S}p\left(s^{\prime}\mid s,a\right)V^{}\left(s^{\prime}\right)\&=R(s,a)+\gamma\sum_{s^{\prime}\in S}p\left(s^{\prime}\mid s,a\right)\max_{a}Q^{*}(s^{\prime},a^{\prime})\end{aligned} \tag{8.9} $$ 于是我们的得到了Q的转移过程. 通过上述的讨论, 应该明白迭代式子得出的意义, 所以当然, Q学习就是基于这个8.9式进行的, 但是由于属于非常经典的算法, 所以我们放在后面单独介绍.

(2) 价值迭代

现在我们换个角度思考问题, 动态规划的方法将优化问题分成两个部分. 第一步执行的是最优的动作, 后继的状态每一步都按照最优策略去做, 最后的结果就是最优的.

这里我们可以引入最优性原理定理 (principle of optimality theorem): 一个策略$\pi(a|s)$ 在状态s达到了最优价值, 也就是$V_{\pi}(s)=V^(s)$ 成立, 当且仅当对于任何能从$s$ 到达的$s'$ , 都已经达到了最优价值, 也就是对于所有的$s'$ , $V_{\pi}(s')=V^(s')$ 恒成立.

这就告诉我们, 如果知道了子问题$V^*(s')$ 的最优解, 就可以通过价值迭代来得到最优的$V_{\pi}(s)$ 的解.

我们可以继续把8.9代入到8.8中: $$ \begin{aligned}V^(s)&=\max_aQ^(s,a)\&=\max_a\mathbb{E}[G_t|s_t=s,a_t=a]\&=\max_a\mathbb{E}[r_{t+1}+\gamma G_{t+1}|s_t=s,a_t=a]\&=\max_a\mathbb{E}[r_{t+1}+\gamma V^(s_{t+1})|s_t=s,a_t=a]\&=\max_a\mathbb{E}[r_{t+1}]+\max_a\mathbb{E}[\gamma V^(s_{t+1})|s_t=s,a_t=a]\&=\max_aR(s,a)+\max_a\gamma\sum_{s^{\prime}\in S}p\left(s^{\prime}\mid s,a\right)V^\left(s^{\prime}\right)\&=\max_a\left(R(s,a)+\gamma\sum_{s^{\prime}\in S}p\left(s^{\prime}\mid s,a\right)V^\left(s^{\prime}\right)\right)\end{aligned} \tag{8.10} $$ 这样, 我们就也得到了状态价值函数的转移. 我们把贝尔曼最优方程当作一个更新规则来进行, 即: $$ V(s)\leftarrow\max_{a\in A}\left(R(s,a)+\gamma\sum_{s^{\prime}\in S}p\left(s^{\prime}\mid s,a\right)V\left(s^{\prime}\right)\right) \tag{8.11} $$ 当整个马尔可夫决策过程以及达到最佳的状态时, 式8.11才满足. 但是我们可以转化为一个迭代的等式, 不断迭代贝尔曼最优方程, 价值函数就能逐渐趋向于最佳的价值函数, 这就是价值迭代算法的精髓. 价值迭代算法可以用下面过程总结:

初始化：令 k=1，对于所有状态 s，$V_{0}(s)$=0。
对于 k=1: H（H 是让 V(s) 收敛所需的迭代次数）
- 对于所有状态 s $Q_{k+1}(s,a)=R(s,a)+\gamma\sum_{s'\in S}p(s'|s,a)V_{k}(s')$ $V_{k+1}(s)=\max_{a}Q_{k+1}(s,a)$
- k←k+1。
在迭代后提取最优策略： $\pi(s)=\arg\max_{a}\left[R(s,a)+\gamma\sum_{s'\in S}p(s'|s,a)V_{H+1}(s')\right]$

四. 总结

至此, 我们奠定了强化学习解决序列决策问题的理论基础. 然而, 上述方法（策略迭代、价值迭代）通常要求我们知道环境的动态模型（即状态转移概率 P 和奖励函数 R）. 在现实中, 例如训练一个LLM Agent, 我们往往无法获得这个模型. 这就引出了下一章的核心——免模型强化学习, 包括著名的Q-learning、Policy Gradient等算法, 它们将是我们将LLM与RL结合的关键工具.

如果你是从头看到现在的, 劝你还是停一下, 冷静思考回顾一遍. 因为即使是写到这里, 也是花了我一个礼拜的时间, 但依然有被大量形式公式带着走的感觉.

回顾一下我们的历程. 我们要将强化学习建模为马尔可夫决策过程, 但是必须从基层开始. 开始, 我们只关注状态之间概率的转移, 叫做马尔可夫过程. 然后我们给每个状态加上奖励值, 这就构成了马尔可夫奖励过程(MRP), 紧接着, 我们根据定义得出来每个状态的价值函数, 并通过贝尔曼方程将其写成了递归形式.

然后我们在这里就开始讨论了求解这个方程的三种方法 (外加一个解析解), 能够求出所有状态的价值.

因为上述MRP假设状态转移是固定的, 而实际情况状态转移是由Agent的行动导致的, 所以MRP还无法建模. 所以要引入动作变量, 拓展为马尔可夫决策过程(MDP). 强化学习的目的是让Agent如何通过动作获得最大的累积奖励, 所以随波逐流的MRP就不能满足要求了. 但是其中的状态价值等概念是可以参考的 -- 这时因为引入策略函数, 就可以将动作a从变量中移除, 转换为仅含概率和原本的状态价值的式子. 所以, 当然, 我们可以经过同样的过程, 由贝尔曼方程的方法推导出其递归形式.

但是, 我们并不能直接按照之前的方法求解, 因为$\pi$ 本身就是需要优化的对象, 不可能直接得到最佳策略$\pi^*$ , 因此, 我们的思路又转变到了如何获得最佳策略 (即上述三.8的问题, 我们要对马尔可夫决策过程进行控制).

在这里, 我们想到的方法是按照前面的方式进行策略评估得到状态的价值函数V, 然后用贪心的策略最大化式子里面的Q, 又得到新的V, 如此迭代下去, 直到收敛之后就得到了最佳的策略. 我们可以证明, 每一步都采用贪心最大化Q值就能得到最大的V值, 也就是贝尔曼最优方程.

还没完, 上述步骤仅仅说明了什么情况下$Q^$或者说$V^$ 最大, 要知道同一个价值可能也有不同的策略. 因此我们还要在其中抽取最大的策略. 这里有两种做法 (还有一个穷举), 分别是策略迭代和价值迭代. 前者根据贝尔曼最优方程的推导过程自然而然得到一个Q的递推形式, 而贪心的过程被记录在Q表上, 查询Q表就可以得到策略; 后者则是将Q的递推转化为V的递推, 做相似的事情.

FastAPI 参数校验：Query、Path、Body、Cookie、Header

Mon, 30 Mar 2026 00:00:00 GMT

官方教程在这里会连续切出 Query、Path、Body、Cookie、Header 好几页，第一次读容易觉得“怎么又来一个函数”。更顺的理解方式是：它们其实都在回答同一个问题，只是参数来源不同。

1. `Query`、`Path`、`Body` 的真正作用

from typing import Annotated
from fastapi import FastAPI, Query, Path

app = FastAPI()


@app.get("/items/")
async def read_items(
    q: Annotated[str | None, Query(max_length=50, description="随便传个字符串")] = None,
):
    results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
    if q:
        results.update({"q": q})
    return results

这里 Query(...) 做了两件事：

告诉 FastAPI：这个参数来自查询字符串
顺手附带额外约束和文档信息

Path() 和 Body() 也是同样的模式，只是来源不同。

2. `Annotated` 的意义

q: Annotated[str | None, Query(max_length=50)] = None

可以把它拆成两层：

真正的数据类型是 str | None
额外的校验规则和来源说明放在 Query(...)

这样“类型”和“元信息”就放在了一起，读起来会比老写法更清楚。

3. 常见约束：长度、范围、别名、弃用

Query、Path、Body 支持一大批相似的约束参数：

max_length
min_length
pattern
gt / ge
lt / le
alias
deprecated
include_in_schema

@app.get("/p_items/{item_id}")
async def read_items(
    item_id: Annotated[int, Path(title="我是一个title", ge=1)],
    q: Annotated[str | None, Query(alias="item-query")] = None,
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    return results

这里：

item_id 必须大于等于 1
对外暴露的查询参数名是 item-query

4. 自定义校验：`AfterValidator`

有些规则不是 gt、max_length 这种现成参数能覆盖的，这时可以接 Pydantic 验证器。

import random
from pydantic import AfterValidator

data = {
    "isbn-9781529046137": "The Hitchhiker's Guide to the Galaxy",
    "imdb-tt0371724": "The Hitchhiker's Guide to the Galaxy",
    "isbn-9781439512982": "Isaac Asimov: The Complete Stories, Vol. 2",
}


def check_valid_id(id: str):
    if not id.startswith(("isbn-", "imdb-")):
        raise ValueError('Invalid ID format, it must start with "isbn-" or "imdb-"')
    return id


@app.get("/v_items/")
async def read_items(
    id: Annotated[str | None, AfterValidator(check_valid_id)] = None,
):
    if id:
        item = data.get(id)
    else:
        id, item = random.choice(list(data.items()))
    return {"id": id, "name": item}

这一步很重要，因为它说明 FastAPI 并不只支持“表面上的参数约束”，而是可以自然接入 Pydantic 更细的校验能力。

5. 用模型承接一整组查询参数

查询参数一多，散着写会越来越乱。这个时候可以把它们建成一个模型：

from typing import Annotated, Literal
from fastapi import Query
from pydantic import BaseModel, Field


class FilterParams(BaseModel):
    model_config = {"extra": "forbid"}

    limit: int = Field(100, gt=0, le=100)
    offset: int = Field(0, ge=0)
    order_by: Literal["created_at", "updated_at"] = "created_at"
    tags: list[str] = []


@app.get("/items/")
async def read_items(filter_query: Annotated[FilterParams, Query()]):
    return filter_query

这段非常值得记，因为它把“查询参数”也推进了结构化建模这一层。

6. Cookie 和 Header 其实还是同一个模式

它们看起来像两个新知识点，本质上还是同一个问题：参数从哪里来。

from typing import Annotated
from fastapi import Cookie, FastAPI, Header

app = FastAPI()


@app.get("/items/")
async def read_items(session_id: Annotated[str | None, Cookie()] = None):
    return {"session_id": session_id}


@app.get("/h_items/")
async def read_items(user_agent: Annotated[str | None, Header()] = None):
    return {"User-Agent": user_agent}

这类来源参数也能继续用模型收起来：

from pydantic import BaseModel


class CommonHeaders(BaseModel):
    host: str
    save_data: bool
    if_modified_since: str | None = None
    traceparent: str | None = None
    x_tag: list[str] = []


@app.get("/hs_items/")
async def read_items(headers: Annotated[CommonHeaders, Header()]):
    return headers

7. 到这里最值得留下来的心智

这一层最重要的不是把 Query / Path / Body / Cookie / Header 分别背下来，而是先把统一模式站稳：

参数先有类型
参数再有来源
参数还可以继续叠加规则

后面你再看表单、文件上传、依赖注入，理解会快很多，因为底层模式其实没变。

小样本多模态微调实战：第一次训练、Loss 曲线与结果复盘

Mon, 30 Mar 2026 00:00:00 GMT

前面的几篇都还是“搭心智模型”。这一篇开始真正进入实践：用极少样本先把完整训练流程跑通，再看它到底学到了什么、没学到什么。

一、任务和现实约束

这次实验的目标，是让 Qwen2.5-VL 对血液图片做描述和分类。任务并不只是“看出这是一张血迹图”，而是要进一步判断它属于哪一类血液形态。

原笔记里给出的核心背景是：

数据涉密，不能上传到公开在线服务
通用多模态模型能看出“这是红色液体”，但不理解“血液形态”这一任务本身
样本非常少，只能先做一次小样本试跑

所以这次训练的目的，不是一步到位得到高精度模型，而是：

先把完整流程跑通，并尽快暴露问题。

二、数据怎么标出来

为了提高标注效率，原笔记里先用 clip-vit-large-patch14 做了一层预处理，然后配了一个交互式 Flask 标注工具，用来不断补全 conversations 字段。

最终生成的就是多模态 ShareGPT 风格数据集：

在这次试验里：

总样本量非常少
五个小类各自保留 2 个作为测试
其余样本进入训练

这本身就决定了结果不会太稳定，但也正因为如此，它特别适合用来观察流程问题。

三、第一次训练时怎么选参数

训练前先统计了 token 长度，确认大部分数据都在 1000 以内，所以 cutoff_len=2048 足够。

再结合前面那篇参数选择的经验，第一次训练采用了下面这组设置：

num_train_epochs=8
per_device_train_batch_size=1
gradient_accumulation_steps=1
learning_rate=5e-5
lora_rank=8
lora_alpha=16
validation split = 0

参数面板如下：

训练命令的核心部分如下：

llamafactory-cli train \
  --stage sft \
  --do_train True \
  --model_name_or_path /data/llm/Qwen2.5-VL/Qwen/Qwen2___5-VL-7B-Instruct \
  --finetuning_type lora \
  --template qwen2_vl \
  --dataset blood_image \
  --cutoff_len 2048 \
  --learning_rate 5e-05 \
  --num_train_epochs 8.0 \
  --per_device_train_batch_size 1 \
  --gradient_accumulation_steps 1 \
  --optim adamw_torch \
  --lora_rank 8 \
  --lora_alpha 16 \
  --lora_dropout 0 \
  --lora_target all \
  --freeze_vision_tower True \
  --freeze_multi_modal_projector True

原笔记里对这组选择的直觉其实很清楚：

样本少，所以 batch 先取小，尽量让模型多“看细节”
LoRA 还是先从保守配置开始
验证集先不开，先看训练能不能跑通、Loss 是否合理

四、第一次训练出来了什么

训练过程如下：

其中一个非常有意思的点，是 Total optimization steps = 112 并不是手工直接设的，而是由参数推出来的：

双卡训练
每卡 batch size = 1
总 batch = 2
梯度累积 = 1
27 个训练样本，ceil(27 / 2) = 14
训练 8 轮，14 × 8 = 112

这个计算过程其实很适合刚接触训练流程时建立感知：
很多日志里的数字，不是神秘参数，而是别的参数共同决定出来的。

五、显存占用怎么估

原笔记里还做了一个很实用的粗估：

基础模型权重：Qwen2.5-VL-7B，BF16 大约 14GB
框架开销：约 1GB
LoRA 适配器：约 0.5GB
激活值：约 2.5GB

合起来单卡大概在 18GB 左右。

这个估算和实际结果已经相当接近，说明对训练资源的判断是比较可靠的。

六、Loss 曲线怎么看

这条曲线整体是符合预期的：

有下降
在逐渐变缓
没出现明显发散

所以至少可以说明：

训练过程本身没有明显跑崩。

原笔记还顺手总结了几类常见坏曲线：

Loss 居高不下：可能学习率太小，或者数据噪声太大
收敛很慢：可能轮数不够
上下震荡：可能学习率过大或 batch 太小
很早就卡住：可能学习率衰减过低、局部最优或过拟合
下降后又回升：通常要怀疑数据问题

这部分很重要，因为它提醒了一件事：

曲线正常，不等于任务完成得好。

七、训练后模型表现怎样

训练后的关键输出是 LoRA adapter 文件。加载方式本质上就是：

保留原始基础模型
叠加训练得到的 adapter

真正测试时，模型已经能识别出“被动的 / 重力类”这一层，但还不能稳定完成更细的分类。

1. 能识别的情况

比较容易区分的滴落型，已经有了一些正确识别：

2. 还会混淆的情况

在不少样本上，它还是容易混淆类别，或者只回答到大类，不回答细分类：

对于接触类血液，也存在明显误判：

浸润 / 血泊型也会被误识别成滴落型：

甚至在一些外部干扰明显的图片里，它还会先被背景带偏：

八、第一次实验最重要的价值

原笔记最后这段复盘其实特别像真实项目刚起步时的状态：

数据集太少
Loss 虽然下降，但平滑程度一般
模型对任务边界感知不够
分类不够鲁棒，还会自行联想
回答过于简洁
类别分布不平衡，滴落型样本偏多

所以这次训练的真正结论不是“它不行”，而是：

训练链路本身是合理的，问题主要暴露在数据设计与任务约束方式上。

这也是下一篇要处理的重点：
不只是“继续训”，而是先把数据和提示方式重构一遍。

LangGraph 核心能力 05：Time-travel 重放与分叉

Mon, 30 Mar 2026 00:00:00 GMT

LangGraph能力 - 时间旅行 (Time-travel)

LangGraph 支持通过检查点实现时间回溯：

重放：从先前的检查点重新执行。
分支：从先前的检查点以修改后的状态分叉，探索其他执行路径。

两者均通过从先前检查点恢复运行。检查点之前的节点不会重新执行（结果已保存）。检查点之后的节点会重新执行，包括所有大模型调用、API 请求以及中断（可能产生不同结果）。

1. 重放 (Replay)

使用先前检查点的配置调用图，从该点开始重放。

使用get_state_history找到你希望从中重放的检查点，然后使用该检查点的配置调用invoke：

from langgraph.graph import StateGraph, START
from langgraph.checkpoint.memory import InMemorySaver
from typing_extensions import TypedDict, NotRequired
import uuid

class State(TypedDict):
    topic: NotRequired[str]
    joke: NotRequired[str]


def generate_topic(state: State):
    return {"topic": "socks in the dryer"}


def write_joke(state: State):
    return {"joke": f"Why do {state['topic']} disappear? They elope!"}


checkpointer = InMemorySaver()
graph = (
    StateGraph(State)
    .add_node("generate_topic", generate_topic)
    .add_node("write_joke", write_joke)
    .add_edge(START, "generate_topic")
    .add_edge("generate_topic", "write_joke")
    .compile(checkpointer=checkpointer)
)

# Step 1: Run the graph
config = {"configurable": {"thread_id": str(uuid.uuid4())}}
result = graph.invoke({}, config)

# Step 2: Find a checkpoint to replay from
history = list(graph.get_state_history(config))
# History is in reverse chronological order
for state in history:
    print(f"next={state.next}, checkpoint_id={state.config['configurable']['checkpoint_id']}")

# Step 3: Replay from a specific checkpoint
# Find the checkpoint before write_joke
before_joke = next(s for s in history if s.next == ("write_joke",))
replay_result = graph.invoke(None, before_joke.config)
# write_joke re-executes (runs again), generate_topic does not

这里稍微复习一下细节，这里TypedDict让字典定义可以写类型，并且写了NotRequired，所以invoke的时候传入{}也是合法的。如果你有印象，我们在LangChain的invoke中会传入一个Message列表，这个列表可以是AIMessage、HumanMessage等的对象，也可以是content block。invoke聊天图的时候，传入的一定要是state的一部分，比如

graph.invoke({
    "messages": [
        {"role": "user", "content": "你好"}
    ]
})

持久化在前面章节介绍过了，我们用graph.get_state_history(config)会得到一个历史快照的迭代器，list化之后可以拿到一个这个thread_id下的所有历史快照（每个超步保存的一个StateSnapshot），我们这时候就可以看看保存的信息。

然后，我们用before_joke = next(s for s in history if s.next == ("write_joke",))，从列表中找到第一个准备开始写笑话之前的节点，在这个图中指的就是generate_topic，然后我们就可以从这个存档开始继续跑，前面置None不传入信息，后面放入找到的历史快照。

2. 分支 (Fork)

分叉会从过往的一个检查点创建一个新分支，并修改状态。对先前的检查点调用update_state以创建分叉，随后使用None调用invoke来继续执行。

# Find checkpoint before write_joke
history = list(graph.get_state_history(config))
before_joke = next(s for s in history if s.next == ("write_joke",))

# Fork: update state to change the topic
fork_config = graph.update_state(
    before_joke.config,
    values={"topic": "chickens"},
)

# Resume from the fork — write_joke re-executes with the new topic
fork_result = graph.invoke(None, fork_config)
print(fork_result["joke"])  # A joke about chickens, not socks

graph.update_state(...)会基于旧checkpoint创建新的checkpoint分支，传入历史checkpoint的config，放入要更新的state字段就行了。

3. 能力总结

时间旅行适合进行调试、人工审核或者分叉试验。当我们想进行正常循环的时候，比如经典的“生成 -> 评估 -> 不满意就继续改”，或者拿官腔说是evaluator-optimizer的时候，可以直接在图上做环就行了。

generator -> evaluator -> conditional edge
                         pass -> END
                         fail -> generator

如果一直用时间回溯，虚拟的未来会越来越多。旧checkpoint还在，新checkpoint继续加进去，内存都会保存到python的进程内存中，越来越臃肿。

旧的checkpoint我们可以通过两种方式清理：

直接删除整条thread，checkpointer.delete_thread(thread_id)
用LangSmith或者Agent Server配置TTL

PyTorch Tensor、Autograd 与动态计算图

Mon, 30 Mar 2026 00:00:00 GMT

这一篇主要整理自 liuer_pytorch/3.ipynb，以及 pytorch_learning/pytorch_3.py、pytorch_learning/pytorch_4.py。如果说上一节在解决“怎么训练一个模型”，这一节就在解决“PyTorch 为什么能训练模型”。

1. Tensor 不只是数组

课程笔记里有一句很关键的话：

PyTorch 中的基本数据类型是 Tensor，Tensor 实际上是一个类，有两个重要成员：data 和 grad。

这句话虽然有点“老表述”，但核心意思没变：
Tensor 在 PyTorch 里不只是存数值，它还能进入计算图，参与自动求导。

所以和 NumPy 比起来，Tensor 重要的不是“也能做矩阵运算”，而是：

它知道自己是否需要梯度
它知道自己是怎么被算出来的
它能沿着计算图反向传播

2. 先把最常用的形状操作记住

我自己的 pytorch_3.py 基本就是在熟悉这些操作：

import torch as t

b = t.arange(0, 6)
b = b.view(3, 2)

d = b.unsqueeze(1)
e = b.view(1, 1, 2, 1, 3)
e.squeeze_()

这里最常见的几个动作是：

view(...)：重排形状，但不改变元素总数
unsqueeze(dim)：插入一个长度为 1 的维度
squeeze(dim)：压掉长度为 1 的维度

后面做 CNN、RNN、Transformer 时，很多 bug 本质上都不是模型错了，而是 shape 没对上。

3. Autograd 的核心：记录计算历史

我自己理解 Autograd，最有效的一句话是：

前向传播时，PyTorch 会一边算值，一边把这条计算链记录下来。

这就是所谓的动态计算图。

import torch as t

x = t.randn(3, 4, requires_grad=True)
y = x ** 2 * t.exp(x)
grad_y = t.ones_like(y)
y.backward(grad_y)
print(x.grad)

这里发生的事情是：

x 开启了梯度追踪
y 的每一步计算都被记录进图里
backward() 从输出往回推，把梯度传回 x

为什么 y.backward(...) 这里要传一个同形状的张量？
因为 y 不是标量。标量可以默认把“最终损失对输出的梯度”看成 1，非标量则需要你显式说明。

4. 叶子节点、非叶子节点与梯度

这个点我一开始也很容易混：

叶子节点：通常是我们手动创建、真正想优化的变量
非叶子节点：中间计算结果

默认情况下，反向传播结束后，真正会保留梯度的是叶子节点。
中间变量如果也想看梯度，需要额外处理，比如：

retain_grad()
torch.autograd.grad(...)
register_hook(...)

这在调试网络时非常有用。

5. 动态计算图到底“动态”在哪

我很喜欢课程里用条件分支举例这一点。
PyTorch 的动态图不是预先写死的，而是每次前向传播都重新搭一遍。

所以像下面这种逻辑是成立的：

def f(x):
    result = 1
    for i in x:
        if i.data > 0:
            result = i * result
    return result

不同输入会走不同分支，而计算图会在运行时按真实路径构建出来。
这也是 PyTorch 在研究和实验里非常舒服的原因之一。

6. 哪些时候要关掉梯度

不是所有阶段都需要反向传播。

在这些场景里，with torch.no_grad(): 非常重要：

验证集 / 测试集推理
纯预测
不希望保存计算图，节省内存

with torch.no_grad():
    predictions = model(inputs)

这不是语法洁癖，而是推理阶段的常规操作。

7. 这一阶段该记住什么

如果只保留最核心的认知，我会记这几句：

Tensor 的价值不只是存数据，而是能进入计算图。
requires_grad=True 才会开始追踪这条计算链。
非标量做 backward() 时，需要明确提供梯度入口。
PyTorch 的计算图是运行时动态生成的，不是静态写死的。

把这一层吃透之后，再看 nn.Module、损失函数和优化器，会明显顺很多。

免模型强化学习：DP、MC、TD、SARSA 与 Q-learning

Mon, 30 Mar 2026 00:00:00 GMT

上一篇笔记, 已经从“为什么要用RL“ 引领到了“如何用MDP相关理论解决RL问题“的门前, 并介绍了策略迭代和价值迭代两种方法. 但是, 这通常要求我们知道环境的动态模型 (比如状态转移概率P和奖励函数R), 但是在训练一个Agent当中, 我们往往无法获得这个模型. 所以接下来的路径自然就是深入各种免模型RL算法, Q-learning、Policy Gradient等算法, 它们是将LLM与RL结合的关键工具.

实际上, 因为我们主要学习的是思想, 要侧重理解这个公式的输入、输出、为什么要用这个公式, 另外还有一个就是代码中何处运用了这个公式. 经过笔记一的训练应该已经进入了RL的语境, 所以现在会弱化推导的过程, 至于代码的运用, 将会在后面的笔记中专门实验.

一. 进化 -- model-based to model-free

在很多实际问题中, 马尔可夫决策过程的模型可能是未知的, 具体而言, 我们不知道状态转移函数与奖励函数. 比如，围棋、雅达利游戏、控制直升机、股票涨跌等问题…… 但是我们仍然想让Agent学习到如何行动, 怎么办呢?

既然舍弃了建模, 那就需要有东西去替代它的作用, 显而易见, 这个东西就是数据. 读者可以回忆 (回去翻) 笔记(一) 中的标题下小字, 那里提到了蒙特卡洛的算法. 因为这种算法是model-free的, 所以我觉得放在这里介绍比较合适.

这些数据在概率论中被称为采样 (Sample) , 而在强化学习中通常会被称为经验 (Experience) .

二. 动态规划的方法 (Dynamic Programming , DP)

在介绍具体的model-free方法之前, 有一点需要解释. 回顾笔记(一)中的MDP决策控制, 我们使用了策略迭代和价值迭代两种方法, 当然, 他们都是model-based算法, 但是要是从算法层面来说明的话, 他们都属于动态规划.

动态规划适合于解决满足最优子结构和重叠子问题的. 因为我们已经得到了一种迭代的公式, 所以我们可以通过自举 (bootstrapping) 的方法不停地迭代贝尔曼方程, 当最后更新的状态和上一个状态区别不大的时候, 更新就可以停止, 我们就可以输出最新的$V'(s)$ 作为它当前的状态的价值. (注: 自举是指更新时采用了估计, 例如动态规划和时序差分都是; 蒙特卡洛则是采样).

对于简单的MRP过程, 我们可以总结这个过程如下:

而如果引入智能体的动作成为MDP, 那就是笔记(一)中介绍的两种迭代: 策略迭代和价值迭代了.

再提一嘴, 不是说model-based的方法就一定不好, 也不是说只有上面说过的两种, 但是他们都是比较基础的开端. 近些年也有继续在model-based领域深挖的, 基于模型的强化学习 (Model-Based Reinforce Learning, MBRL), 这里提供一个工具库: facebookresearch/mbrl-lib: Library for Model Based RL . 该领域致力于通过数据估计出模型, 继而进行强化学习, 而不是直接用数据.

三. 蒙特卡洛方法 (Monte Carlo, MC)

1. MRP的MC

同样, 我们先用MRP这个随波逐流的过程来看MC的价值评估方法, 借此来说明MC的思想. 当得到一个马尔可夫奖励过程后, 我们从某个状态开始, 把agent放在状态转移矩阵里面, 让它”随波逐流”, 这样就会产生一个轨迹. 产生一个轨迹之后, 就会得到一个奖励, 那么直接把折扣的奖励即回报$g$ 算出来之后, 积累起来得到回报$G_t$. 当累积到一定数量的轨迹之后, 我们直接用$G_t$ 除以轨迹数量, 就会得到某个状态的价值.

2. MDP的MC

通过上述例子我们就可以知道, MC是通过采样轨迹代替概率轨迹, 采样轨迹奖励的均值代替奖励函数. 这实际上就是依赖于大数定律: 只要我们获得足够多的轨迹, 就可以趋近于价值函数 (因为价值函数的定义就是用期望 ), 即当 $N(s) \rightarrow \infty$ 时, $V(s) \rightarrow V_\pi(s)$ . 虽然我们不能通过迭代求解贝尔曼方程的方法得到价值函数, 但是我们仍然可以用采样来做策略评估.

(1) MC Basic

注意, 本算法的效果极差, 基本是没法用的状态. 但是却是后面优化的起点, 并且非常清晰的揭示了如何从model-based跨向model-free, 所以必须首先介绍.

现在需要正式跨向model-free, 通过MRP中的MC我们已经可以知道如何通过采样来近似出概率从而得到价值函数. 但是在更复杂的MDP中, 策略不是能通过采样总结出来的, 而是要主动选择的. 因此, 我们的想法是, 回到策略迭代的算法中, 把里面依赖模型的算法替换掉, 从而得到MDP中的model-free算法.

首先回顾策略迭代的两个步骤, 策略评估和策略更新. 当时我们是借用Q值的迭代, 并证明了最优情况下的V就是采取最优行动Q的价值. 这里Q值非常关键, 我们回归得出Q值的地方, Q值最原始最基本的定义是学习笔记(一)里的6.6, 当时我们由于是知道奖励函数和状态转移概率的, 所以我们使用贝尔曼公式的工具, 直接推到出了其公式6.8. 实际上, 这里前面的$R(s,a)$ 部分还能继续展开, 因为它是累积的总汇报, 完全写开之后就是这种形式: $$ Q(s,a)=\sum_rp(r|s,a)r+\gamma\sum_{s^{\prime}\in S}p\left(s^{\prime}\mid s,a\right)V\left(s^{\prime}\right) \tag{2.1.1} $$ 然后, 模型的更新依赖于Q值. 继续推导, 可以得到式2.1.2表示Q可以由迭代来更新, 然后得到的更新策略的方法就是让Q更大: $$ Q^{}(s,a)==\sum_rp(r|s,a)r+\gamma\sum_{s^{\prime}\in S}p\left(s^{\prime}\mid s,a\right)\max_{a}Q^{}(s^{\prime},a^{\prime})\tag{2.1.2} $$ $$ \pi_{i+1}(s)=\underset{a}{\operatorname*{\arg\max}}Q_{\pi_i}(s,a) \tag{2.1.3} $$ 策略迭代依赖于Q值, Q值依赖于贝尔曼公式道出的递归式, 递归式的求解依赖于动态规划的方法…… 本来是严丝合缝的逻辑, 但是目前, 环境未知, 自然就不可能得到p和r, 这种方法作废.

那么现在回到最原始的定义 (上一章的式6.6), 它目前还不依赖于模型 $$ Q_\pi(s,a)=\mathbb{E}\pi\left[G_t\mid s_t=s,a_t=a\right] \tag{2.1.4} $$ 这是一个随机变量的期望值进行估计的过程, 或者说这是一个均值估计的过程. 而MC就可以求解, 其中$g^{(i)}$ 是对随机变量的采样, 用来估计$G_t$ : $$ Q{\pi_k}(s,a) = \mathbb{E}[G_t|s_t = s, a_t = a] \approx \frac{1}{N} \sum_{i=1}^{N} g^{(i)}(s,a) \tag{2.1.5} $$ 现在我们来梳理一下算法的过程, 首先我们会给出一个初始策略$\pi_0$ , 并且在第k步迭代中, 会有以下两步: Step1: policy evaluation. 计算得到所有(s, a)的Q值, 方法就是之前说过的MC采样. Step2: policy improvement. 第二步和策略迭代算法一样, 选出Q表中最大的值, 开始迭代.

我们可以说, MC Basic算法就是Policy Iteration算法的一个变形, 将其基于模型计算Q值的部分改为了基于采样估计. 另外, Policy Iteration中是先计算V再转成Q, 而MC Basic就是直接估计Q, 这是因为V转化成Q的过程也依赖于模型, 这是肯定不行的. 详见笔记(一)的马尔可夫决策过程控制.

(2) MC Exploring Starts

MC Basic虽然思想直观, 但是却非常低效, 所以我们对其进行推广, 让其更高效.

(3) MC $\epsilon$ -Greedy

1-$\epsilon$ 的概率按照Q函数执行动作, $\epsilon$ 概率的可能会随机探索. 通常情况下, $\epsilon$ 是一个比较小的值. 数学上可以证明, 任意$\epsilon$ 贪心策略$\pi'$ 都是对$\pi$ 对改进, 优化是单调的.

四. 时序差分学习 (temporal-difference learning, TD)

TD (时序差分) 学习是RL中非常经典的算法, 它结合了动态规划和蒙特卡洛的优点, 实现了单步更新. Q-learning和SARSA是TD学习的典型代表, 前者属于离策略(off-policy)学习, 后者则是同策略(on-policy)方法.

1. DP, MC和TD

到现在, 我们已经学完了DP和MC, 知道了DP和MC的区别最大在于是否model-based. 但是TD和这两者的区别是什么呢. 接下来, 我们可以从统一的视角, 来看一看这三种算法更新的备份图:

如上图, 从左到右分别是DP, MC, TD (这里是TD(0), 即单步更新) 的视角. DP通过递推相加, 每一个节点都会被计算到; MC每次采样完一整条轨迹. 而TD则是走一步(或几步), 就会对未来的值进行估计.

时序差分的目的, 就死后对于某个给定的策略$\pi$ , 在线计算出它的状态价值函数$V_\pi$, 即一步一步算. 最简单的算法是一步时序差分(one-step TD), 即TD(0), 它每走一步都更新一次: $$ V(s_t) \leftarrow V(s_t) + \alpha (r_{t+1} + \gamma V(s_{t+1}) - V(s_t)) \tag{4.1.1} $$ 上式中, $\alpha$ 是学习率, 而$r_{t+1} + \gamma V(s_{t+1})$ 是估计回报, 也可以称为时序差分目标(TD Target), 我们减去和目标的差距, 也被称为TD Error, 对价值函数进行软更新, 以此来不断达到逼近目标.

我们可以看出, 时序差分实际上是一种估计. 首先它同样对期望值采样, 然后最重要的是它使用的是当前估计的V而不是真实的V.

对TD进行推广, 如果调整步数 (step), 就可以变成n步差分算法 (n-step TD). n=1的时候, 就是上述提到的TD(0)或者直接称TD算法, 而当n趋向于无穷, 实际上就就是MC算法.

通过调整步数, 可以进行MC方法和TD方法之间的权衡. 上述方法也被称为基于state value的TD算法.

2. Sarsa

Sarsa时一种同策略时序差分算法 (On-Policy), 也就是说, 它只有一个Q表来实现, 优化和选择都在上面.

Sarsa算法做出的改变很简单, 它把原本TD更新V的过程, 改为了更新Q, 或者说, Sarsa直接估计Q表, 即: $$ Q(s_t,a_t) \leftarrow Q(s_t,a_t) + \alpha [r_{t+1} + \gamma Q(s_{t+1},a_{t+1}) - Q(s_t,a_t)] \tag{4.2.1} $$ 由于每次更新函数值需要知道目前的状态, 当前的动作, 奖励, 下一步的状态, 下一步的动作, 即$(s_t,a_t,r_{t+1},s_{t+1},a_{t+1})$ , 所以取首字母就构成了Sarsa算法.

Sarsa同样有单步和n步之分, 依据step. 如果给Q机上资格衰减参数$\lambda$ , 就会成为Sarsa($\lambda$) 策略.

3. Q-learning

相比于Sarsa, Q-learning采用的是异策略算法(Off-Policy). 在它学习的过程中, 有两种不同的策略, 目标策略(target policy) 和 行为策略(behavior policy). 我们可以进行直观的比喻, 前者相当于军师的角色, 后者相当于士兵. 士兵的按照自己的策略探索环境, 用$\mu$ 表示, 然后探索出来的轨迹/数据再交给军师, 而且交出的数据中不需要像Sarsa一样包含$a_{t+1}$ .

因为学习策略很多时候太“胆小”了,总倾向于选择目前的最优, 所以有了探索策略.

异策略学习有很多好处:

可以用探索学习来学到最佳策略, 学习效率高
可以学习其他智能体的动作, 进行模仿学习
可以重用旧的策略产生轨迹, 节省资源

当然, 以上的优势主要在加入经验回放后才能体现出来, 对于朴素Q-learning来说, 异策略同样是有好处的.

现在我们来详细介绍Q学习. Q学习在目标策略$\pi$ 上直接采用贪心策略, 按照从Q表里选择最大的来进行. 行为策略$\mu$ 可以是随机的策略, 我们采用$\epsilon$ 贪心方法.

Q学习的增量表达形式如下, 就形式而言, 其与Sarsa非常相似, 但是要看仔细, 这里的目标是不一样的. $$ Q(s_t, a_t) \leftarrow Q(s_t, a_t) + \alpha \left[ r_{t+1} + \gamma \max_a Q(s_{t+1}, a) - Q(s_t, a_t) \right] \tag{4.3.1} $$ 对比Sarsa用同一策略选择$a_{t+1}$ 之后再更新Q值, 其目标$r_{t+1} + \gamma \max_a Q(s_{t+1}, a)$ , 使用当前的a中使得Q取得最大的贪心结果, 而不需要$a_{t+1}$ , 也就是说Q学习不需要提前知道下一个动作, 只需要前面的$(s_t,a_t,r_{t+1},s_{t+1})$ .

当然, 上述更新的式子是隐含异策略的, 只表达了更新时属于完全贪婪, 我们可以将其显式写出, 行为策略$\mu$ 为: $$ a_t \sim \mu (\cdot|s_t)=\left{ \begin{aligned} &\text{随机动作，概率 } \epsilon; \ &\operatorname*{argmax}a Q(s_t,a), \text{概率 } 1-\epsilon \end{aligned} \right. \tag{4.3.2} $$ 学习策略时 (更新Q值时): $$ \pi(s{t+1})=argmax_aQ(s_{t+1},a) \tag{4.3.3} $$ 为什么我们要将两个策略分开, 给行为策略选择$\epsilon-greedy$ 算法? 这是其中的核心意义就是, 当前Q值最大的动作不一定是最好的, 因为我们得到的信息不完整, 或者说不能采样所有动作, 有的动作可能根本就没有尝试过. $\epsilon-greedy$ 算法就承认了当前的“最好”可能不是真正的“最好”, 所以使用了探索和利用的trade-off, 解决了困境, 有意识探索未知避免陷入局部最优.

FastAPI 输出层：响应模型、状态码与数据更新

Sun, 29 Mar 2026 00:00:00 GMT

前面几篇主要在看“请求怎么进来”。这一篇开始把视角转到输出端：接口最终要返回什么、返回到什么程度、文档和数据过滤怎样跟着一起工作。

1. `response_model` 到底在解决什么

最直接的写法，是在返回类型上做类型注解：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: list[str] = []


@app.post("/items/")
async def create_item(item: Item) -> Item:
    return item


@app.get("/items/")
async def read_items() -> list[Item]:
    return [
        Item(name="Portal Gun", price=42.0),
        Item(name="Plumbus", price=32.0),
    ]

这样做的效果不只是“有类型提示”，还包括：

自动生成响应 schema
自动体现在 OpenAPI 文档里
返回数据结构不匹配时更早暴露问题

2. 返回类型和 `response_model` 的关系

有时函数真实返回的东西，和你希望文档/过滤层看到的模型不完全一样。这时候可以把 response_model 写在装饰器上。

from typing import Any
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: list[str] = []


@app.get("/items/", response_model=list[Item])
async def read_items() -> Any:
    return [
        {"name": "Portal Gun", "price": 42.0},
        {"name": "Plumbus", "price": 32.0},
    ]

官方文档明确提到：

如果同时声明了返回类型和 response_model
那么 FastAPI 最终会以 response_model 为准

来源：Response Model 官方页 https://fastapi.tiangolo.com/zh/tutorial/response-model/

3. 响应模型不仅描述输出，也会过滤输出

这是 response_model 很值的一点。

官方文档专门提到“返回类型与数据过滤”这一层：即使函数返回了更多字段，FastAPI 也会按响应模型把不该暴露的字段过滤掉。
来源：Response Model 官方页 https://fastapi.tiangolo.com/zh/tutorial/response-model/

这也是为什么用户模型常常会拆成：

UserIn
UserOut

或者用继承关系把公共字段提出来。

4. `response_model_exclude_unset`、`include`、`exclude`

如果模型里有很多默认值，但响应里只想保留“真实设置过的字段”，可以这样写：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float = 10.5
    tags: list[str] = []


items = {
    "foo": {"name": "Foo", "price": 50.2},
    "bar": {"name": "Bar", "description": "The bartenders", "price": 62, "tax": 20.2},
}


@app.get("/items/{item_id}", response_model=Item, response_model_exclude_unset=True)
async def read_item(item_id: str):
    return items[item_id]

如果只想挑部分字段，也可以用：

response_model_include
response_model_exclude

不过这类写法更适合临时裁剪；真正长期可维护的接口，通常还是拆独立输出模型更清楚。

5. 状态码不是附属配置，而是输出语义的一部分

你在本地 13、16 这两份笔记里把状态码和路径操作配置单独记出来，这一步其实很值，因为它们就是输出层的一部分。

from fastapi import FastAPI, status
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(item: Item) -> Item:
    return item

常见的几个记忆点：

200：默认成功
201：创建成功
204：成功但没有响应体
400/404：客户端错误
500：服务端错误

6. 路径操作配置：`tags`、`summary`、`description`

这些参数看起来像“文档修饰”，实际上对大一点的项目非常重要。

from enum import Enum
from fastapi import FastAPI

app = FastAPI()


class Tags(Enum):
    items = "items"
    users = "users"


@app.get("/items/", tags=[Tags.items], summary="读取条目列表")
async def get_items():
    return ["Portal gun", "Plumbus"]

这类配置会直接影响：

/docs 里的分组
OpenAPI 中的语义结构
前后端对接口的认知方式

如果应用大起来了，把标签收进 Enum 会比到处散落字符串稳很多。

7. `jsonable_encoder` 的位置

jsonable_encoder() 最容易在“更新数据”和“写入数据库前序列化”这两个场景里出现。

from datetime import datetime
from fastapi.encoders import jsonable_encoder
from pydantic import BaseModel

fake_db = {}


class Item(BaseModel):
    title: str
    timestamp: datetime
    description: str | None = None


def update_item(id: str, item: Item):
    json_compatible_item_data = jsonable_encoder(item)
    fake_db[id] = json_compatible_item_data

它的作用就是：

把 Pydantic 模型转成更适合 JSON 的结构
顺手把 datetime、UUID 这类类型转换成可序列化形式

如果你后面要把数据存进数据库、缓存或者文件，这一步非常常见。

8. PUT 和 PATCH 的区别

你在 18.md 里已经把这一层写出来了，放到输出层来看会更顺：

PUT 更像整体替换
PATCH 更像部分更新

from fastapi import FastAPI
from fastapi.encoders import jsonable_encoder
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str | None = None
    description: str | None = None
    price: float | None = None
    tax: float = 10.5
    tags: list[str] = []


items = {
    "foo": {"name": "Foo", "price": 50.2},
    "bar": {"name": "Bar", "description": "The bartenders", "price": 62, "tax": 20.2},
}


@app.patch("/items/{item_id}", response_model=Item)
async def update_item(item_id: str, item: Item):
    stored_item_data = items[item_id]
    stored_item_model = Item(**stored_item_data)
    update_data = item.model_dump(exclude_unset=True)
    updated_item = stored_item_model.model_copy(update=update_data)
    items[item_id] = jsonable_encoder(updated_item)
    return updated_item

这里最核心的一步其实是：

item.model_dump(exclude_unset=True)

它保证只有用户真的传了的字段才会参与更新，而不会让模型默认值把旧数据覆盖掉。

9. 响应层为什么值得单独当一篇看

刚开始学 FastAPI，很容易只盯着“能不能把参数收进来”。但真正把接口做稳，靠的是输出端：

返回什么模型
过滤掉什么字段
用什么状态码表达结果
文档怎么展示
更新时怎样避免误覆盖

输入层决定你怎么接请求，输出层决定你的接口能不能长久稳定。

失败复盘与二次优化：system、数据重构与 agent 配合

Sun, 29 Mar 2026 00:00:00 GMT

第一次训练的意义是把问题暴露出来。第二次的重点，就不再是“再训一遍”，而是先重新理解：到底是哪一层出了问题。

一、先把问题重新说清楚

目标还是同一个：
对 Qwen2.5-VL 做微调，让它能准确描述图片并完成血液分类任务。

原笔记里把分类树整理成了这样：

.
├── 被动的、重力
│   ├── 大量血液自由落体
│   ├── 滴落
│   ├── 接触
│   ├── 浸润、血泊
│   └── 流动
├── 变动的
│   ├── 虫咬的
│   ├── 干缩的
│   ├── 空白区
│   ├── 扩散的
│   ├── 凝固的
│   ├── 顺序的
│   └── 稀释的
└── 溅落的
    ├── 二次作用机理
    ├── 喷射机理
    └── 撞击机理

但第一次实验后暴露出来的问题很明确：

数据太少
类别不平衡
模型对分类任务的“使命感”不够强
会自行联想出不存在的类别
回答过于简洁

所以第二轮优化的核心不是“多训一点”，而是：

如何在小样本前提下，让模型更明确地知道它究竟要做什么。

二、第一步尝试：把分类规则写进 system

这一步的想法非常自然：
既然模型不知道分类边界，那就把分类标准显式写给它。

原笔记把各类血迹的规则进行了细化整理，然后准备写成一段 system 信息，让模型在训练时直接看到这些标准。

这里的出发点其实完全合理：

样本少
领域标准复杂
靠样本自己学出分类边界太难

所以想用 system 给它补规则。

1. 但是这一步为什么失败了

原笔记里记录得很清楚：
直接把大段规则写进 system 去训练，效果反而变差，模型开始胡言乱语。

这件事很值得记，因为它说明：

“更多任务说明”不一定等于“更好的微调效果”。

一个很可能的原因是：

Qwen2.5-VL-Instruct 这类模型在预训练和指令微调阶段，已经形成了它熟悉的对话格式分布。如果强行引入一套与原有分布不一致、而且很重的 system 结构，模型在小样本上反而更容易学歪。

所以这里第一次真正感觉到：

有些约束适合写进模型，有些约束更适合交给外部 agent 或系统逻辑。

三、真正有效的改动：先重构数据

既然“直接灌 system”不行，那就回到更基础的一层：数据本身。

1. 把描述写得更细

第一次训练里，很多图像描述过于简短，导致模型很难抓住真正能支持分类的细节。

所以第二轮开始做的第一件事，是把描述写得更具体、更像“真正有助于分类的观察记录”。

这个改动非常朴素，但往往最有效。因为分类任务不只是要求模型“看到了图像”，而是要求它“看到并描述了对分类有帮助的要点”。

2. 把 system 的职责往 agent 迁

原笔记里有一句特别关键的判断：

如果不框定范围，模型会联想；但直接把范围硬写进训练用 system，又会把模型训练搞乱。

所以最终想到的折中办法是：

模型微调只学核心任务模式
更重的任务约束交给外部 agent 的 system 提示去控制

这其实非常像现在很多真实系统的设计：

模型参数负责“底层能力”，agent/system 负责“运行时边界”。

四、第二轮参数怎么改

第二次训练并没有彻底推翻第一轮，而是在原有参数上做了几处更有针对性的微调：

--num_train_epochs 10.0
--lora_dropout 0.1
--warmup_steps 20

对应的直觉分别是：

num_train_epochs 增加：小样本下让模型多看几遍
lora_dropout 增加：给 LoRA 一点正则化，防止过拟合
warmup_steps 增加：让学习率更平稳地升起来

而有几项则保持不变：

学习率不变
per_device_train_batch_size=1
gradient_accumulation_steps=1

原笔记里的判断是：继续让模型“细着学”，而不是靠更大 batch 去换更平滑的梯度。

五、第二轮训练结果

调整后再次微调，Loss 曲线如下：

这张图至少说明一点：

第二轮不是乱改，而是沿着第一次暴露出来的问题在做针对性修正。

六、第二轮怎么评估

后面没有直接让微调模型裸跑，而是用了一个快速搭起来的 agent，把：

微调后的模型
vLLM 启动出来的服务
外部 system 提示

重新组合到一起，再去跑测试集。

这个做法本身就很有启发性，因为它说明：

微调不是一个非黑即白的过程，不一定所有约束都必须写进权重。

最终在 10 张测试图上的结果是：

正确率约 50%
流动型识别最好
接触型最容易出错
回答风格仍然偏简洁

原笔记最后把现象概括得很直白：

特征明显的类别更容易识别
团聚型血液更容易误判
接触型容易被识别成流动型
回答格式化且过于简短

七、这次复盘真正留下了什么

如果只看数字，50% 正确率显然不理想。
但如果站在学习和工程角度看，这次复盘其实留下了几条很重要的结论：

数据设计比单纯加轮数更重要
system 提示并不是越重越好
小样本下，任务边界必须明确
微调与 agent 不必对立，它们可以分工

所以第二轮最大的价值，并不是“已经训好了”，而是：

终于开始知道该把什么交给模型、把什么交给系统。

LangGraph 核心能力 06：Memory 短期与长期记忆

Sun, 29 Mar 2026 00:00:00 GMT

LangGraph能力 - Memory

人工智能应用需要记忆来在多次交互间共享上下文。在LangGraph中，你可以添加两种类型的记忆：

添加短期记忆作为智能体状态的一部分，以实现多轮对话。
添加长期记忆以跨会话存储用户专属或应用级别的数据。

1. 短期记忆

短期记忆，我们应该在LangChain的Short-term Memory和前面的持久化、时间旅行中已经很清晰知道了。现在我们补充一个在生成环境下使用的简单例子：

from langgraph.checkpoint.postgres import PostgresSaver

DB_URI = "postgresql://postgres:postgres@localhost:5442/postgres?sslmode=disable"
with PostgresSaver.from_conn_string(DB_URI) as checkpointer:
    builder = StateGraph(...)
    graph = builder.compile(checkpointer=checkpointer)

这段代码是连接Postgres来存checkpoint，它的意义是把 thread 内状态变成可持久、可恢复、可生产使用。不过从LangGraph的概念上来说，这还是属于短期/线程内记忆。

还有一点，如果你的图中包含子图，只需在编译父图时提供检查点工具即可。LangGraph 会自动将检查点工具传递给子图。

2. 长期记忆

在前面持久化的章节中，我们说明了Store是负责跨线程共享长期记忆的结构，其中数据按命名空间组织，通过runtime注入读写，并可以支持自然语言query搜索记忆。

当你使用存储（store）编译图结构时，LangGraph 会自动将存储注入到你的节点函数中。推荐的访问存储方式是通过 Runtime 对象，下面是一个简单示例：

from dataclasses import dataclass
from langgraph.runtime import Runtime
from langgraph.graph import StateGraph, MessagesState, START
import uuid

@dataclass
class Context:
    user_id: str

async def call_model(state: MessagesState, runtime: Runtime[Context]):
    user_id = runtime.context.user_id  
    namespace = (user_id, "memories")

    # Search for relevant memories
    memories = await runtime.store.asearch(
        namespace, query=state["messages"][-1].content, limit=3
    )
    info = "\n".join([d.value["data"] for d in memories])

    # ... Use memories in model call

    # Store a new memory
    await runtime.store.aput(
        namespace, str(uuid.uuid4()), {"data": "User prefers dark mode"}
    )

builder = StateGraph(MessagesState, context_schema=Context)
builder.add_node(call_model)
builder.add_edge(START, "call_model")
graph = builder.compile(store=store)

# Pass context at invocation time
graph.invoke(
    {"messages": [{"role": "user", "content": "hi"}]},
    {"configurable": {"thread_id": "1"}},
    context=Context(user_id="1"),
)

同样，生产级使用的时候，我们会用一个数据库：

from langgraph.store.postgres import PostgresStore

DB_URI = "postgresql://postgres:postgres@localhost:5442/postgres?sslmode=disable"
with PostgresStore.from_conn_string(DB_URI) as store:
    builder = StateGraph(...)
    graph = builder.compile(store=store)

前面提到过的semantic搜索，借助嵌入模型实现：

from langchain.embeddings import init_embeddings
from langgraph.store.memory import InMemoryStore

# Create store with semantic search enabled
embeddings = init_embeddings("openai:text-embedding-3-small")
store = InMemoryStore(
    index={
        "embed": embeddings,
        "dims": 1536,
    }
)

store.put(("user_123", "memories"), "1", {"text": "I love pizza"})
store.put(("user_123", "memories"), "2", {"text": "I am a plumber"})

items = store.search(
    ("user_123", "memories"), query="I'm hungry", limit=1
)

store.search是一个高层的API，面向LangGraph的长期记忆。InMemoryStore搜索的时候会用 embed_query(...) 生成查询向量，调 _cosine_similarity(...) 计算分数，不过不要随便推广，自然语言搜索是否支持、怎么做，依赖具体 store implementation。LangGraph 官方提供的是 BaseStore 抽象，以及像 InMemoryStore、AsyncSqliteStore、内置 Postgres store 这类实现，如果要用store后端用Milvus，通常要自己实现一个BaseStore。

3. 管理短期记忆

启用短期记忆后，随着对话变长，messages 很容易超过模型上下文窗口。这一部分其实已经在LangChain的Short-term Memory中整理过，不过我们再来看看LangGraph的写法，官方给出的常见处理方式有：

Trim messages：在调用模型前截断消息，只保留最近一部分上下文。
Delete messages：从图状态中永久删除某些消息。
Summarize messages：把更早的消息总结成摘要，再替换原始消息。
Manage checkpoints：直接查看和管理 thread 的 checkpoint 历史。
Custom strategies：例如按角色过滤消息、只保留最近几轮工具调用等。

3.1 Trim messages

最简单的做法是在真正调用模型前，对 messages 做裁剪。官方推荐可以借助 LangChain 的 trim_messages 工具，按 token 数量保留最后一段上下文。

from langchain_core.messages.utils import (
    trim_messages,
    count_tokens_approximately,
)

def call_model(state: MessagesState):
    messages = trim_messages(
        state["messages"],
        strategy="last",
        token_counter=count_tokens_approximately,
        max_tokens=128,
        start_on="human",
        end_on=("human", "tool"),
    )
    response = model.invoke(messages)
    return {"messages": [response]}

其中常见参数含义：

strategy="last"：优先保留最新消息。
max_tokens：裁剪后的消息总 token 上限。
start_on="human"：尽量让裁剪后的历史从用户消息开始。
end_on=("human", "tool")：裁剪边界尽量落在合法消息类型上。

这种方法的优点是简单直接，缺点是早期信息会被丢弃。

3.2 Delete messages

如果你不是“临时裁剪后喂给模型”，而是希望真正从图状态中删掉某些旧消息，可以返回 RemoveMessage。这会永久修改短期记忆。

from langchain.messages import RemoveMessage

def delete_messages(state: MessagesState):
    messages = state["messages"]
    if len(messages) > 2:
        return {
            "messages": [RemoveMessage(id=m.id) for m in messages[:2]]
        }
    return {}

注意：

这种方式要求 messages 使用 add_messages reducer，也就是通常使用 MessagesState 或 messages: Annotated[list, add_messages]。
删除后仍要保证消息历史合法。比如有些模型要求消息历史以 human 开始；如果前面有 tool call，对应的 ToolMessage 也不能删乱。

3.3 Summarize messages

只裁剪和删除会丢失信息，所以更实用的方式是：把旧消息总结成一段摘要，然后只保留最近几条原始消息。

from langchain.messages import HumanMessage, RemoveMessage
from langgraph.graph import MessagesState

class State(MessagesState):
    summary: str

def summarize_conversation(state: State):
    summary = state.get("summary", "")

    if summary:
        summary_message = (
            f"This is a summary of the conversation to date: {summary}\n\n"
            "Extend the summary by taking into account the new messages above:"
        )
    else:
        summary_message = "Create a summary of the conversation above:"

    messages = state["messages"] + [HumanMessage(content=summary_message)]
    response = model.invoke(messages)

    delete_messages = [RemoveMessage(id=m.id) for m in state["messages"][:-2]]
    return {
        "summary": response.content,
        "messages": delete_messages,
    }

这个模式的核心思想是：

summary 单独作为 state 的一个键长期保留。
新摘要会在旧摘要基础上继续扩展，而不是每次从零总结。
原始消息不需要全部保留，只保留最近几条高价值上下文即可。

所以可以把它理解成：

messages：保存最近的原始上下文
summary：保存更早历史的压缩版本

3.4 管理 checkpoints

短期记忆本质上就是 thread 级别的 checkpoint 状态，因此也可以直接通过 checkpoint API 查看。

PyTorch 分类任务、Dataset / DataLoader 与训练循环

Sun, 29 Mar 2026 00:00:00 GMT

这一篇主要整理自 liuer_pytorch/5-10.ipynb。相比前两篇的“训练直觉”和“自动微分”，这里更像真正开始做任务：输入有了标签，输出不再是连续值，而是类别。

1. 分类和回归最大的不同是什么

在线性回归里，我们输出的是一个连续值。
到了分类任务，输出就不再是“一个实数”，而更像“每个类别的概率分布”。

课程里对逻辑回归的总结很直接：

虽然叫“回归”，但它解决的是分类问题
输出要映射到 0-1
loss 常常用交叉熵

这就是为什么二分类里经常会看到：

sigmoid
BCELoss
BCEWithLogitsLoss

而多分类里经常会看到：

softmax
CrossEntropyLoss

2. 从二分类到多分类

这组笔记里，二分类和多分类的任务其实已经很典型了：

糖尿病数据集：二分类
Titanic 作业：表格分类
Otto 数据集：多分类

从学习角度看，它们最有价值的地方不是“数据集本身”，而是让我逐渐看到分类训练的完整链路：

数据预处理
定义模型
定义损失函数
划分 batch
训练与评估

3. Dataset 和 DataLoader 为什么重要

课程在 7.ipynb 里专门整理了三个概念：

Epoch：完整看完一遍全部样本
Batch Size：一次前向与反向传播处理多少样本
Iteration：一个 epoch 被切成多少次参数更新

然后真正把数据喂给模型的，是 Dataset 和 DataLoader。

DataLoader 至少解决了几件很烦但必须做的事：

按 batch 划分数据
shuffle 打乱顺序
变成一个可迭代对象

也就是说，它让训练循环终于能写成：

for epoch in range(epochs):
    for x, y in train_loader:
        optimizer.zero_grad()
        pred = model(x)
        loss = criterion(pred, y)
        loss.backward()
        optimizer.step()

这就是从“玩具代码”进入“正常训练代码”的关键一步。

4. 表格数据任务里，数据清洗不能跳过

在 Titanic 那一节里，我觉得最有价值的不是模型本身，而是那份 Pandas 数据清洗速查表。
因为表格数据任务很少能一上来就直接转 Tensor。

真正高频的动作包括：

df.info()：看列类型和缺失值
df.isnull().sum()：排查空值
fillna(...)：填补缺失
map(...)：把类别映射成数字
drop(...)：删除无用列
astype(...)：强制转换类型

这一步如果没做，后面 PyTorch 再熟也跑不顺。

5. PyTorch 多分类里最常见的误区

课程里讲多分类时提到一个很关键的直觉：

希望输出有竞争性，且大于等于 0，和为 1。

这就是 Softmax 的角色。
但在真正写 PyTorch 时，一个很常见的坑是：

模型输出 logits
损失用 CrossEntropyLoss
不需要自己先手动做 softmax

因为 CrossEntropyLoss 内部已经帮你处理了。

6. 这一阶段真正应该掌握什么

如果只留最核心的能力，我觉得是下面这些：

能分清回归、二分类、多分类对应的输出和损失函数。
知道 Dataset / DataLoader 为什么是标准训练入口。
知道 batch、epoch、iteration 分别在说什么。
知道真实任务里，数据预处理和特征清洗本来就是训练流程的一部分。

到这一步，PyTorch 就不只是“会写一个最小例子”了，而是已经开始具备做小任务的基本骨架。

RAG 入门：概念、优势与演进路线

Sun, 29 Mar 2026 00:00:00 GMT

这一篇是整条 RAG 学习线的起点。先把“为什么需要 RAG”说清楚，后面再去看数据加载、文本分块和向量数据库，就不容易只记工具名，不记系统目标。

RAG - 简介

一、什么是RAG

1. 核心定义

从本质上讲，RAG（Retrieval-Augmented Generation）是一种旨在解决大语言模型（LLM）“知其然不知其所以然”问题的技术范式。它的核心是将模型内部学到的“参数化知识”（模型权重中固化的、模糊的“记忆”），与来自外部知识库的“非参数化知识”（精准、可随时更新的外部数据）相结合。其运作逻辑就是在 LLM 生成文本前，先通过检索机制从外部知识库中动态获取相关信息，并将这些“参考资料”融入生成过程，从而提升输出的准确性和时效性。

2. 技术原理

RAG系统实现参数化知识+非参数化结果结合的方法，主要可以分为两步：

检索阶段：通过知识向量化、语义召回等方式寻找非参数化知识
生成阶段：将检索到的知识整合到上下文，按照预设的Prompt指令，将上下文和问题有效整合，并引导LLM做出可控的、有理有据的文本生成。

3. 技术演进

维度	初级 RAG（Naive RAG）	高级 RAG（Advanced RAG）	模块化 RAG（Modular RAG）
流程	离线：索引<br>在线：检索 → 生成	离线：索引<br>在线：… → 检索前 → … → 检索后 → …	积木式可编排流程
特点	基础线性流程	增加检索前后的优化步骤	模块化、可组合、可动态调整
关键技术	基础向量检索	查询重写（Query Rewrite）<br>结果重排（Rerank）	动态路由（Routing）<br>查询转换（Query Transformation）<br>多路融合（Fusion）
局限性	效果不稳定，难以优化	流程相对固定，优化点有限	系统复杂性高

这里的离线指的是提起完成数据预处理。

二、为什么要使用RAG

1. RAG vs. 微调

在选择具体的技术路径时，一个重要的考量是成本与效益的平衡。通常，我们应优先选择对模型改动最小、成本最低的方案，所以技术选型路径往往遵循的顺序是提示词工程（Prompt Engineering） -> 检索增强生成 -> 微调（Fine-tuning）。

下图横轴表示LLM优化，纵轴表示上下文优化。

问题	RAG 的解决方案
静态知识局限	实时检索外部知识库，支持动态更新
幻觉（Hallucination）	基于检索内容生成，错误率降低
领域专业性不足	引入领域特定知识库（如医疗/法律）
数据隐私风险	本地化部署知识库，避免敏感数据泄露

2. RAG的关键优势

以下直接照搬All in RAG，看一遍即可：

(1) 准确性与可信度的双重提升

RAG 最核心的价值在于突破了模型预训练知识的限制。它不仅能补充专业领域的知识盲区，还能通过提供具体的参考材料，有效抑制“一本正经胡说八道”的幻觉现象。论文研究还表明，RAG 生成的内容在具体性和多样性上也显著优于纯 LLM。更重要的是，RAG 具备可溯源性——每一条回答都能找到对应的原始文档出处，这种“有据可查”的特性极大提高了内容在法律、医疗等严肃场景下的可信度。

(2) 时效性保障

在知识更新方面，RAG 解决了 LLM 固有的知识时滞问题（即模型不知道训练截止日期之后发生的事）。RAG 允许知识库独立于模型进行动态更新——新政策或新数据一旦入库，立刻就能被检索到。这种能力在论文中被称为“索引热拔插”（Index Hot-swapping）——就像给机器人换一张存储卡一样，瞬间切换其世界知识库，而无需重新训练模型，实现了知识的实时在线。

(3) 显著的综合成本效益

从经济角度看，RAG 是一种高性价比的方案。首先，它避免了高频微调带来的巨额算力成本；其次，由于有了外部知识的强力辅助，我们在处理特定领域问题时，往往可以使用参数量更小的基础模型来达到类似的效果，从而直接降低了推理成本。这种架构也减少了试图将海量知识强行“塞入”模型权重中所需的计算资源消耗。

(4) 灵活的模块化可扩展性

RAG 的架构具备极强的包容性，支持多源集成，无论是 PDF、Word 还是网页数据，都能统一构建进知识库中。同时，其模块化设计实现了检索与生成的解耦，这意味着我们可以独立优化检索组件（比如更换更好的 Embedding 模型），而不会影响到生成组件的稳定性，便于系统的长期迭代。

3. RAG风险评估

风险等级	案例	RAG 适用性
低风险	翻译/语法检查	高可靠性
中风险	合同起草/法律咨询	需结合人工审核
高风险	证据分析/签证决策	需严格质量控制机制

从表格到函数：DQN 与 Value-Based 深度强化学习

Sun, 29 Mar 2026 00:00:00 GMT

之前陈述的问题中, 动作都是离散的, 所以可以用表格表达, 但是在实际RL过程中, 很多时候是高纬度的动作, 甚至是无限的动作(一个范围), 这时所有动作都会失效

一. 引入深度网络

我们需要在连续的状态和动作空间中计算函数值$Q_\pi(s,a)$, 我们可以用一个函数$Q_\phi(s,a)$ 来近似计算, 称为价值函数近似 (value funciton approximation) : $$ Q_\phi(\boldsymbol{s},\boldsymbol{a})\approx Q_\pi(\boldsymbol{s},\boldsymbol{a}) \tag{1.1} $$ 函数$Q_\phi(s,a)$ 通常是一个参数为$\phi$ 的函数, 比如神经网络, 其输出为一个实数, 称为Q网络 (Q-network). 因为Q值本质上是一个实数, 所以我们可以通过这种端到端的方法, 直接计算出Q值.

二. 离散动作的DQN

深度Q网络 (deep Q-network) 是指基于深度学习的Q学习. DQN是value-based算法, 批评家 (Critic) 基于深度网络计算Q. 我们首先介绍三个常用的技巧, 然后在给出DQN算法的更新过程.

1. 目标网络

DQN与Q-learning的思想没有区别, 只是用神经网络完成了标量Q的输出.我们回顾Q-learning算法, 他的核心思想也是让做策略评估, 让当前的Q更接近于贝尔曼公式递推出来的Q‘. Q-learning的更新式可以写作: $$ Q(s_t, a_t) \leftarrow Q(s_t, a_t) + \alpha \left[ r_{t+1} + \gamma \max_a Q(s_{t+1}, a) - Q(s_t, a_t) \right] \tag{2.1.1} $$ 这其中, Q-Target为: $$ Q_{target}=r_{t+1}+\gamma \underset{a}{max}Q(s_{t+1},a) \tag{2.1.2} $$ 对于DQN就是用一个带有参数$\theta^-$ 的目标网络来输出这个值, 所以可以写作: $$ Q_{target}=r_{t+1}+\gamma \underset{a}{max}Q(s_{t+1},a;\theta^-) \tag{2.1.3} $$ 相对的, 左侧的Q就用一个参数为$\theta$ 的网络来输出, 用于选择动作和计算当前Q值.

回顾之前的TD方法, 我们用TD error, 加上学习率$\alpha$ 对Q进行软更新. 但是这样其实是不好学习的, 因为每次Q都是更新的, 也就是说, 我们在学习的过程中, 目标也是变动的.

我们可以举个例子, 在猫抓老鼠当中, 将猫比做Q估计 (左侧), 老鼠比做Q目标 (右侧), 如果Q网络也会动, 就会产生非常奇怪的优化轨迹, 使得训练十分不稳定.

所以, 我们可以先把老鼠固定一段时间, 动的不要那么频繁, 比如每五步跑一次, 放到上面的式子中, 就是我们把后面的$Q_\pi\left(s_{t+1},\pi\left(s_{t+1}\right)\right)$ 称为目标网络, 这其中的$\pi(s_{t+1})$ 采用和上一节Q-learning中一样的argmax策略选择a (式4.3.3). 将其固定, 左侧的Q更新, 等到更新一些次数之后(比如100次) 再把参数复制到右边的网络中改变目标值. 因此, 在目标没有改变的期间, 我们仅仅相当于在做一个回归问题, 去靠近一个固定的值:

严格来说$r_t$ 应该写为$r_{t+1}$ 比较规范. 回忆一下我们的回报$G(t)$ 也是从t+1开始奖励, 不知道你当时疑惑了没有🤫. 后面图片也有这个问题.

2. 探索

当我们使用Q函数的时候, 策略完全取决于Q函数, 给定一个状态, 我们就穷举所有动作, 来采取让Q值最大的动作. 这里就遇到一个问题: 我们一定要对一个动作进行过采样才能计算出Q值, 然而如果在那个状态没有采样过某动作, 就估测不出它的Q值.

如果Q是表格, 问题会很严重, 导致根本估不出没见过的s-a对的Q值; 如果是网络, 也会有类似的问题, 假设有三个s-a对, 我们估测其初始值(假设为0,0,0), 然后我们采样了第二对得到了正向的奖励, 变成了(0,1,0), 这样我们以后每次都会选择第二个动作, 但是可能选择两外两个会更好.

如果我们没有很好探索, 训练就会遇到这种问题. 所以, 我们需要在探索和利用中找到一个trade-off, 这个问题被称为强化学习过程中的探索-利用窘境(exploration-exploitation dilemma).

我们通常可以用两个方法来解决它, 首先是我们的老熟人 $\epsilon$-贪心, 我们在model-free的MC方法中就使用了这种优化. 而另一种是玻尔兹曼探索 (Boltzmann exploration). 我们假设对于所有s-a对, Q值均大于等于0, 那么a选中的概率就和Q成正比. 我们引入温度系数T, 得到下面式子: $$ \pi(a\mid s)=\frac{\mathrm{e}^{Q(s,a)/T}}{\sum_{a^{\prime}\in A}\mathrm{e}^{Q(s,a^{\prime})/T}} \tag{2.1.1} $$ 其中T为正数. 如果T很大, 所有动作几乎都以等概率选择 (探索); 如果T很小, Q值大的动作更倾向于被选中 (利用). 通过调整T值, 我们可以实现trade-off.

3. 经验回放

读者也许还记得介绍Q-learning的时候提到过异策略算法的优势, 其中之一就是可以重用旧的采样, 产生轨迹, 节省性能. 我们构建一个回放缓冲区(replay buffer), 也被称作回放内存(replay memory). 现有策略$\pi$ 与环境交互多次收集数据, 全部放在buffer中. 回放缓冲区的经验可能来自于不同的策略, 在存满的时候才会丢弃旧的策略.

有了回放缓冲区之后, 我们会迭代训练Q函数, 在每次迭代里面从回放缓冲区随机挑选一个批量 (batch) 出来, 按照过去的经验去更新Q函数. 所以说, 如果使用了经验回放的技巧, 这个算法也就是异策略算法了.

4. 深度Q网络

一般的深度Q网络中, 我们初始化两个网络 -- Q和$\hat{Q}$ . 开始两者一样, 然后我们对于每一个时间步, 用探索的算法 (如$\epsilon$-贪心) 选择动作a获得反馈r, 然后我们$(s_t,a_t,r_t,s_{t+1})$ 存储到缓冲区中. 然后我们从缓冲区以批量形式采样, 然后更新Q函数. 我们通过更新Q让其更接近于目标网络$y=r_{i}+\max_{a}\widehat{Q}(s_{i+1},a)$ (回归). 然后每经过C次重置$\hat{Q}=Q$ , 并更新目标.

三. 深度Q网络进阶优化

1. 双深度Q网络 (double DQN, DDQN)

为什么要提出DDQN ? 这是因为, 在传统的Q网络中, Q值往往是被高估的. 这是因为我们实际在设计更新式子的过程中, 我们实际上就是看哪个a可以得到最大的Q值, 就贪心为目标. 但是, 网络是有误差的, 假设其中一个动作被高估了, 就总会倾向于选择它, 从而使目标总是太大.

为了解决高估问题, 我们在DDQN设置了两个Q函数. 其中一个与之前一样, 贪心决定动作a, 但是决定之后并不适用这个Q网络计算Q值, 而是用另一个Q‘计算, 也就是: $$ Q\left(s_t,a_t\right)\longleftrightarrow r_t+Q^{\prime}\left(s_{t+1},\arg\max_aQ\left(s_{t+1},a\right)\right)\tag{3.1.1} $$ 这样一来, 如果Q高估了a, 只要Q‘没有高估, 就还是正常的值; 如果Q’高估了, 也是没问题的, 只要Q不选择这个a就可以. 这种互相制约的网络, 正是DDQN的神奇之处.

我们针对如下几个游戏中, DDQN和DQN之间的对比, DDQN得到的真正的Q值是要比DQN高的, 所以我们说, DDQN学出来的策略比较强, 实际得到的奖励比较大.

最上面一行中水平的橙色（对应DQN）和蓝色（对应Double DQN）直线是在学习结束后运行相应智能体，并对从每个访问状态获得的实际折扣回报进行平均后计算得出的。如果不存在偏差，这些直线将与图表右侧的学习曲线完全吻合。中间一行展示了两款游戏中DQN过度乐观情况尤为明显的对数值估计（以对数尺度表示）。最下面一行则显示了这种过度乐观对智能体在训练过程中评估时所取得分数的负面影响：一旦出现高估现象，分数便会下降。而使用Double DQN进行学习则要稳定得多。

2. 竞争深度Q网络

相比于原本的DQN, 它唯一的差别就是改变了网络的架构. DQN输入的是状态, 输出的是每一个动作的Q值. 而竞争深度Q网络不直接输出Q值, 而是分成两条路径运算, 第一条路径会输出一个标量$V(s)$ , 第二条路径会输出一个向量$A(s,a)$, 把这两者加起来够成新的Q值$Q(s,a)$.

这样做有什么好处呢? 答案是我们不需要把所有的状态-动作对都采样, 可以不修改$A(s,a)$ 转而修改$V(s)$. 因为很多时候, 一个动作并不会太大影响即使在在这个状态的价值了. 我们这样修改, Q表的值也会被修改, 但是修改的话可以仅仅通过调整V值如下图:

那么剩下的问题就是如何让网络倾向于修改V来解决问题. 最直观的方法就是, 我们给A加上约束, 让网络倾向于修改V来解决问题. 比如, 我们可以控制A的均值为0, 所以更新单个A值就不可行了, 网络就会更新在V值上.

对于具体的实现, 我们将A和V相加之前, 先进行归一化让A列之和等于0.

3. 优先级经验回放 (Prioritized Experience Replay, PER)

我们原本在采样数据训练Q网络的过程中, 会均匀从回放缓冲区采样数据, 然而这样并不一定是好的, 因为一些数据非常重要. 所以我们就需要给不同的数据优先权 (priority). 做PER的时候, 因为改变了采样的过程, 更新参数的方法也要更改.

4. 多步更新 -- MC + TD

这个就不用解释了, 多步更新即可.

5. 噪声网络 (noisy net)

探索的过程也可以改进, $\epsilon$-贪心就是在动作的空间上加噪声. 噪声网路是给参数的空间加上噪声. 比如我们给网路上每一个参数加上一个高斯噪声, 就把原来的Q变成了$\widetilde{Q}$ , 称为噪声Q函数(noisy Q-function).

OpenAI和DeepMind几乎在同一时间提出了几乎一模一样的噪声网络方法, 只是作用范围不同. 日后有机会在看看读不读吧.

6. 分布式Q函数

分布式Q函数是一个比较合适但难以实现的代码. 事情是这样的, 我们算出来的Q值是一个期望值. 我们把某一个状态采取某一个动作时, 得到的所有奖励在游戏结束时进行统计, 就会得到一个分布, 我们对这个分布计算平均值才是Q值, 算出来是累积奖励的期望. 也就是说, 累积奖励也是一个分布, 对它求期望, 再取平均值, 得到Q值.

但是不同的分布可能会相同的均值, 我们用Q值的期望来代替这个那个奖励, 这样可能丢失一些信息, 无法对真实的奖励分布建模:

分布式Q函数是对distribution建模. 具体的做法暂时不用去管.

四. 针对连续动作的深度Q网络

前面主要是在针对Q网络展开讨论其设计初衷, 但是我们仍然假设动作时离散的. 但是如果a是无限的, 该怎么利用Q网络? 以下有几种解决的方法

1. 对动作采样

这个方案也是最原始最直观的, 我们尽量采样多个动作, 并选择一个最大的Q. 这不是一个精确的方案, 但是并不会太低效: 因为我们会在计算中使用GPU, 进行并行运算.

2. 梯度上升

我们找a的本质是解决一个优化问题, 最大化目标函数. 因此我们就可以采用梯度上升, 将a作为参数, 找一组a去最大化Q函数, 就用梯度上升去更新a的值, 直到最后收敛.

既然是梯度上升, 就面临两个问题, 一个是局部最大值问题, 另一个就是每次决定采取动作的时候还是要训练一次网络, 计算量还是很大.

3. 设计网络架构

我们通过特别设计Q函数来解决arg max操作问题, 通过, 我们输入的状态s可以用向量或矩阵来表示它, Q函数则会输出向量$\mu(s)$ 、矩阵$\Sigma(s)$ 和标量$V(s)$. $$ Q(\boldsymbol{s},\boldsymbol{a})=-(\boldsymbol{a}-\boldsymbol{\mu}(\boldsymbol{s}))^\mathrm{T}\boldsymbol{\Sigma}(\boldsymbol{s})(\boldsymbol{a}-\boldsymbol{\mu}(\boldsymbol{s}))+V(\boldsymbol{s})\tag{4.3.1} $$ 注意这里的a是连续的动作, 所以是一个向量. $\boldsymbol{a}$ 和$\boldsymbol{\mu}(\boldsymbol{s})$ 都是列向量, $(\boldsymbol{a}-\boldsymbol{\mu}(\boldsymbol{s}))^\mathrm{T}$ 是一个行向量, $\boldsymbol{\Sigma}(\boldsymbol{s})$ 是一个正定矩阵. 通过矩阵运算很显然Q值是一个标量.

我们让$(\boldsymbol{a}-\boldsymbol{\mu}(\boldsymbol{s}))^\mathrm{T}\boldsymbol{\Sigma}(\boldsymbol{s})(\boldsymbol{a}-\boldsymbol{\mu}(\boldsymbol{s}))+V(\boldsymbol{s})$ 的值越小, 显然Q的值就越大. 很显然, 令 $\boldsymbol{a}$ 接近$\boldsymbol{\mu}(\boldsymbol{s})$ , 得到的Q值就会更大, 从而解决arg max操作.

综上而言, 深度Q网络也可以用于连续的情况中, 只是有一定的局限: 函数不能随意设置.

关于这个网络的具体细节这里暂时略过, 可能后面在实现时会进行补充说明.

4. 干脆不使用DQN吧

Q函数无论如何处理连续数字都很麻烦, 于是我们可以优化算法. 我们将基于策略的方法如PPO于基于价值的方法如DQN结合, 就可以得到Actor-Critic算法, 由于时策略导向, 并不在乎动作的连续性. 我们将在后续章节中继续介绍.

FastAPI 请求编码切换：表单、文件上传与 UploadFile

Sat, 28 Mar 2026 00:00:00 GMT

到这里最容易产生的误解是：好像“FastAPI 接请求”就等于“FastAPI 收 JSON”。其实不是。只要开始碰登录表单、图片上传、附件上传，请求编码就已经切到另一层了。

1. 为什么上传文件一定会牵涉到表单

JSON 和表单最大的区别不是语法，而是使用场景：

JSON：更适合结构化数据交换
multipart/form-data：适合文本字段 + 二进制文件一起传

所以一旦接口里要上传文件，几乎就等于在说：这次请求不会是普通 JSON，而会是表单编码。

2. 用 `Form` 接收表单字段

from typing import Annotated
from fastapi import FastAPI, Form

app = FastAPI()


@app.post("/login/")
async def login(
    username: Annotated[str, Form()],
    password: Annotated[str, Form()],
):
    return {"username": username}

这里的重点不是“又多学一个函数”，而是明确告诉 FastAPI：

这两个参数不是从 JSON 里读
而是从表单字段里读

如果项目里要收表单数据，需要先安装：

pip install python-multipart

3. 表单也可以建模

from typing import Annotated
from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class FormData(BaseModel):
    username: str
    password: str


@app.post("/login/")
async def login(data: Annotated[FormData, Form()]):
    return data

这一点很值，因为它说明：

表单字段不是“只能散着收”
也能继续走模型化这条路

4. 文件上传：`bytes` 和 `UploadFile`

from typing import Annotated
from fastapi import FastAPI, File, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(file: Annotated[bytes, File()]):
    return {"file_size": len(file)}


@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile):
    return {"filename": file.filename}

这两种写法都能收文件，但语义不一样：

bytes：FastAPI 直接把整个文件读进内存
UploadFile：给你一个更适合处理文件流的大文件接口

5. 为什么 `UploadFile` 更常用

你在本地笔记里把它写得很清楚，核心优势有这些：

文件先在内存里缓冲，超过阈值后会落盘
更适合图片、视频、大文件
能拿到元数据，比如 filename、content_type
提供异步文件方法
底层暴露的是真正的 file-like 对象

所以简单记法是：

小文件、只想马上拿内容：bytes
更真实的上传场景：UploadFile

6. `UploadFile` 常用属性和方法

最常用的属性：

filename
content_type
file

最常用的方法：

await file.read()
await file.write(data)
await file.seek(0)
await file.close()

尤其是 seek(0)，在“已经读过一次，还想再从头处理”的场景里很常见。

7. 同时接表单和文件

from typing import Annotated
from fastapi import FastAPI, File, Form, UploadFile

app = FastAPI()


@app.post("/files/")
async def create_file(
    file: Annotated[bytes, File()],
    fileb: Annotated[UploadFile, File()],
    token: Annotated[str, Form()],
):
    return {
        "file_size": len(file),
        "token": token,
        "fileb_content_type": fileb.content_type,
    }

这就是表单编码最常见的真实场景：

文本字段
一个或多个文件
一次请求一起提交

8. 多文件上传和可选文件

文件参数也能继续做扩展：

可选文件：给默认值 None
多文件上传：声明成 list[UploadFile]
即便是 UploadFile，也能继续在 File() 里补元信息

所以它的使用方式和前面学过的 Body / Query / Form 很一致，只不过这次载体换成了文件。

9. 从请求流角度看这一层

到这里，其实不是又学了三个新 API，而是把“请求编码”这个层补完整了：

URL 参数：路径和查询
JSON 请求体：Pydantic 模型
表单和文件：Form / File / UploadFile

这样你后面再看认证表单、头像上传、附件接口，就不会觉得这些接口是完全不同的一套东西。

LangChain 前置：OpenAI API 调用基线

Sat, 28 Mar 2026 00:00:00 GMT

这篇被我放在 LangChain 学习路径的最前面。它严格来说不是 LangChain 本体，而是为了先弄明白“模型调用本身长什么样”，后面看 Models、Messages、Streaming 时会顺很多。

1. 介绍与安装

官网的介绍是：OpenAI API 可应用于理解或生成自然语言、代码或图像的几乎所有任务。我们提供一系列不同功率级别的模型，适用于不同的任务，并具有微调自定义模型的能力。这些模型可以用于从内容生成到语义搜索和分类的一切。

我们要调用了解OpenAI包的用法，可以前往OpenAI Python API library查看；如果想快速用了解怎么用这个包来开发，可以看OpenAI Developers的接口文档。笔者整理的时候，这个包在pypi上的stable版本已经v2.29.0，一些教程还在用旧版的接口。

首先，最基本的当然是从PyPI安装

pip install openai

安装完成用pip show openai可以看到

Name: openai
Version: 2.29.0
Summary: The official Python library for the openai API
Home-page: https://github.com/openai/openai-python
Author: 
Author-email: OpenAI <support@openai.com>
License: Apache-2.0
Location: /opt/homebrew/anaconda3/envs/agent/lib/python3.13/site-packages
Requires: anyio, distro, httpx, jiter, pydantic, sniffio, tqdm, typing-extensions
Required-by:

2. 快速使用

(1) 主流新接口 - responses.create(...)

github页提供了一个示例。由于我们没有OpenAI额度😭，我们换中转API。

一般情况下，我们会用python-dotenv的方法将API秘钥添加到.env中，然后载入，防止直接写进源码。下面写法也可以不用find_dotenv，直接一句load_dotenv()，就会去默认环境找。

import os
from dotenv import load_dotenv, find_dotenv
from openai import OpenAI

_ = load_dotenv(find_dotenv())

client = OpenAI(
    api_key=os.environ["QIHANG_API"],
    base_url=os.environ["QIHANG_BASE_URL"]
)

response = client.responses.create(
    model = "gpt-4o-mini",
    instructions= "你是猪",
    input = "叫一声"
)

print(response.output_text)

(2) 传统聊天信息 - chat.completions

这是偏“传统聊天消息”的接口风格。相比而言，新版的instructions + input更像直接回答，而messages更像多轮聊天形式。

另外需要注意的是，这里的role必须是标准角色，比如system、user、assistant。

对比两者，还有接口返回的结构不同，可以观察一下。

import os
from dotenv import load_dotenv, find_dotenv
from openai import OpenAI

_ = load_dotenv(find_dotenv())

client = OpenAI(
    api_key=os.environ["QIHANG_API"],
    base_url=os.environ["QIHANG_BASE_URL"]
)

completion = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {
            "role": "system", 
            "content": "你要像一只猪一样说话"
        },
        {
            "role": "user",
            "content": "你最喜欢什么事情啊？",
        },
    ],
)

print(completion.choices[0].message.content)

(3) 图像

可以在input里面用content加入type键。默认input_text换成input_image即可图像即可，有两种形式，一种是用在线图像的URL，一般用{"type": "input_image", "image_url": f"{img_url}"}，一种是base64，base64包的用法在这里略掉，可以在Base64包用法里面查看。

(4) 异步使用

与正常使用几乎没区别，只是换成了AsyncOpenAI，举例如下：

import os
import asyncio
from openai import AsyncOpenAI
from dotenv import load_dotenv

load_dotenv()

client = AsyncOpenAI(
    api_key=os.environ.get("QIHANG_API"),
    base_url=os.environ.get("QIHANG_BASE_URL")
)


async def main() -> None:
    response = await client.responses.create(
        model="gpt-4o-mini", input="Explain disestablishmentarianism to a smart five year old.说中文"
    )
    print(response.output_text)


asyncio.run(main())

(5) aiohttp

默认情况下，异步客户端使用 HTTP 请求。然而，为了提高并发性能，也可以使用 aiohttp 作为 HTTP 后端。不过aiohttp暂时还没看，skip一下。

(6) 流式回答

流式回答可以让模型不要等整段生成完再一次性返回，而是边生成边把事件流发回来。官方文档描述为server-sent events，SDK中会拿到一个可迭代对象，所以能一直打印，直到收到完成事件为止。

直接print会打印整个对象的一大堆信息，我们也可以看一下：

ResponseTextDeltaEvent(content_index=0, delta='善', item_id='msg_01cd90f5c2f813180069c3fef6a7e08190b9a175ce86233099', logprobs=[], output_index=0, sequence_number=492, type='response.output_text.delta', obfuscation='JRiZxCSRiPjcp8M')

如果想呈现目前常见的打字机输出，可以只打印每个事件的delta字段，然后把flush设置为True（即将缓存区的数据立刻写入文件同时清空缓冲区）。

import os
import asyncio
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()

client = OpenAI(
    api_key=os.environ.get("QIHANG_API"),
    base_url=os.environ.get("QIHANG_BASE_URL")
)


stream = client.responses.create(
    model= "gpt-4o-mini",
    input = "写一个关于猪的鬼故事",
    stream = True
)

# stream会得到可迭代的一堆event
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta,end="",flush=True)
print()

暂时经常用到的应该就是这些，后面可以边学边看

3. 参数

API字典在这里，可以随用随看，里面包含一大堆参数。

LangGraph 核心能力 07：Subgraphs 子图与复用

Sat, 28 Mar 2026 00:00:00 GMT

LangGraph能力 - Subgraphs (子图)

子图是一种在另一张图中作为图节点使用的节点。适用于以下场景：

构建多智能体系统
在多张图中复用一组节点
分布式开发：当需要不同团队独立负责图的不同部分时，可将各部分定义为子图。只要遵循子图接口（输入与输出模式），父图即可在无需了解子图任何细节的情况下完成构建

添加子图时，需要定义父图与子图之间的通信方式：

模式	适用场景	状态 schema 特点
在节点内部调用子图	父图和子图的状态 schema 不同，二者没有共享键；或者你需要在父图与子图之间做状态转换	需要自己写一个包装节点，把父图 state 映射成子图输入，再把子图输出映射回父图 state
将子图直接作为节点加入	父图和子图共享部分状态键；子图可以直接读写父图的同一批 state channel	直接把编译好的子图传给 `add_node`，不需要额外包装函数

1. 节点内部调用：

当父图与子图拥有不同的状态结构（无共享键）时，需在节点函数内部调用子图。这种做法常见于多智能体系统中需要为每个智能体保留独立消息历史的场景。

节点函数会在调用子图前将父图状态转换为子图状态，并在返回前将结果转换回父图状态。

from typing_extensions import TypedDict
from langgraph.graph.state import StateGraph, START

class SubgraphState(TypedDict):
    bar: str

# Subgraph

def subgraph_node_1(state: SubgraphState):
    return {"bar": "hi! " + state["bar"]}

def subgraph_node_2(state: SubgraphState):
    return {"bar": state["bar"] + "!"}

subgraph_builder = StateGraph(SubgraphState)
subgraph_builder.add_node(subgraph_node_1)
subgraph_builder.add_node(subgraph_node_2)
subgraph_builder.add_edge(START, "subgraph_node_1")
subgraph_builder.add_edge("subgraph_node_1", "subgraph_node_2")
subgraph = subgraph_builder.compile()

# Parent graph

class State(TypedDict):
    foo: str

def call_subgraph(state: State):
    # Transform the state to the subgraph state
    subgraph_output = subgraph.invoke({"bar": state["foo"]})
    # Transform response back to the parent state
    return {"foo": subgraph_output["bar"]}

builder = StateGraph(State)
builder.add_node("node_1", call_subgraph)
builder.add_edge(START, "node_1")
graph = builder.compile()

因为父图和子图的state不一样，上例用了一个call_subgraph包装，来把父图的状态转化为子图的输入，再把子图的输出转回父图的状态。

2. 子图作为node加入

当父图与子图共享状态键（State）时，可将编译后的子图直接传入add_node。无需包装函数 —— 子图会自动读写父图的状态通道。例如，在多智能体系统中，智能体通常通过共享的messages键进行通信。

如果子图与父图共享状态键，可按照以下步骤将其添加到你的图中：

定义子图工作流（下方示例中的subgraph_builder）并对其进行编译
在定义父图工作流时，将编译后的子图传入add_node方法

from typing_extensions import TypedDict
from langgraph.graph.state import StateGraph, START

class State(TypedDict):
    foo: str

# Subgraph

def subgraph_node_1(state: State):
    return {"foo": "hi! " + state["foo"]}

def subgraph_node_2(state: State):
    return {"foo": state["foo"] + "!"}

subgraph_builder = StateGraph(State)
subgraph_builder.add_node(subgraph_node_1)
subgraph_builder.add_node(subgraph_node_2)
subgraph_builder.add_edge(START, "subgraph_node_1")
subgraph_builder.add_edge("subgraph_node_1", "subgraph_node_2")
subgraph = subgraph_builder.compile()

# Parent graph

builder = StateGraph(State)
builder.add_node("node_1", subgraph)
builder.add_edge(START, "node_1")
graph = builder.compile()

只要有共享的 state key，就可以直接作为 node 加入，同时子图还可以有自己私有的 key，也就是说，子图结构可以比父图更复杂。

3. 流式看到子图内部执行

只需要调整一个参数就可以，然后，我们就可以通过chunk["ns"] 看这个事件来自哪里，ns == ()表示是主图，如果来自某个子图可能是ns == ("node_2:<task_id>",)。

graph.stream(..., subgraphs=True, version="v2")

4. 子图的持久化模式

子图在 compile() 时，checkpointer 有 3 种模式：

checkpointer=None

默认
每次调用子图都从头开始
但单次调用内部仍继承父图 checkpointer，支持 interrupt / durable execution

checkpointer=True

子图按 thread 持续积累状态
下次调用同一个子图时，会接着上次记忆继续
适合“子 agent 自己也要有多轮记忆”

checkpointer=False

完全无 checkpoint
像普通函数调用
不支持 interrupt / durable execution

对于有多个“有记忆的子图”命名时，我们要给稳定的namespace进行空间隔离。

5. 查询子图状态

我们通过graph.get_state(config, subgraphs=True)来获取快照，然后可以用.tasks[0].state来看子图的内部状态。

下面给一个最小的可运行子图示例，包含了子图持久化、namespace隔离、查询子图状态、查看子图流输出等，包含详细注释：

from typing_extensions import TypedDict, NotRequired
from langgraph.graph import StateGraph, START
from langgraph.checkpoint.memory import InMemorySaver


# -----------------------------
# 1) 父图 state
# -----------------------------
# 父图只关心共享字段：
# - request: 输入任务
# - result: 子图处理后的结果
class ParentState(TypedDict):
    request: str
    result: NotRequired[str]


# -----------------------------
# 2) 子图 state
# -----------------------------
# 子图既可以读写父图共享键，也可以维护自己的私有键：
# - request: 与父图共享
# - result: 与父图共享
# - visits: 子图私有，用来证明“子图会跨调用记忆”
# - agent_name: 子图私有
class SubgraphState(TypedDict):
    request: str
    result: NotRequired[str]
    visits: NotRequired[int]
    agent_name: NotRequired[str]


def build_agent_subgraph(label: str):
    """构造一个最小子图。
    
    这个子图只有一个节点：
    - 每次被调用时，把 visits + 1
    - 写入自己的私有状态 agent_name / visits
    - 同时更新与父图共享的 result
    """

    def remember(state: SubgraphState):
        # 这里的 visits 是子图自己的内部状态。
        # 如果子图开启了 per-thread 持久化，那么同一 thread 下多次调用会持续累加。
        visits = state.get("visits", 0) + 1

        return {
            "visits": visits,
            "agent_name": label,
            "result": f"{label} handled '{state['request']}' (visit {visits})",
        }

    builder = StateGraph(SubgraphState)
    builder.add_node("remember", remember)
    builder.add_edge(START, "remember")

    # 关键点 1：
    # checkpointer=True 表示这个子图拥有“per-thread 持久化”。
    # 同一个 thread_id 下，下次再调用这个子图时，它会记得上次的内部状态。
    return builder.compile(checkpointer=True)


# -----------------------------
# 3) 构造两个子图
# -----------------------------
research_agent = build_agent_subgraph("research")
writer_agent = build_agent_subgraph("writer")


# -----------------------------
# 4) 父图把子图直接作为节点加入
# -----------------------------
parent_builder = StateGraph(ParentState)

# 关键点 2：
# 这里直接把“编译好的子图”传给 add_node。
# 因为父图和子图共享 request/result 这两个键，所以不需要额外包装函数。
parent_builder.add_node("research_agent", research_agent)
parent_builder.add_node("writer_agent", writer_agent)

parent_builder.add_edge(START, "research_agent")
parent_builder.add_edge("research_agent", "writer_agent")

# 父图本身也需要一个 checkpointer。
# 没有父图 checkpointer，子图的持久化/检查/中断能力都没法正常工作。
checkpointer = InMemorySaver()
graph = parent_builder.compile(checkpointer=checkpointer)

config = {"configurable": {"thread_id": "demo-thread"}}


# -----------------------------
# 5) 第一次调用
# -----------------------------
print("=== Run 1 ===")
result1 = graph.invoke({"request": "first task"}, config)
print(result1)
# 预期：
# {'request': 'first task', 'result': "writer handled 'first task' (visit 1)"}


# -----------------------------
# 6) 第二次调用（同一个 thread）
# -----------------------------
print("\n=== Run 2 ===")
result2 = graph.invoke({"request": "second task"}, config)
print(result2)
# 预期：
# research 子图和 writer 子图都会各自把 visits 从 1 累加到 2
# 最终 result 会显示 writer handled ... (visit 2)


# -----------------------------
# 7) 看流式输出，观察 namespace 隔离
# -----------------------------
print("\n=== Stream Run 3 ===")
for chunk in graph.stream(
    {"request": "third task"},
    config,
    stream_mode="updates",
    subgraphs=True,
    version="v2",
):
    if chunk["type"] == "updates":
        print("ns =", chunk["ns"], "data =", chunk["data"])

# 你会看到类似：
# ns = ('research_agent',) ...
# ns = () ...
# ns = ('writer_agent',) ...
# ns = () ...
#
# 这说明：
# - research_agent 子图的内部更新进入了它自己的 namespace
# - writer_agent 子图的内部更新进入了它自己的 namespace
# - 这就是“namespace 隔离”
#
# 由于这两个子图是“作为不同节点加入父图”的，
# LangGraph 会自动按节点名给它们稳定分配 namespace。


# -----------------------------
# 8) 查询子图自己的最新状态
# -----------------------------
# 关键点 3：
# 图执行完以后，想稳定读取某个子图的状态，
# 最直接的方法是显式指定 checkpoint_ns。

research_state = graph.get_state(
    {
        "configurable": {
            "thread_id": "demo-thread",
            "checkpoint_ns": "research_agent",
        }
    }
)

writer_state = graph.get_state(
    {
        "configurable": {
            "thread_id": "demo-thread",
            "checkpoint_ns": "writer_agent",
        }
    }
)

print("\n=== Latest research subgraph state ===")
print(research_state.values)
# 预期类似：
# {
#   'request': 'third task',
#   'result': "research handled 'third task' (visit 3)",
#   'visits': 3,
#   'agent_name': 'research'
# }

print("\n=== Latest writer subgraph state ===")
print(writer_state.values)
# 预期类似：
# {
#   'request': 'third task',
#   'result': "writer handled 'third task' (visit 3)",
#   'visits': 3,
#   'agent_name': 'writer'
# }


# -----------------------------
# 9) 可选：查看底层 checkpoint，观察 namespace
# -----------------------------
print("\n=== Raw checkpoint namespaces ===")
for ckpt in checkpointer.list({"configurable": {"thread_id": "demo-thread"}}):
    cfg = ckpt.config["configurable"]
    print("checkpoint_ns =", cfg["checkpoint_ns"], "checkpoint_id =", cfg["checkpoint_id"])

PyTorch 工具箱：Module、functional、optim 与初始化

Sat, 28 Mar 2026 00:00:00 GMT

这一篇主要整理自 pytorch_learning/pytorch_6.py 到 pytorch_learning/pytorch_10.py，以及 liuer_pytorch/9.ipynb 里那部分对 PyTorch 包结构的速查总结。这些内容单看都不难，但最容易散，放到一起反而更适合复习。

1. `nn.Module` 是网络的基本壳

PyTorch 里最核心的对象，就是继承 nn.Module 的网络。

import torch as t
from torch import nn


class Perceptron(nn.Module):
    def __init__(self, in_features, hidden_features, out_features):
        super().__init__()
        self.layer1 = nn.Linear(in_features, hidden_features)
        self.layer2 = nn.Linear(hidden_features, out_features)

    def forward(self, x):
        x = self.layer1(x)
        x = t.sigmoid(x)
        return self.layer2(x)

这里的经验可以记成一句：

只要一个结构里有可学习参数，它大概率就应该放进 nn.Module

这样：

参数会被自动注册
model.parameters() 才能收集到它们
优化器才能更新它们

2. `nn` 和 `nn.functional` 的区别

我之前很容易把这两个混着用。现在更清楚的理解是：

nn.*：偏对象化，适合有参数或有状态的层
nn.functional.*：偏无状态纯函数，适合直接在 forward() 里调用

比如：

nn.Linear、nn.Conv2d 用 nn
F.relu、F.max_pool2d 这种更适合用 functional

pytorch_9.py 里也有个很直观的小例子：

import torch as t
from torch import nn

inp = t.randn(2, 3)
model = nn.Linear(3, 4)
output1 = model(inp)
output2 = nn.functional.linear(inp, model.weight, model.bias)
print(output1 == output2)

本质是一样的，只是组织代码的方式不同。

3. 优化器：不是只有 `SGD`

在最开始的练习里，我几乎总是用：

optimizer = torch.optim.SGD(model.parameters(), lr=0.01)

但到了 pytorch_8.py，有两个很实用的工程技巧：

技巧一：不同层用不同学习率

optimizer = torch.optim.SGD(
    [
        {"params": net.features.parameters()},
        {"params": net.classifier.parameters(), "lr": 1e-2},
    ],
    lr=1e-5,
)

这个在迁移学习和微调时非常常见。

技巧二：动态调整学习率

虽然这里的代码只是做演示，但背后的工程直觉很重要：
学习率不是“一次写死到训练结束”，而是常常需要按阶段调。

4. 参数初始化

大多数时候，nn.Module 已经带了合理默认初始化。
但 pytorch_9.py 也提醒我，初始化并不是完全不用管。

比如：

from torch.nn import init

init.xavier_normal_(model.weight)

Xavier 初始化背后的目标，是让信号在网络中传播得更稳定，不容易一开始就炸掉或塌掉。

5. 其他容易散的小工具

pytorch_10.py 虽然比较像提纲，但它点出了真正做项目时经常绕不过去的方向：

自定义 Dataset
torchvision
可视化工具
GPU 加速
模型保存与加载

这些内容暂时还没有被我完全展开成独立文章，但它们其实构成了 PyTorch 从“写模型”到“做工程”的入口。

6. 把 PyTorch 的包结构记成一个简单地图

我后来比较喜欢的记法是：

torch.*：张量和基础运算
torch.nn.*：网络层、损失函数、模块
torch.nn.functional.*：无状态操作
torch.optim.*：参数更新

这样至少不会在代码里每次都把几个包的职责混掉。

7. 这一阶段该记住什么

如果把这篇压缩成最少几句话，我会记：

nn.Module 是网络的组织方式，不只是一个语法壳。
有参数的层优先用 nn.*，无状态操作常用 F.*。
优化器不是黑盒配置项，而是训练策略的一部分。
初始化、学习率、数据集接口这些“边角 API”，其实很影响真实训练体验。

这篇看起来像杂项，但真正写 PyTorch 项目时，它往往是最常用的一层。

RAG 数据加载：文档解析与预处理入口

Sat, 28 Mar 2026 00:00:00 GMT

RAG 的第一步不是“问模型”，而是“把外部知识变成可处理的数据”。这一篇主要整理文档加载器和预处理环节，为后面的分块与索引打底。

RAG - 数据加载

一、文档加载器

1. 主要功能

RAG 系统中，数据加载是整个流水线的第一步，也是不可或缺的一步。文档加载器负责将各种格式的非结构化文档（如PDF、Word、Markdown、HTML等）转换为程序可以处理的结构化数据。数据加载的质量会直接影响后续的索引构建、检索效果和最终的生成质量。

文档加载器在 RAG 的数据管道中一般需要完成三个核心任务，一是解析不同格式的原始文档，将 PDF、Word、Markdown 等内容提取为可处理的纯文本，二是在解析过程中同时抽取文档来源、页码、作者等关键信息作为元数据，三是把文本和元数据整理成统一的数据结构，方便后续进行切分、向量化和入库，其整体流程与传统数据工程中的抽取、转换、加载相似，目标都是把杂乱的原始文档清洗并对齐为适合检索和建模的标准化语料。

2. 主流RAG文档加载器

工具	功能	适用场景	特点
PyMuPDF4LLM	PDF → Markdown 转换，OCR + 表格识别	科研文献、技术手册	开源免费，GPU 加速
TextLoader	基础文本文件加载	纯文本处理	轻量高效
DirectoryLoader	批量目录文件处理	混合格式文档库	支持多格式扩展
Unstructured	多格式文档解析	PDF、Word、HTML 等	统一接口，智能解析
FireCrawlLoader	网页内容抓取	在线文档、新闻	实时内容获取
LlamaParse	深度 PDF 结构解析	法律合同、学术论文	解析精度高，商业 API
Docling	模块化企业级解析	企业合同、报告	IBM 生态兼容
Marker	PDF → Markdown，GPU 加速	科研文献、书籍	专注 PDF 转换
MinerU	多模态集成解析	学术文献、财务报表	集成 LayoutLMv3 + YOLOv8

二、Unstructured文档处理库

Unstructured是一个专业的文档处理库，专门设计用于RAG和AI微调场景的非结构化数据预处理。提供了统一的接口来处理多种文档格式，是目前应用较广泛的文档加载解决方案之一。Unstructured 在格式支持和内容解析方面具有明显优势，它一方面支持 PDF、Word、Excel、HTML、Markdown 等多种文档格式，并通过统一的 API 接口避免为不同格式分别编写代码，另一方面可以自动识别标题、段落、表格、列表等文档结构，同时保留相应的元数据信息。

元素类型	描述
Title	文档标题
NarrativeText	由多个完整句子组成的正文文本，不包括标题、页眉、页脚和说明文字
ListItem	列表项，属于列表的正文文本元素
Table	表格
Image	图像元数据
Formula	公式
Address	物理地址
EmailAddress	邮箱地址
FigureCaption	图片标题 / 说明文字
Header	文档页眉
Footer	文档页脚
CodeSnippet	代码片段
PageBreak	页面分隔符
PageNumber	页码
UncategorizedText	未分类的自由文本
CompositeElement	分块处理时产生的复合元素*

三、从LangChain封装到原始Unstructured

from unstructured.partition.auto import partition

# PDF文件路径
pdf_path = "../../data/C2/pdf/rag.pdf"

# 使用Unstructured加载并解析PDF文档
elements = partition(
    filename=pdf_path,
    content_type="application/pdf"
)

# 打印解析结果
print(f"解析完成: {len(elements)} 个元素, {sum(len(str(e)) for e in elements)} 字符")

# 统计元素类型
from collections import Counter
types = Counter(e.category for e in elements)
print(f"元素类型: {dict(types)}")

# 显示所有元素
print("\n所有元素:")
for i, element in enumerate(elements, 1):
    print(f"Element {i} ({element.category}):")
    print(element)
    print("=" * 60)

不过这里的运行结果其实一般，首先是Could not get FontBBox...，通常是PDF里字体数据不规范；然后，No languages specified, defaulting to English 和一堆 short text... Defaulting to English 也不是报错，只是说明它没拿到语言参数，默认按英文处理。

partition 函数参数解析：

filename: 文档文件路径，支持本地文件路径；
content_type: 可选参数，指定MIME类型（如"application/pdf"），可绕过自动文件类型检测；
file: 可选参数，文件对象，与 filename 二选一使用；
url: 可选参数，远程文档 URL，支持直接处理网络文档；
include_page_breaks: 布尔值，是否在输出中包含页面分隔符；
strategy: 处理策略，可选 "auto"、"fast"、"hi_res" 等；
encoding: 文本编码格式，默认自动检测。

如果要更好的处理，可以直接from unstructured.partition.pdf import partition_pdf用专门的pdf包，提供方更多特有的参数选项，如OCR语言设置、图像提取、表格结构推理等高级性能，同时性能更优。当我们换用这个包，且使用his_res之后，明显效果好多了，NarrativeText 从之前很少，变成了 68 个，正文识别明显更好了；出现了 Table、FigureCaption、Image，说明版面理解生效了；像“历史沿革”“技术定义”“工作流程”下面的大段正文，基本能被连续抽出来了。不过，hi_res需要一些新的系统依赖，比如用于OCR的Tesseract、用于PDF的Popler。

而在实际应用中，针对 pdf 的处理，目前更多选用的是 PaddleOCR、MinerU 等模型或工具。

策略梯度入门：从定理到 REINFORCE

Sat, 28 Mar 2026 00:00:00 GMT

前面我们已经跨过了RL到三个大的难题: model-base 2 model-free ( 用数据代替建模 ), non-incremental 2 incremental ( 从递推形式变成增量形式 ), tabular representation 2 function representation (当然, 这个目前大多数的解决还是依赖于Policy网络 ). 但是, 还是有些问题无法解决的……

一. 策略梯度定理

DQN虽然某些地方获得了成功, 但是其本身还是有许多问题. 比如:

因为是value-based, 策略是隐式的, 无法表示随机策略. 而某些问题, 随机策略反而是最好的, 需要以不同概率选择不同动作. DQN之类的算法在实现时候采用了贪心策略, 显然无法按照概率执行候选动作.
Q值的微小改变就会让动作选中、不选中. 举例来说Q值排名前两名的动作可能只相差了0.0001这样子, 增大一点第二位的动作就变成最优了. 所以说, 不稳定, 影响算法收敛.

对于1我们可以再进行举例解释: 下图黑色部分为墙壁, 扫地机器人的功能是避开仓鼠吸灰, 在左侧红色区域时, 机器人可能会向左, 发现仓鼠, 从而向右来吸灰. 但是, 当同样的state发生, 扫地机器人进入右侧红色区域时候, 应该采取的是向左的action, 这就导致了同样的state, 产生了两种不同应该采取的action, 但是机器人却学到的是相同的东西, 陷入了混淆的感知态 (perceptual aliasing) , 混合推导.

Q(s, a)的输入是智能体感知态s, 而非环境的真实状态, 所以Q值是与感知态强绑定的. 正确的, 应该在红色区域学到的策略, 并非是向左或向右, 而应该是一本概率向左, 一半概率向右 这种有概率的策略, 确定性策略无法应对非对称问题.

因此, 我们不学习值函数, 而是采用显示学习策略(policy-based) 这样就可以学习到随机的策略, 而不会一直被卡住.

为了解决这个问题, 我们不如采用更直接的方法来直接学习策略, 将策略参数化, 让神经网络学习更新参数$\theta$ , 输出策略$\pi_\theta$. 这个策略是s状态下执行各种动作的概率值, 条件概率. 此时的神经网络输出层的作用类似于多分类问题的softmax回归, 输出的是一个概率分布，只不过这里的概率分布不是用来进行分类, 而是执行动作:

$$ \pi_{\theta}(s) = P[a|s; \theta] \tag{1.1} $$

如何衡量这个动作的概率分布好不好呢 ? 在一系列动作, 或者说一个轨迹trajectory之后, 我们把每一步的奖励累积起来, 来评价这个轨迹的好坏. 我们通过优化预期的累计奖励$J(\theta)$ 这个目标函数, 就可以得到最佳策略. $$ J(\theta)=\Sigma_\tau P(\tau;\theta)R(\tau)\tag{1.2} $$ 所以, 我们现在就要通过梯度上升的方法, 让$J(\theta)$ 最大, 称为策略梯度. 首先, 我们对其求梯度: $$ \nabla_\theta J(\theta)=\nabla_\theta \Sigma_\tau P(\tau;\theta)R(\tau)=\Sigma_\tau \nabla_\theta P(\tau;\theta)R(\tau)\tag{1.3} $$ $$ =\Sigma_\tau \frac{\nabla_\theta P(\tau;\theta)}{P(\tau;\theta)}P(\tau;\theta)R(\tau)\tag{1.4} $$ 而根据对数函数复合函数求导公式: $$ \nabla_xlogf(x)=\frac{\nabla_x f(x)}{f(x)}\tag{1.5} $$ 我们可以进一步化简公式, 得到: $$ \nabla_\theta J(\theta)=\Sigma_\tau P(\tau;\theta)\nabla_\theta logP(\tau;\theta)R(\tau) \tag{1.6} $$ 而这个时候, 又会巧妙发现这是符合概率论中期望定义的一个式子, 前面是走其中一个trajectory的概率, 后面是走这个trajectory对应的值. 现在将其写为期望的形式: $$ \nabla_\theta J(\theta)=E_{\tau \sim P(\tau;\theta)} \Sigma_\tau \nabla_\theta logP(\tau;\theta)R(\theta) \tag{1.7} $$ 继续, 根据大数定律, 我们可以通过采样的方法来近似出对$\theta$ 的梯度, 得到如下的式子: $$ \nabla_\theta J(\theta)=\frac{1}{m}\sum \limits_{i=1}^{m}\nabla_\theta logP(\tau^{(i)};\theta)R(\tau^{(i)}) \tag{1.8} $$ 其中i表示第i次流程, 这样就可以一轮一轮走过流程, 来训练这个值让他最大. 这样其实已经从宏观把握了如何进行的优化,

继续化简, 其中$P(\tau ^{i};\theta)$ 是一个链条, 表示在$\pi(\theta)$ 这个策略下 , 选择$\tau$ 这个trajectory的概率:

$$ P(\tau;\theta)=\Pi_{t=0}P(s_{t+1}|s_t;a_t)\pi_\theta(a_t|s_t) \tag{1.9} $$ 其中第i次采样的结果是: $$ P(\tau ^ {i};\theta)=\mu(s_0)\prod\limits_{t=0}^{H} P(s_{t+1}^{(i)}|s_{t}^{(i)}, a_{t}^{(i)})\pi_\theta(s_{t}^{(i)}, a_{t}^{(i)}) \tag{1.10} $$ 这里说明一下, 在第i次采样中$\theta$ 是$s_t^{(i)}$ 中$a_t^{(i)}$ 对可能性是$\pi_\theta(s_{t}^{(i)}, a_{t}^{(i)})$, 但即时该动作也可能到不了$s_{t+1}$, 举个例子如果路滑可能就会多走一格. 这取决于环境的反馈概率, 也就是$P(s_{t+1}^{(i)}|s_{t}^{(i)}, a_{t}^{(i)})$ . 而$\mu(s_0)$ 则是代表以$s_0$ 开始的概率, 或者说$s_0$ 的概率分布, 因为某些环境中起点都有可能. 所以从$\mu$ 开始, 累乘后面的式子到结束, 就是一个trajectory的P.

考虑形式, 两边取对数对$\theta$ 求梯度, 用对数性质化简: $$ \begin{aligned}&\nabla_\theta\log P(\tau^{(i)};\theta)=\nabla_\theta\log\left[\mu(s_0)\prod_{t=0}^HP\left(s_{t+1}^{(i)}\mid s_t^{(i)},a_t^{(i)}\right)\pi_\theta\left(a_t^{(i)}\mid s_t^{(i)}\right)\right]\

&\nabla_\theta\log P(\tau^{(i)};\theta)=\nabla_\theta\left[\log\mu(s_0)+\sum_{t=0}^H\log P\left(s_{t+1}^{(i)}\mid s_t^{(i)},a_t^{(i)}\right)+\sum_{t=0}^H\log\pi_\theta\left(a_t^{(i)}\mid s_t^{(i)}\right)\right]\end{aligned}\tag{1.11} $$

而右侧的式子, 根据和的梯度就等于梯度的和, 继续化简:

$$ \begin{aligned}&\nabla_\theta\log P(\tau^{(i)};\theta)=\nabla_\theta\log\mu(s_0)+\nabla_\theta\sum_{t=0}^H\log P\left(s_{t+1}^{(i)}\mid s_t^{(i)},a_t^{(i)}\right)+\nabla_\theta\sum_{t=0}^H\log\pi_\theta\left(a_t^{(i)}\mid s_t^{(i)}\right)\

&\nabla_\theta\log P(\tau^{(i)};\theta)=\nabla_\theta\sum_{t=0}^H\log\pi_\theta\left(a_t^{(i)}\mid s_t^{(i)}\right)\\end{aligned}\tag{1.12} $$

综合一下, 将1.12式代入1.8式子, 最终就得到了$J(\theta)$ 的梯度. $$ \nabla_\theta J(\theta)=\hat{g}=\frac1m\sum_{i=1}^m\sum_{t=0}^H\nabla_\theta\log\pi_\theta\left(a_t^{(i)}\mid s_t^{(i)}\right)R(\tau^{(i)})\tag{1.13} $$ 上面其实是m次采样之后的策略梯度. 我们也可以将本式子再回归本源, 写回期望形式: $$ \nabla_\theta J(\theta)=\mathbb{E}{\pi\theta}[\nabla_\theta log\pi_\theta (a_t|s_t)R(\tau)]\tag{1.14} $$

这个式子, 就是我们需要的策略梯度定理 ! 虽然我们进行了非常繁琐的推理, 但是这个期望式子意外的非常简洁. 值得注意的是, 这里的$\nabla_\theta log\pi_\theta (a_t|s_t)$ 在统计学上被称为得分函数 (Score Function), 它的定义就是对数似然函数对某个参数的偏导数. 这个量有一些很有趣的数学性质.

得分函数在真实参数下的期望为0. 这是因为对数似然函数的导数反映了似然函数的“坡度”, 而在真实参数$\theta$ 下, 似然函数达到极大值, 坡度为0.
得分函数的方差不为0, 而是与Fisher信息密切相关.

当然上面的性质不用管, 只需要认识到它是一个重要的统计量, 蕴含着更深入的信息. 比如在求解MLE时, 我们就是通过求解得分函数等于零的点来估计参数.

回到这个式子, 对于概率分布$\pi_\theta(a|s)$ , 得分函数定义为该分布的对数似然关于参数$\theta$ 的梯度. 我们可以把它看作是在策略空间中指向增加特定动作$a_t$ 概率的方向. 这个值指导我们, 如何微调参数$\theta$ , 才能最有效地增加/减少选择特定动作$a_t$ 的概率. 如果整个轨迹的回报$R(\tau)$ 是正的, 就沿着这个方向更新; 如果是负的, 就反方向更新.

而且, 这个式子还有自动调节步长的能力. 在概率较低的动作上, 得分函数的幅度较大 (可以想象log图像) , 更新步长也就越大. 换言之, 重视那些很少被选中但是有潜力的动作, 在策略梯度中起到权重调节器的作用.

二. 策略梯度的实现技巧

1. 基线 (baseline)

基线通常是一个常数或函数, 用于对轨迹回报进行调整, 将回报转换为对基线的优势 (advantage), 这也是优势函数中优势一词的来源 (优势函数是后面AC框架的重要概念, 我们将会在下一节介绍) .

引入baseline的好处不止除了从减小方差的方向理解, 我们观察如下例子, 假设在某个状态有三个动作a、b、c可以执行. 根据式子1.13, 我们要把这三个动作的概率, 对数概率都提高. 但是它们前面的权重$R(\tau)$ 是不一样的, 权重有大有小. 权重小的, 该动作的概率提升的就少, 权重大的概率更提升的就大. 但是对数概率是一个概率, 所以对数概率和肯定是log1也就是0. 因此, 提高少的, 在做完归一化之后会发现居然是下降的, 提升多的才会上升.

而即使是这样, 也还是理想的状态. 因为我们假设a、b、c都被采样到了, 但是实际上我们只采样到了少量的s-a对, 可能有的动作根本没采样到, 那么这些动作就会不断下降, 但是没被采样的明明不一定是不好的动作.

为了解决这个问题, 我们可以让奖励不总是正的, 通过把奖励减去b的方法, 让$R(\tau)>b$ 的时候, 概率就上升, 反之概率就下降. 至于b怎么设置, 我们可以对$R(\tau)$ 的值取期望, 拿到一个“平均”的准线, 也就是说: $$ b \approx E[R(\tau)] \tag{2.1.1} $$

使用了这一技巧的公式可以写为: $$ \nabla\bar{R}{\theta}\approx\frac{1}{N}\sum{n=1}^{N}\sum_{t=1}^{T_{n}}\left( R\left(\tau^{n}\right)-b\right)\nabla\log p_{\theta}\left(a_{t}^{n}\mid s_{t}^{n}\right) \tag{2.1.2} $$

2. 分配合适的分数

除了基线之外, 策略梯度算法还有另外一种实现的技巧, 那就是给每一个动作分配合适的分数 (credit). 这是因为, 在同一场游戏里, 我们对所有的状态-动作对使用同样的奖励项进行加权.

这显然是不公平的, 在同一场游戏里面, 也许有些动作是好的, 有些动作是不好的. 假设整场游戏的结果是好的, 但并不代表这场游戏里面每一个动作都是好的, 反之亦然. 所以我们希望可以给每一个不同的动作前面都乘上不同的权重. 我们再像之前value-based一样, 给未来的奖励做一个折扣, 式子就变成了: $$ \nabla\bar{R}{\theta}\approx\frac{1}{N}\sum{n=1}^{N}\sum_{t=1}^{T_{n}}\left( \sum_{t^{\prime}=t}^{T_{n}}\gamma^{t^{\prime}-t}r_{t^{\prime}}^{n}-b\right) \nabla\log p_{\theta}\left(a_{t}^{n}\mid s_{t}^{n}\right) \tag{2.1.3} $$

三. REINFORCE算法(蒙特卡洛策略梯度)

在前面的讨论中, 我们已经推导出了策略梯度采样下的形式, 并对其进行了优化得到了2.1.3. 既然是采样, 我们可以与value-based一开始一样, 采用MC的方法对梯度奖励进行估计.

显然, 我们的分配后合适奖励的部分, 可以继续写成带折扣回报 (return)的形式, 即第n次采样时间步t的回报为$G_t^n$ (为了区分, 我们把蒙特卡洛采样的总回报用G表示而不是R ). 然后我们就可以将其写为: $$ \nabla\bar{R}{\theta}\approx\frac{1}{N}\sum{n=1}^{N}\sum_{t=1}^{T_{n}}G_{t}^ {n}\nabla\log\pi_{\theta}\left(a_{t}^{n}\mid s_{t}^{n}\right) \tag{3.1} $$ Reinforce算法是Williams提出的经典策略梯度算法之一, 其步骤如下:

用当前策略走一条完整的轨迹
倒退计算这条轨迹中每个时间步的累计回报
相乘得到一条轨迹的梯度估计. (即上述梯度公式)
沿着梯度上升的方向更新策略 $\theta \leftarrow \theta+\alpha \hat{g}$

我们举一个具体的例子:

假设我们在玩一个简单的游戏，状态 s 是当前游戏画面的像素（一个向量或张量）。可能的动作为：[“上”, “下”, “左”, “右”]
1. 构建策略网络：
我们设计一个神经网络，输入层接收状态 s（像素数据）。
中间有若干隐藏层。
输出层有4个神经元，分别对应4个动作。
最后通过一个 Softmax 激活函数，将这4个神经元的输出值转换成一个概率分布（所有输出值之和为1）。
2. 定义参数 θ：
这个网络里所有的连接权重（Weights）和偏置（Bias），从输入层到第一个隐藏层，一直到输出层，所有这些数字，共同构成了参数向量 θ。
3.策略的执行：
当智能体处于某个状态 s_t 时，它将 s_t 输入网络。
网络根据当前的参数 θ 进行计算，在输出层得到一个概率分布，例如 [0.1, 0.7, 0.1, 0.1]。
智能体就按照这个概率分布随机选择一个动作（比如有70%的概率选择“下”）。这就是你提到的“随机的策略，而不会一直被卡住”的体现。
4.策略的更新（学习）：
智能体执行动作，从环境中获得奖励（Reward），并进入新的状态。
经过一系列这样的交互（一个轨迹），我们通过策略梯度 等算法来计算：如果稍微调整参数 θ，是否能使得获得的总奖励增加？
然后，我们使用梯度上升法来更新参数 θ（例如：θ = θ + α * ∇J(θ)，其中 ∇J(θ) 是策略梯度）。
θ 更新后，我们的“策略机器”就发生了改变。对于同一个状态 s，网络会输出一个新的、期望能带来更高奖励的概率分布。

我们可以看出, 早期的REINFORCE算法, 梯度上就等于$\nabla_\theta log\pi_\theta (a_t|s_t)G(\tau)$ , 方差很大. 当使用上述的基线来进行优化变成了REINFORCE with baseline算法时, 就已经产生了优势的雏形了.

FastAPI 组织逻辑：Depends、yield、错误处理与安全起步

Fri, 27 Mar 2026 00:00:00 GMT

前面几篇主要在搭“接口表层”。到了这里，FastAPI 开始真正长出工程味：共享逻辑、资源生命周期、认证入口和错误通道都在这一层。

1. `Depends` 在干什么

官方把依赖项单独拆成一章，这一章非常关键，因为 FastAPI 的很多高级能力都站在它上面。

from typing import Annotated
from fastapi import Depends, FastAPI

app = FastAPI()


async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):
    return {"q": q, "skip": skip, "limit": limit}


@app.get("/items/")
async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
    return commons


@app.get("/users/")
async def read_users(commons: Annotated[dict, Depends(common_parameters)]):
    return commons

这里可以直接把依赖注入理解成：

路径函数声明“我需要什么”
FastAPI 负责先把这段逻辑跑完
再把结果注进来

它最值的地方在于复用：

共享查询参数
共享数据库会话
共享认证逻辑

2. `Depends` 里传的其实是可调用对象

官方文档明确提到，Depends() 里只接受一个参数，而且这个参数必须是可调用对象。你不需要自己加括号去调用它，FastAPI 会负责调用。
来源：Dependencies 官方页 https://fastapi.tiangolo.com/zh/tutorial/dependencies/

所以依赖不一定非得是函数，也可以是类。

from typing import Annotated
from fastapi import Depends, FastAPI

app = FastAPI()


class CommonQueryParams:
    def __init__(self, q: str | None = None, skip: int = 0, limit: int = 100):
        self.q = q
        self.skip = skip
        self.limit = limit


@app.get("/items/")
async def read_items(
    commons: Annotated[CommonQueryParams, Depends(CommonQueryParams)],
):
    return {"q": commons.q, "skip": commons.skip, "limit": commons.limit}

这类写法的优势主要在于：

编辑器补全更自然
组织多参数依赖时更清楚

3. 子依赖和依赖缓存

依赖还可以继续依赖别的依赖：

from typing import Annotated
from fastapi import Cookie, Depends, FastAPI

app = FastAPI()


def query_extractor(q: str | None = None):
    return q


def query_or_cookie_extractor(
    q: Annotated[str | None, Depends(query_extractor)],
    last_query: Annotated[str | None, Cookie()] = None,
):
    if not q:
        return last_query
    return q


@app.get("/items/")
async def read_query(
    query_or_default: Annotated[str | None, Depends(query_or_cookie_extractor)],
):
    return {"q_or_cookie": query_or_default}

而且同一个请求里，FastAPI 不会重复计算同一个依赖结果，而是会缓存并复用。

4. 装饰器依赖和全局依赖

有些依赖不是为了把值注入进函数，而是为了让某个检查逻辑在进入路由前一定执行。这时可以放到装饰器上：

from typing import Annotated
from fastapi import Depends, FastAPI, Header, HTTPException

app = FastAPI()


async def verify_token(x_token: Annotated[str, Header()]):
    if x_token != "fake-super-secret-token":
        raise HTTPException(status_code=400, detail="X-Token header invalid")


@app.get("/items/", dependencies=[Depends(verify_token)])
async def read_items():
    return [{"item": "Foo"}, {"item": "Bar"}]

如果整个应用都需要某个依赖，也可以直接写到 FastAPI(...) 上。

5. `yield` 依赖：提供资源，也负责回收资源

你本地 19.md 这部分其实已经抓到重点了：yield 依赖不是返回一个值然后结束，而是先把值交出去，等请求处理完，再回来执行清理逻辑。

async def get_db():
    db = DBSession()
    try:
        yield db
    finally:
        db.close()

可以直接把它理解成：

yield 前：准备资源
yield 出去：把资源交给路径函数
yield 后：做清理

最典型的场景就是数据库会话、文件句柄、临时连接。

6. 为什么 `try/finally` 总和 `yield` 一起出现

因为 finally 能保证：

即使中间抛异常
即使路径函数失败
清理逻辑也最终会执行

这一点在资源管理里很重要，不然连接和会话很容易泄漏。

7. 错误处理：先从 `HTTPException` 开始

from fastapi import FastAPI, HTTPException

app = FastAPI()

items = {"foo": "The Foo Wrestlers"}


@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id not in items:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item": items[item_id]}

这是 FastAPI 最常见的错误出口。

如果只记一个点，那就是：

raise HTTPException(...)

比手写响应对象更像“真正的错误通道”。

8. 自定义异常处理器

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse


class UnicornException(Exception):
    def __init__(self, name: str):
        self.name = name


app = FastAPI()


@app.exception_handler(UnicornException)
async def unicorn_exception_handler(request: Request, exc: UnicornException):
    return JSONResponse(
        status_code=418,
        content={"message": f"Oops! {exc.name} did something. There goes a rainbow..."},
    )

这一步意味着错误处理开始从“单个路由里的 if 判断”升级成“全局错误策略”。

9. 处理校验错误：`RequestValidationError`

当客户端输入数据不合法时，FastAPI 内部会抛出 RequestValidationError。这类错误也可以被接管：

from fastapi import FastAPI, HTTPException
from fastapi.exceptions import RequestValidationError
from fastapi.responses import PlainTextResponse
from starlette.exceptions import HTTPException as StarletteHTTPException

app = FastAPI()


@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(request, exc):
    return PlainTextResponse(str(exc.detail), status_code=exc.status_code)


@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request, exc: RequestValidationError):
    message = "Validation errors:"
    for error in exc.errors():
        message += f"\\nField: {error['loc']}, Error: {error['msg']}"
    return PlainTextResponse(message, status_code=400)

官方还特别提到一个细节：

业务里抛错用 FastAPI 的 HTTPException
但注册异常处理器时，更适合注册 Starlette 的 HTTPException

因为这样连 Starlette 内部抛出的同类错误也能一起接住。
来源：Handling Errors 官方页 https://fastapi.tiangolo.com/zh/tutorial/handling-errors/

10. 安全起步：`OAuth2PasswordBearer`

安全入门那一页最值得先记住的不是完整 OAuth2 流程，而是：

FastAPI 把认证入口也做成了依赖

from fastapi import Depends, FastAPI
from fastapi.security import OAuth2PasswordBearer

app = FastAPI()

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


@app.get("/items/")
async def read_items(token: str = Depends(oauth2_scheme)):
    return {"token": token}

这里的 tokenUrl="token" 指向的是相对路径 ./token，官方文档里专门解释了这一点。
来源：Security First Steps 官方页 https://fastapi.tiangolo.com/zh/tutorial/security/first-steps/

一旦加上它，/docs 右上角就会出现 Authorize 按钮，交互文档会自动进入“可以带认证信息调试”的状态。

这一页最重要的意义，不是立刻把认证做完，而是先意识到：

安全在 FastAPI 里不是“外挂”
而是沿着依赖注入系统自然长出来的

LangChain 入门：安装、Quick Start 与设计哲学

Fri, 27 Mar 2026 00:00:00 GMT

这篇是整条学习线的起点文章。它保留了“先搭一个最小 Agent 看全貌”的视角，但我把它放在真正进入各组件之前，让它承担“先看全景图，再拆零件”的作用。

1. 介绍与安装

LangChain 是一个用于构建LLM应用的开源开发框架，有Python和Java两种包，注重组合和模块化。利用LangChain，可以创造完全自定义的agents和LLM应用，可以在不到10行代码内连接到OpenAI、Anthropic、Google等。

关于它和LangGraph、Deep Agents的区别，也给的很详细，大概就是Deep Agents开箱即用；LangChain 代理构建在 LangGraph 之上，以提供持久执行、流媒体、人工干预、持久性等功能。基本使用 LangChain 代理不需要了解 LangGraph，只要需要深度自定义的时候才用LangGraph。

我们基于LangChain的官方文档进行学习。

先安装一下，然后LangChain说自己对许多LLM有融合，这些融合在独立的包中，所以我们安装一下对OpenAI的支持。

pip install -U langchain
pip install -U langchain-openai

2. 获得AI coding assistant

官网提供了一个LangChain Docs MCP server来帮助你的agent获取最新文档，并提供一个LangChain Skills来帮你提高agent在LangChain ecosystem的表现。我正好有一个codex账号，平时用agent插件辅助编码，现在就接入试试。

首先按照官网提供的MCP地址，给codex配置，然后用prompt测试连接：

可以看到，已经成功连接到了LangChain Docs的API。

然后，我们依旧按照官网地址，给codex提供LangChain Skills。这个skill可以帮助搭建LangChain、LangGraph和Deep Agents。

npx是Node.js生态里的一个通用命令执行工具，用于直接运行npm包提供的命令。所谓Node.js是JavaScript程序的运行环境，npx skills可以运行一个叫skills的Node.js CLI工具。至于为什么不继续发布到Python的PyPI，主要还是因为JS还有一些自己的好处，我问了问AI总结如下：

总之，只要“support the Agent Skills specification”，也就是说agent支持标准的Agent规范，就可以用命令添加。Agent Skills的介绍如下：Agent Skills文档，这里按下不表，之后进行学习，不然就跑偏太远了。

npx skills add langchain-ai/langchain-skills --skill '*' --yes

这个命令实际上干了两件事：

临时拉取工具： npx 去网上临时下载了一个名叫 skills 的执行工具（这个工具被塞进了 ~/.npm/_npx 里）。
执行添加动作：这个 skills 工具运行了 add 命令，把 langchain-skills 添加到了你的当前工作目录下。

我们看看目录，果然多了一堆东西：

总之，这个先这样，现在我们是把skills放在了当前目录下，在这里使用agent可以让它自己去读取。但是其实也可以放~/.agents/skills/一劳永逸，用这样的命令：

npx skills add langchain-ai/langchain-skills --skill '*' --agent codex -g

执行完这条，还默认给我装了Find Skills的Skill，我们检查文件如下：

里面有点像说明书，暂时不展开，之后应该会细看。

3. 搭建一个基础Agent

官网给的最小实例，好像是默认你装了OpenAI兼容包，设置了OpenAI的key，而且走官方路径。我们走的中转，环境变量也是在.env中，因此我们自己要设置一下：

import os
from dotenv import load_dotenv
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

load_dotenv()

model = ChatOpenAI(
    model = "gpt-4o-mini",
    api_key=os.environ["QIHANG_API"],
    base_url=os.environ["QIHANG_BASE_URL"],    
)

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_agent(
    model=model,
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

# Run the agent
result = agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

print(result)

我们来看看原始输出的结果：

{
  "messages": [
    {
      "type": "HumanMessage",
      "content": "what is the weather in sf",
      "additional_kwargs": {},
      "response_metadata": {},
      "id": "11c974bc-3204-4e15-9391-40db1cd6c982"
    },
    {
      "type": "AIMessage",
      "content": "",
      "additional_kwargs": {
        "refusal": null
      },
      "response_metadata": {
        "token_usage": {
          "completion_tokens": 16,
          "prompt_tokens": 56,
          "total_tokens": 72,
          "completion_tokens_details": {
            "accepted_prediction_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 0,
            "rejected_prediction_tokens": 0
          },
          "prompt_tokens_details": {
            "audio_tokens": 0,
            "cached_tokens": 0
          }
        },
        "model_provider": "openai",
        "model_name": "gpt-4o-mini-2024-07-18",
        "system_fingerprint": "fp_eb37e061ec",
        "id": "chatcmpl-DNMHzlR2RTmob84VvtgxHEcA2jWwF",
        "finish_reason": "tool_calls",
        "logprobs": null
      },
      "id": "lc_run--019d2608-a56b-7991-84f5-3a40addac2bb-0",
      "tool_calls": [
        {
          "name": "get_weather",
          "args": {
            "city": "San Francisco"
          },
          "id": "call_GHZls5pzrZTFanydz2VJANUb",
          "type": "tool_call"
        }
      ],
      "invalid_tool_calls": [],
      "usage_metadata": {
        "input_tokens": 56,
        "output_tokens": 16,
        "total_tokens": 72,
        "input_token_details": {
          "audio": 0,
          "cache_read": 0
        },
        "output_token_details": {
          "audio": 0,
          "reasoning": 0
        }
      }
    },
    {
      "type": "ToolMessage",
      "content": "It's always sunny in San Francisco!",
      "name": "get_weather",
      "id": "f84e1e0b-bf8b-4dcd-bdc2-cd9d40a7c1b2",
      "tool_call_id": "call_GHZls5pzrZTFanydz2VJANUb"
    },
    // 下面就是message列表的最后一项，AIMessage
    {
      "type": "AIMessage",
      "content": "The weather in San Francisco is currently sunny!",
      "additional_kwargs": {
        "refusal": null
      },
      "response_metadata": {
        "token_usage": {
          "completion_tokens": 11,
          "prompt_tokens": 86,
          "total_tokens": 97,
          "completion_tokens_details": {
            "accepted_prediction_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 0,
            "rejected_prediction_tokens": 0
          },
          "prompt_tokens_details": {
            "audio_tokens": 0,
            "cached_tokens": 0
          }
        },
        "model_provider": "openai",
        "model_name": "gpt-4o-mini-2024-07-18",
        "system_fingerprint": "fp_eb37e061ec",
        "id": "chatcmpl-DNMI1dEwEqVRaNAX2FI8sUJXZl9nW",
        "service_tier": "default",
        "finish_reason": "stop",
        "logprobs": null
      },
      "id": "lc_run--019d2608-ae45-7a23-a3d7-79389811c5fc-0",
      "tool_calls": [],
      "invalid_tool_calls": [],
      "usage_metadata": {
        "input_tokens": 86,
        "output_tokens": 11,
        "total_tokens": 97,
        "input_token_details": {
          "audio": 0,
          "cache_read": 0
        },
        "output_token_details": {
          "audio": 0,
          "reasoning": 0
        }
      }
    }
  ]
}

这就是回复体啦，可以看到超级长一串。我们可以将其看为四部分：用户问题、模型判断是否调用工具、工具执行结果、模型基于工具结果的最终回答。我们这里是用了一个假工具告诉Agent总是晴天。

如果我们只想抽取回复，可以拿result["messages"][-1].content来打印，就拿到了AIMessage的content：“The weather in San Francisco is currently sunny!”

4. 建立一个真实agent

按照官网的build步骤，我们开始构建，这里同样构造一个天气agent（伪）。

(1) 定义prompt

我们需要一段系统提示词，用于定义agent的角色和行为，需要保持specific和actionable。

# Step1 Defines the system prompt
SYSTEM_PROMPT = """
以下英文提示词，但是请用中文回答。
You are an expert weather forecaster, who speaks in puns.

You have access to two tools:

- get_weather_for_location: use this to get the weather for a specific location
- get_user_location: use this to get the user's location

If a user asks you for the weather, make sure you know the location. If you can tell from the question that they mean wherever they are, use the get_user_location tool to find their location.
"""

(2) 创建工具

工具允许模型通过调用您定义的函数与外部系统交互。工具可以依赖于运行时上下文(runtiem context)，并与agent内存进行交互。

@tool是将一个Python函数注册成LangChain可调用的工具，并读取工具名、参数、描述（docstring说明文档，也就是函数上面那一段三引号内部内容）、返回值。@dataclass则是python标准库中的装饰器，表达“只装数据的类”，这样可以自动生成很多样板代码，比如__init__，你可以直接写ctx = Context(user_id="1")。。

官方文档：工具应有详细文档：它们的名称、描述和参数名称成为模型提示的一部分。LangChain 的 @tool 装饰器添加元数据，并通过 ToolRuntime 参数启用运行时注入。请在工具指南中了解更多。

# Create tools
from dataclasses import dataclass
from langchain.tools import tool, ToolRuntime

@tool
def get_weather_for_location(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always rainy in {city}!"

@dataclass
class Context:
    """Custom runtime context schema."""
    user_id: str

@tool
def get_user_location(runtime: ToolRuntime[Context]) -> str:
    """Retrieve user information based on user ID."""
    user_id = runtime.context.user_id
    return "Shanghai" if user_id == "1" else "Wuhan"

(3) 配置模型

官网给出的方法，是通用对话模型的创建方法，它通过provider适配层+模型名规则识别，来走自动集成的配置。更推荐这么写，方便随时更换模型。我们在模型前面注明provider（不注明走自动判断）。

## Configure your model
import os
from dotenv import load_dotenv
from langchain.chat_models import init_chat_model

load_dotenv()

model = init_chat_model(
    model = "openai:gpt-4o-mini",
    api_key=os.environ["QIHANG_API"],
    base_url=os.environ["QIHANG_BASE_URL"],
    temperature=0.5,
    timeout=10,
    max_tokens=1000,    
)

(4) 定义回复格式

这是可选项，可以定义模型回复的格式。这里也明确说明了，除了dataclass，也可以用Pydantic来定义，LangChain只是需要一个结构化的schema。方便复习，所以我们之类就用Pydantic。

另外，其实所有dataclass都可以直接换成pydantic，比如Context。

from pydantic import BaseModel, Field

class ResponseFormat(BaseModel):
    """Response schema for the agent."""
    punny_response: str = Field(description="必须给用户的俏皮回答")
    weather_conditions: str | None = Field(
        default=None,
        description="天气补充信息"
    )

(5) 添加记忆

为agent添加记忆，以在交互之间保持状态。这使代理能够记住先前的对话和上下文。之后会专门来学习这个记忆模块，现在只做简单了解，把这个InMemorySaver传给Agent。

# Add memory
from langgraph.checkpoint.memory import InMemorySaver

checkpointer = InMemorySaver()

(6) 创建和运行agent

把前面定义过的一些参数，传进create_agent里面，创建出agent。然后，再定义一个config，调用agent的invoke，传入对话、config和Context，就可以获得回答了。

# Create and run the agent
from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy

agent = create_agent(
    model=model,
    system_prompt=SYSTEM_PROMPT,
    tools=[get_user_location, get_weather_for_location],
    context_schema=Context,
    response_format=ToolStrategy(ResponseFormat),
    checkpointer=checkpointer
)

# `thread_id` is a unique identifier for a given conversation.
config = {"configurable": {"thread_id": "1"}}

response = agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather outside?"}]},
    config=config,
    context=Context(user_id="1")
)

# print(response['structured_response'])


# Note that we can continue the conversation using the same `thread_id`.
response = agent.invoke(
    {"messages": [{"role": "user", "content": "thank you!"}]},
    config=config,
    context=Context(user_id="1")
)

print(response)

(7) 分析结果

先看一下原始结果是啥样的，我们把直接print(response)整理成了json结果，大概是这样的：

{
  "messages": [
    {
      "type": "HumanMessage",
      "content": "what is the weather outside?",
      "additional_kwargs": {},
      "response_metadata": {},
      "id": "a0514473-c615-4362-826e-92ec42a63884"
    },
    {
      "type": "AIMessage",
      "content": "",
      "additional_kwargs": {
        "refusal": null
      },
      "response_metadata": {
        "token_usage": {
          "completion_tokens": 12,
          "prompt_tokens": 224,
          "total_tokens": 236,
          "completion_tokens_details": {
            "accepted_prediction_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 0,
            "rejected_prediction_tokens": 0
          },
          "prompt_tokens_details": {
            "audio_tokens": 0,
            "cached_tokens": 0
          }
        },
        "model_provider": "openai",
        "model_name": "gpt-4o-mini-2024-07-18",
        "system_fingerprint": "fp_eb37e061ec",
        "id": "chatcmpl-DNYJbb2YC3bGBabU4cMChBtS8XzEB",
        "finish_reason": "tool_calls",
        "logprobs": null
      },
      "id": "lc_run--019d28c9-ddd4-7f83-9f16-b9a82cc51a0e-0",
      "tool_calls": [
        {
          "name": "get_user_location",
          "args": {},
          "id": "call_Yc265lCmfCTiSFb0ywzfbZeX",
          "type": "tool_call"
        }
      ],
      "invalid_tool_calls": [],
      "usage_metadata": {
        "input_tokens": 224,
        "output_tokens": 12,
        "total_tokens": 236,
        "input_token_details": {
          "audio": 0,
          "cache_read": 0
        },
        "output_token_details": {
          "audio": 0,
          "reasoning": 0
        }
      }
    },
    {
      "type": "ToolMessage",
      "content": "Shanghai",
      "name": "get_user_location",
      "id": "6eb3e154-d329-4497-aa2b-e6ea8803c91b",
      "tool_call_id": "call_Yc265lCmfCTiSFb0ywzfbZeX"
    },
    {
      "type": "AIMessage",
      "content": "",
      "additional_kwargs": {
        "refusal": null
      },
      "response_metadata": {
        "token_usage": {
          "completion_tokens": 17,
          "prompt_tokens": 244,
          "total_tokens": 261,
          "completion_tokens_details": {
            "accepted_prediction_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 0,
            "rejected_prediction_tokens": 0
          },
          "prompt_tokens_details": {
            "audio_tokens": 0,
            "cached_tokens": 0
          }
        },
        "model_provider": "openai",
        "model_name": "gpt-4o-mini",
        "system_fingerprint": "fp_eb37e061ec",
        "id": "chatcmpl-DNYJel8PrtJkiYfONkB1Le1TPWQuS",
        "finish_reason": "tool_calls",
        "logprobs": null
      },
      "id": "lc_run--019d28ca-1321-7231-a3b3-0ca73eb8e4a8-0",
      "tool_calls": [
        {
          "name": "get_weather_for_location",
          "args": {
            "city": "Shanghai"
          },
          "id": "call_DuMTODUFSuEZyeC6feJl1q8b",
          "type": "tool_call"
        }
      ],
      "invalid_tool_calls": [],
      "usage_metadata": {
        "input_tokens": 244,
        "output_tokens": 17,
        "total_tokens": 261,
        "input_token_details": {
          "audio": 0,
          "cache_read": 0
        },
        "output_token_details": {
          "audio": 0,
          "reasoning": 0
        }
      }
    },
    {
      "type": "ToolMessage",
      "content": "It's always rainy in Shanghai!",
      "name": "get_weather_for_location",
      "id": "131320f4-c2c5-4bba-b153-cfdc1a3d3a38",
      "tool_call_id": "call_DuMTODUFSuEZyeC6feJl1q8b"
    },
    {
      "type": "AIMessage",
      "content": "",
      "additional_kwargs": {
        "refusal": null
      },
      "response_metadata": {
        "token_usage": {
          "completion_tokens": 46,
          "prompt_tokens": 277,
          "total_tokens": 323,
          "completion_tokens_details": {
            "accepted_prediction_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 0,
            "rejected_prediction_tokens": 0
          },
          "prompt_tokens_details": {
            "audio_tokens": 0,
            "cached_tokens": 0
          }
        },
        "model_provider": "openai",
        "model_name": "gpt-4o-mini-2024-07-18",
        "system_fingerprint": "fp_eb37e061ec",
        "id": "chatcmpl-DNYJfkI8eMkpScdEUDH2VweZJ8j8J",
        "finish_reason": "tool_calls",
        "logprobs": null
      },
      "id": "lc_run--019d28ca-1b81-7e02-b17a-7cc074ac7645-0",
      "tool_calls": [
        {
          "name": "ResponseFormat",
          "args": {
            "weather_conditions": "多雨",
            "punny_response": "上海的天气真是让人\"水\"深火热，今天又是个\"下雨天\"！"
          },
          "id": "call_PzZ5A1CewBlCZFBO60f7AeXs",
          "type": "tool_call"
        }
      ],
      "invalid_tool_calls": [],
      "usage_metadata": {
        "input_tokens": 277,
        "output_tokens": 46,
        "total_tokens": 323,
        "input_token_details": {
          "audio": 0,
          "cache_read": 0
        },
        "output_token_details": {
          "audio": 0,
          "reasoning": 0
        }
      }
    },
    {
      "type": "ToolMessage",
      "content": "Returning structured response: punny_response='上海的天气真是让人\"水\"深火热，今天又是个\"下雨天\"！' weather_conditions='多雨'",
      "name": "ResponseFormat",
      "id": "dbdac10f-0c98-40d7-b688-1f69908b1136",
      "tool_call_id": "call_PzZ5A1CewBlCZFBO60f7AeXs"
    },
    {
      "type": "HumanMessage",
      "content": "thank you!",
      "additional_kwargs": {},
      "response_metadata": {},
      "id": "5b17ed89-3b4e-423f-a0f1-44fac7029215"
    },
    {
      "type": "AIMessage",
      "content": "",
      "additional_kwargs": {
        "refusal": null
      },
      "response_metadata": {
        "token_usage": {
          "completion_tokens": 45,
          "prompt_tokens": 375,
          "total_tokens": 420,
          "completion_tokens_details": {
            "accepted_prediction_tokens": 0,
            "audio_tokens": 0,
            "reasoning_tokens": 0,
            "rejected_prediction_tokens": 0
          },
          "prompt_tokens_details": {
            "audio_tokens": 0,
            "cached_tokens": 0
          }
        },
        "model_provider": "openai",
        "model_name": "gpt-4o-mini",
        "system_fingerprint": "fp_eb37e061ec",
        "id": "chatcmpl-DNYJhKUMQBmPsNDE56FyIE4yZ1fPY",
        "finish_reason": "tool_calls",
        "logprobs": null
      },
      "id": "lc_run--019d28ca-21e5-7812-86af-c7556b1cd64c-0",
      "tool_calls": [
        {
          "name": "ResponseFormat",
          "args": {
            "punny_response": "不客气，\"天气\"如人心，\"风\"云变幻！希望你有个\"晴\"朗的一天！"
          },
          "id": "call_OjxJ1IqfxM4zzzABiNUTwE1E",
          "type": "tool_call"
        }
      ],
      "invalid_tool_calls": [],
      "usage_metadata": {
        "input_tokens": 375,
        "output_tokens": 45,
        "total_tokens": 420,
        "input_token_details": {
          "audio": 0,
          "cache_read": 0
        },
        "output_token_details": {
          "audio": 0,
          "reasoning": 0
        }
      }
    },
    {
      "type": "ToolMessage",
      "content": "Returning structured response: punny_response='不客气，\"天气\"如人心，\"风\"云变幻！希望你有个\"晴\"朗的一天！' weather_conditions=None",
      "name": "ResponseFormat",
      "id": "0ed7a498-f2ae-4bee-8531-77181a3c51ee",
      "tool_call_id": "call_OjxJ1IqfxM4zzzABiNUTwE1E"
    }
  ],
  "structured_response": {
    "type": "ResponseFormat",
    "punny_response": "不客气，\"天气\"如人心，\"风\"云变幻！希望你有个\"晴\"朗的一天！",
    "weather_conditions": null
  }
}

好，其实一路看下来还是比较清晰的结果。注意几个点：

因为写了response_format=ToolStrategy(ResponseFormat)，所以LangChain为了拿到结构化输出，把这个schema包装成了类似工具调用的内部步骤。
打印response不只是本轮新增内容，而是整个thread的当前状态。我们发送了一个问天气的消息，又发送了一个thank you，最后会打印整个线程所有对话。
ResponseFormat里面的description，不仅仅是给人看的主食，也参与到模型结构化输出约束中。它跟system_prompt的起效层级不一样，约束力没那么强硬，算是进一步引导。

当然，我们可以指定字段，防止输出这么一长串有点傻的东西。我们用response['structured_response']

注意到这里其实有个警告，“正在从 checkpoint 反序列化一个未注册的类型 __main__.ResponseFormat。”，未来的版本或许不允许这样用。意思是如果确认这个类型是安全且允许回复，要加入 allowed_msgpack_modules 白名单。

消除这个警告的方法也很简单，将ResponseFormat放大单独的模块中，比如就叫schemas.py，然后再导包进来，这样就不是__main__.ResponseFormat而是schemas.ResponseFormat了。

5. 设计哲学

在此界面提了一下，我这里简单概述一下。

这一页不是在教具体 API 怎么写，而是在解释 LangChain 想成为什么样的框架，以及它为什么这样设计。

官方的核心意思可以概括为：LangChain 想成为“构建带上下文能力和推理能力的应用的最简单方式”。这里说的不是只调用一次模型，而是构建完整应用，让模型能读上下文、调工具、输出结构化结果，并在真实项目中持续运行。

(1) 从简单开始，但可以扩展到复杂应用

LangChain 希望开发者一开始就能用很少的代码搭起一个能运行的 agent 或 LLM 应用，而不是先学习大量底层细节。但它又不想只适合 demo，因此同一套框架要能继续扩展到更复杂的生产场景。

我的理解是：

入门时可以先用高层封装快速起步
后面需求变复杂时，不需要整套推倒重来
可以逐步加入工具、结构化输出、记忆、检索和工作流

(2) 提供高层抽象，但不要把开发者困在黑盒里

LangChain 的哲学不是“把一切都藏起来”，而是默认给你高层接口来提升开发效率，同时保留足够的可控性。

所以它的思路通常是：

常见任务给出简单接口
复杂需求允许向下深入
当高层抽象不够时，可以转向 LangGraph 做更细粒度的编排

也就是说，LangChain 追求的是“默认简单，但不牺牲控制力”。

(3) 设计重点是现实中的 agent 应用

LangChain 关注的不是孤立的一次 prompt 调用，而是一个真实 AI 应用从输入到输出的完整过程。例如：

如何连接不同模型提供商
如何让模型调用工具
如何管理上下文
如何拿到结构化输出
如何调试和观测 agent 的行为

因此它很多设计都围绕“让 agent 应用真正可用”展开，而不是只服务于演示性质的 prompt 实验。

(4) 尽量与具体模型提供商解耦

LangChain 希望应用逻辑不要被某一家模型提供商强绑定。也就是说，如果底层模型从 OpenAI 换成 Anthropic、Google 等，开发者最好还能保留大部分上层逻辑。

这也是为什么文档里会不断强调：

统一的模型初始化方式
统一的消息接口
统一的工具调用模式

它想减少“换模型就重写程序”的成本。

(5) 重视生产可用性，而不只是能跑

LangChain 的目标不是“代码能执行一次就行”，而是希望它能走向真实项目。所以它会特别重视：

tracing
observability
debugging
structured output
与 LangSmith / LangGraph 的协作

也就是说，一个应用不仅要能回答问题，还应该能被追踪、分析、调试和维护。

(6) LangChain 和 LangGraph 的关系

从设计哲学上看，LangChain 更偏向“让构建 agent 更容易”，而 LangGraph 更偏向“提供底层运行时和编排能力”。

可以这样理解：

LangChain：高层、上手快、常见场景更省心
LangGraph：底层、可控性更强、适合复杂流程

所以官方常见的建议是：先从 LangChain 入门，当需求需要更复杂的控制时，再下沉到 LangGraph。

(7) 我的总结

这页 Philosophy 本质上是在告诉读者：

LangChain 不只是模型调用封装
它更像一个 AI 应用框架
它强调易用性，但不想把开发者锁死在黑盒里
它的很多抽象，都是为了让应用可以从 demo 平滑过渡到真实项目

LangGraph 应用思路 01：从流程到 Agent 架构

Fri, 27 Mar 2026 00:00:00 GMT

用LangGraph构建Agent的思路

本章提供一种构建自己Agent的一种思路入手

1. 从想要的自动化流程入手

例如，你需要构建一个用于处理客户支持邮件的 AI 智能体。产品团队向你提出了以下需求：

The agent should:

- Read incoming customer emails
- Classify them by urgency and topic
- Search relevant documentation to answer questions
- Draft appropriate responses
- Escalate complex issues to human agents
- Schedule follow-ups when needed

Example scenarios to handle:

1. Simple product question: "How do I reset my password?"
2. Bug report: "The export feature crashes when I select PDF format"
3. Urgent billing issue: "I was charged twice for my subscription!"
4. Feature request: "Can you add dark mode to the mobile app?"
5. Complex technical issue: "Our API integration fails intermittently with 504 errors"

2. 拆解为独立步骤

首先明确流程中的各个独立步骤，每个步骤将成为一个节点（执行单一具体功能的函数）。然后勾勒出这些步骤之间的连接关系。

此图表中的箭头表示可能的路径，但具体选择哪条路径的决策在每个节点内部完成。既然我们已经确定了工作流中的各个组件，接下来了解每个节点需要执行的操作：

Read Email：提取并解析邮件内容
Classify Intent：使用大语言模型对紧急程度和主题进行分类，然后路由至相应操作
Doc Search：在知识库中查询相关信息
Bug Track：在跟踪系统中创建或更新问题
Draft Reply：生成合适的回复内容
Human Review：转交人工坐席进行审批或处理
Send Reply：发送邮件回复

3. 每一步要做什么

为图中的每个节点，确定其代表的操作类型以及正常运行所需的上下文信息。

LLM steps：当某一步骤需要理解、分析、生成文本或进行推理决策时
Data steps：当某个步骤需要从外部来源获取信息时
Action steps：当某个步骤需要执行外部操作时
User input steps：当某个步骤需要人工介入时

4. 设计state

state是智能体中所有节点均可访问的共享存储器。可将其视作智能体在执行任务过程中，用于记录所有学习内容与决策信息的笔记本。这是非常重要的信息。

我们要问自己两个问题：

它是否需要在多个步骤间持续存在？如果是，就放入状态中。
能否从其他数据推导得出？如果可以，在需要时计算即可，不必存入状态。

5. 建立节点

现在我们将每个步骤实现为一个函数。LangGraph 中的节点只是一个 Python 函数，它接收当前状态并返回对状态的更新。

(1) 错误处理

错误类型	由谁修复	处理策略	适用场景
瞬时错误（网络问题、限流等）	系统自动处理	重试策略（retry policy）	这类失败通常是临时性的，重试后大概率恢复
LLM 可恢复错误（工具调用失败、解析失败等）	LLM	把错误写入 state，再回到模型节点重试	模型能够看到错误信息，并据此调整下一步做法
用户可修复错误（信息缺失、指令不清）	人类用户	使用 `interrupt()` 暂停	必须等待用户补充信息后才能继续
非预期错误	开发者	直接向上抛出异常	未知问题，需要调试和排查根因

(2) 实现节点

写node本身。

6. 建图

将节点连接成一个可运行的图结构。由于各个节点会自行处理路由决策，我们只需要几条核心的边即可。

7. 测试

测试、总结、升级。

PyTorch CNN：从 LeNet 到经典卷积架构

Fri, 27 Mar 2026 00:00:00 GMT

这一篇主要整理自 liuer_pytorch/11-13.ipynb，以及 pytorch_learning/pytorch_6.py。这组材料最适合的读法，不是逐个背模型名字，而是先把卷积网络的核心骨架理解清楚。

1. 为什么 CNN 适合图像

和全连接网络相比，卷积网络的关键优势在于：

局部感受野：先看局部
权重共享：同一个卷积核在不同位置复用
参数更少：不会像全连接层那样一上来就爆炸

课程笔记里反复强调的一点是：
卷积层不是“更复杂的线性层”，而是一种刻意保留空间结构的线性变换。

2. LeNet 是理解 CNN 的最好起点

我自己在 pytorch_learning/pytorch_6.py 里第一次完整写了一个 LeNet：

class LeNet(nn.Module):
    def __init__(self):
        super().__init__()
        self.conv1 = nn.Conv2d(1, 6, 5)
        self.conv2 = nn.Conv2d(6, 16, 5)
        self.fc1 = nn.Linear(16 * 5 * 5, 120)
        self.fc2 = nn.Linear(120, 84)
        self.fc3 = nn.Linear(84, 10)

    def forward(self, x):
        x = F.max_pool2d(F.relu(self.conv1(x)), (2, 2))
        x = F.max_pool2d(F.relu(self.conv2(x)), (2, 2))
        x = x.view(x.size(0), -1)
        x = F.relu(self.fc1(x))
        x = F.relu(self.fc2(x))
        return self.fc3(x)

这段代码几乎把经典 CNN 的主干全露出来了：

卷积
激活
池化
展平
全连接分类头

LeNet 结构图我也一起保留到了博客目录里：

3. 读 LeNet 时最该记住什么

我现在看 LeNet，最重要的不是记参数，而是记住这条流：

输入图像
→ 卷积提取局部特征
→ 池化压缩空间尺寸
→ 再卷积、再池化
→ 展平后送入全连接层
→ 输出类别分数

这条流后来几乎影响了所有经典 CNN，只是中间模块变复杂了。

4. 从 LeNet 往后看：为什么网络越做越深

课程在 Advanced CNN 那几节里，重点提到了三条线：

4.1 GoogLeNet / Inception

核心思路是：
不要只押注一种卷积核大小，而是在同一层里并行做多种卷积，再把结果拼起来。

它解决的是“同一层特征尺度可能不一样”的问题。

4.2 ResNet

ResNet 最关键的点，是残差连接。

它不是在说“网络一定要有捷径才厉害”，而是在解决一个更工程的问题：

网络越深，训练越难
信息和梯度传得越来越差
残差连接让模型更容易学到“至少别变坏”

4.3 DenseNet

DenseNet 可以看成把“连接”这件事推得更极端：

前面层的特征不只残差相加
而是更密集地往后传

课程里还顺手把它当成了一个“参考论文自己实现网络”的练习入口，这其实很对。

5. CNN 这一阶段该怎么学

我现在觉得最适合的顺序是：

先把卷积、池化和 feature map 形状变化看懂
再把 LeNet 写出来
再去理解 GoogLeNet / ResNet / DenseNet 解决的具体问题

不要一上来就被各种大模型名字压住。

6. 这一阶段该记住什么

如果只保留最少的几句话，我会记：

CNN 的核心不是“更深”，而是“保留空间结构的局部特征提取”。
LeNet 是最好的起点，因为它把卷积网络的主干完整展示出来了。
GoogLeNet、ResNet、DenseNet 分别在解决不同的“怎么把 CNN 做得更强”的问题。

到这里，PyTorch 已经不只是“会写训练循环”，而是开始真正进入深度学习模型结构本身了。

RAG 文本分块：为什么切、怎么切、怎么权衡

Fri, 27 Mar 2026 00:00:00 GMT

分块是 RAG 里最容易“看起来简单、实际上很关键”的步骤。这里把块大小、重叠与几种典型分块策略整理到一起，方便后面搭索引时直接回看。

RAG - 文本分块

一、理解文本分块

文本分块（Text Chunking）是构建 RAG 流程的关键步骤。它的原理是将加载后的长篇文档，切分成更小、更易于处理的单元。这些被切分出的文本块，是后续向量检索和模型处理的基本单位。

二、文本分块的重要性

1. 上下文限制

将文本分块的首要原因，是为了适应 RAG 系统中两个核心组件的硬性限制：

嵌入模型 (Embedding Model): 负责将文本块转换为向量。这类模型有严格的输入长度上限。例如，许多常用的嵌入模型（如 bge-base-zh-v1.5）的上下文窗口为512个token。任何超出此限制的文本块在输入时都会被截断，导致信息丢失，生成的向量也无法完整代表原文的语义。因此，文本块的大小必须小于等于嵌入模型的上下文窗口。
大语言模型 (LLM): 负责根据检索到的上下文生成答案。LLM同样有上下文窗口限制（尽管通常比嵌入模型大得多，从几千到上百万token不等）。检索到的所有文本块，连同用户问题和提示词，都必须能被放入这个窗口中。如果单个块过大，可能会导致只能容纳少数几个相关的块，限制了LLM回答问题时可参考的信息广度。

因此，分块是确保文本能够被两个模型完整、有效处理的基础。

2. 块大小的trade-off

块大小	优势	劣势	对 RAG 的影响
大块	上下文更完整，保留更多原文细节，适合需要整体语境的信息	嵌入时信息被压缩得更严重，主题容易稀释，检索不够精准；生成时也容易出现“大海捞针”	召回可能不稳定，噪声较多，回答容易遗漏关键点
中等块	在上下文完整性和语义聚焦之间取得平衡	仍可能混入少量无关信息，需要结合重叠策略优化	通常是实践中最常用、效果最稳妥的选择
小块	主题集中，语义清晰，检索匹配更精准，信噪比更高	上下文可能不足，容易丢失前后关联，回答时可能缺背景	召回更精确，但可能需要检索多个块拼接上下文
过小的块	对单一知识点定位非常强	语义过于碎片化，信息不完整，容易失去独立表达能力	检索结果零散，增加后续整合和生成难度

三、基础分块策略

LangChain提供了丰富且易用的文本分割器 (Text Splitters)。

1. 固定大小分块 (CharacterTextSplitter)

这是最简单直接的分块方法。根据LangChain源码，这种方法的工作原理分为两个主要阶段：

（1）按段落分割：CharacterTextSplitter 采用默认分隔符 "\n\n"，使用正则表达式将文本按段落进行分割，通过 _split_text_with_regex 函数处理。

（2）智能合并：调用继承自父类的 _merge_splits 方法，将分割后的段落依次合并。该方法会监控累积长度，当超过 chunk_size 时形成新块，并通过重叠机制（chunk_overlap）保持上下文连续性，同时在必要时发出超长块的警告。

需要注意，CharacterTextSplitter 实际实现的并非严格的固定大小分块。根据 _merge_splits 源码逻辑，这种方法会：

优先保持段落完整性：只有当添加新段落会导致总长度超过 chunk_size 时，才会结束当前块
处理超长段落：如果单个段落超过 chunk_size，系统会发出警告但仍将其作为完整块保留
应用重叠机制：通过 chunk_overlap 参数在块之间保持内容重叠，确保上下文连续性

所以，LangChain 的实现更准确地应该称为"段落感知的自适应分块"，块大小会根据段落边界动态调整。

接下来我们配置一各固定大小分块器：

from langchain.text_splitter import CharacterTextSplitter
from langchain_community.document_loaders import TextLoader

loader = TextLoader("../../data/C2/txt/蜂医.txt")
docs = loader.load()

text_splitter = CharacterTextSplitter(
    chunk_size=200,    # 每个块的目标大小为100个字符
    chunk_overlap=10   # 每个块之间重叠10个字符，以缓解语义割裂
)

chunks = text_splitter.split_documents(docs)

print(f"文本被切分为 {len(chunks)} 个块。\n")
print("--- 前5个块内容示例 ---")
for i, chunk in enumerate(chunks[:5]):
    print("=" * 60)
    # chunk 是一个 Document 对象，需要访问它的 .page_content 属性来获取文本
    print(f'块 {i+1} (长度: {len(chunk.page_content)}): "{chunk.page_content}"')

这种方法的主要优势在于实现简单、处理速度快且计算开销小。劣势在于可能会在语义边界处切断文本，影响内容的完整性和连贯性。实际的固定大小分块实现（如LangChain的 CharacterTextSplitter）通常会结合分隔符来减少这种问题，在段落边界处优先切分，只有在必要时才会强制按大小切断。因此，这种方法在日志分析、数据预处理等场景中仍有其应用价值。

2. 递归字符分块 (RecursiveCharacterTextSplitter)

这种分块器通过分隔符层级递归处理，相对与固定大小分块，改善了超长文本的处理效果。

算法流程：

寻找有效分隔符: 从分隔符列表中从前到后遍历，找到第一个在当前文本中存在的分隔符。如果都不存在，使用最后一个分隔符（通常是空字符串 ""）。
切分与分类处理: 使用选定的分隔符切分文本，然后遍历所有片段：

如果片段不超过块大小: 暂存到 _good_splits 中，准备合并
如果片段超过块大小:
- 首先，将暂存的合格片段通过 _merge_splits 合并成块
- 然后，检查是否还有剩余分隔符：
  - 有剩余分隔符: 递归调用 _split_text 继续分割
  - 无剩余分隔符: 直接保留为超长块

最终处理: 将剩余的暂存片段合并成最后的块

实现细节：

批处理机制: 先收集所有合格片段（_good_splits），遇到超长片段时才触发合并操作。
递归终止条件: 关键在于 if not new_separators 判断。当分隔符用尽时（new_separators 为空），停止递归，直接保留超长片段。确保算法不会无限递归。

与固定大小分块的关键差异：

固定大小分块遇到超长段落时只能发出警告并保留。
递归分块会继续使用更细粒度的分隔符（句子→单词→字符）直到满足大小要求。

from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_community.document_loaders import TextLoader

loader = TextLoader("../../data/C2/txt/蜂医.txt")
docs = loader.load()

text_splitter = RecursiveCharacterTextSplitter(
    separators=["\n\n", "\n", "。", "，", " ", ""],  # 分隔符优先级
    chunk_size=200,
    chunk_overlap=10,
)

chunks = text_splitter.split_text(docs)

直觉上来看切的更碎了，总块数更多。这里默认的分隔符优先级也就是上文代码的separators，可以自己调整，默认是["\n\n", "\n", " ", ""]，对于无词边界语言可以添加：

separators=[
    "\n\n", "\n", " ",
    ".", ",", "\u200b",      # 零宽空格(泰文、日文)
    "\uff0c", "\u3001",      # 全角逗号、表意逗号
    "\uff0e", "\u3002",      # 全角句号、表意句号
    ""
]

另外，还可以针对特定编程语言（如Python，Java等）使用预设的、更符合代码结构的分隔符。它们通常包含语言的顶级语法结构（如类、函数定义）和次级结构（如控制流语句），以实现更符合代码逻辑的分割。

# 针对代码文档的优化分隔符
splitter = RecursiveCharacterTextSplitter.from_language(
    language=Language.PYTHON,  # 支持Python、Java、C++等
    chunk_size=500,
    chunk_overlap=50
)

递归字符分块的原理是采用一组有层次结构的分隔符（如段落、句子、单词）进行递归分割，旨在有效平衡语义完整性与块大小控制。在 RecursiveCharacterTextSplitter 的实现中，该分块器首先尝试使用最高优先级的分隔符（如段落标记）来切分文本。如果切分后的块仍然过大，会继续对这个大块应用下一优先级分隔符（如句号），如此循环往复，直到块满足大小限制。这种分层处理的机制，能够在尽可能保持高级语义结构完整性的同时，有效控制块大小。

3. 语义分块 (Semantic Chunking)

语义分块（Semantic Chunking）是一种更智能的方法，这种方法不依赖于固定的字符数或预设的分隔符，而是尝试根据文本的语义内涵来切分。其核心是：在语义主题发生显著变化的地方进行切分。这使得每个分块都具有高度的内部语义一致性。LangChain 提供了 langchain_experimental.text_splitter.SemanticChunker 来实现这一功能。

(1) 实现原理

SemanticChunker 的工作流程可以概括为以下几个步骤：

句子分割 (Sentence Splitting)：首先，使用标准的句子分割规则（例如，基于句号、问号、感叹号）将输入文本拆分成一个句子列表。
上下文感知嵌入 (Context-Aware Embedding)：这是 SemanticChunker 的一个关键设计。该分块器不是对每个句子独立进行嵌入，而是通过 buffer_size 参数（默认为1）来捕捉上下文信息。对于列表中的每一个句子，这种方法会将其与前后各 buffer_size 个句子组合起来，然后对这个临时的、更长的组合文本进行嵌入。这样，每个句子最终得到的嵌入向量就融入了其上下文的语义。
计算语义距离 (Distance Calculation)：计算每对相邻句子的嵌入向量之间的余弦距离。这个距离值量化了两个句子之间的语义差异——距离越大，表示语义关联越弱，跳跃越明显。
识别断点 (Breakpoint Identification)：SemanticChunker 会分析所有计算出的距离值，并根据一个统计方法（默认为 percentile）来确定一个动态阈值。例如，它可能会将所有距离中第95百分位的值作为切分阈值。所有距离大于此阈值的点，都被识别为语义上的“断点”。
合并成块 (Merging into Chunks)：最后，根据识别出的所有断点位置，将原始的句子序列进行切分，并将每个切分后的部分内的所有句子合并起来，形成一个最终的、语义连贯的文本块。

(2) 断点识别方法 (breakpoint_threshold_type)

如何定义“显著的语义跳跃”是语义分块的关键。SemanticChunker 提供了几种基于统计的方法来识别断点：

percentile (百分位法 - 默认方法):
- 逻辑: 计算所有相邻句子的语义差异值，并将这些差异值进行排序。当一个差异值超过某个百分位阈值时，就认为该差异值是一个断点。
- 参数: breakpoint_threshold_amount (默认为 95)，表示使用第95个百分位作为阈值。这意味着，只有最显著的5%的语义差异点会被选为切分点。
standard_deviation (标准差法):
- 逻辑: 计算所有差异值的平均值和标准差。当一个差异值超过“平均值 + N * 标准差”时，被视为异常高的跳跃，即断点。
- 参数: breakpoint_threshold_amount (默认为 3)，表示使用3倍标准差作为阈值。
interquartile (四分位距法):
- 逻辑: 使用统计学中的四分位距（IQR）来识别异常值。当一个差异值超过 Q3 + N * IQR 时，被视为断点。
- 参数: breakpoint_threshold_amount (默认为 1.5)，表示使用1.5倍的IQR。
gradient (梯度法):
- 逻辑: 这是一种更复杂的方法。它首先计算差异值的变化率（梯度），然后对梯度应用百分位法。对于那些句子间语义联系紧密、差异值普遍较低的文本（如法律、医疗文档）特别有效，因为这种方法能更好地捕捉到语义变化的“拐点”。
- 参数: breakpoint_threshold_amount (默认为 95)。

稍微总结一下几个断点的优缺点，一般优先使用percentile就行了，默认切分效果不好时，再尝试gradient或更鲁棒的interquartile。

方法	核心思路	优点	缺点	适用场景
`percentile`	把句子间语义距离排序，超过某个百分位就切分	简单直观，默认方法，通用性强	对不同文档分布适应性一般，阈值偏经验化	通用文本、入门默认选择
`standard_deviation`	超过“均值 + N 倍标准差”视为断点	能识别明显异常的语义跳跃	对分布敏感，若数据波动不稳定，切分效果可能不稳	语义跳跃较明显的普通文本
`interquartile`	用四分位距识别异常值，超过阈值就切分	比标准差法更抗极端值干扰，鲁棒性更好	理解门槛稍高，参数不如百分位法直观	噪声较多、分布不均匀的文本
`gradient`	关注语义距离变化率，在“变化拐点”处切分	更擅长捕捉细微主题转折，对语义连续文本更敏感	计算和理解都更复杂，调参成本更高	法律、医疗、学术等语义连续但局部变化重要的文本

import os
## os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
from langchain_experimental.text_splitter import SemanticChunker
from langchain_community.embeddings import HuggingFaceEmbeddings
from langchain_community.document_loaders import TextLoader

embeddings = HuggingFaceEmbeddings(
    model_name="BAAI/bge-small-zh-v1.5",
    model_kwargs={'device': 'cpu'},
    encode_kwargs={'normalize_embeddings': True}
)

# 初始化 SemanticChunker
text_splitter = SemanticChunker(
    embeddings,
    breakpoint_threshold_type="percentile" # 断点识别方法
)

loader = TextLoader("../../data/C2/txt/蜂医.txt")
documents = loader.load()

docs = text_splitter.split_documents(documents)

语义分块当然就都需要嵌入模型了，它是预训练之后的，知道将语义相近的句子嵌入后的高维向量拉进、不同的句子拉远。嵌入的过程大概就是分词、查表（查词表对应到id，然后查预训练好的嵌入表得初始向量）、加位置信息、Transformer编码、池化压缩成句子向量、归一。

flowchart LR
    subgraph T["训练嵌入模型"]
        direction TB
        T0["训练样本<br/>Query / Positive / Negative"]
        T1["Tokenizer / 词表<br/>文本 -> token ids"]
        T2["Embedding Table 查表<br/>token id -> 初始 token 向量"]
        T3["位置编码<br/>加入位置信息"]
        T4["Transformer Encoder<br/>让 token 融合上下文"]
        T5["Pooling / Projection<br/>token 向量 -> 句向量"]
        T6["得到句向量<br/>q / pos / neg"]
        T7["计算相似度<br/>sim(q,pos), sim(q,neg)"]
        T8["训练目标<br/>让 q 更接近 pos<br/>让 q 更远离 neg"]
        T9["Loss"]
        T10["反向传播"]
        T11["更新参数<br/>Embedding Table<br/>Encoder<br/>Projection"]

        T0 --> T1 --> T2 --> T3 --> T4 --> T5 --> T6 --> T7 --> T8 --> T9 --> T10 --> T11
    end

    M["训练好的嵌入模型参数<br/>Embedding Table + Encoder + Projection"]

    T11 --> M

    subgraph U["使用嵌入模型"]
        direction TB
        U0["新文本<br/>用户问题 / 文档块"]
        U1["同一个 Tokenizer / 词表"]
        U2["查训练好的 Embedding Table<br/>得到初始 token 向量"]
        U3["位置编码"]
        U4["经过训练好的 Encoder<br/>融合上下文"]
        U5["Pooling / Projection"]
        U6["最终句向量"]
        U7["相似度计算 / 向量检索 / 入库"]

        U0 --> U1 --> U2 --> U3 --> U4 --> U5 --> U6 --> U7
    end

    M -. 提供固定参数 .-> U2
    M -. 提供固定参数 .-> U4
    M -. 提供固定参数 .-> U5

4. 基于文档结构的分块

对于具有明确结构标记的文档格式（如Markdown、HTML、LaTex），可以利用这些标记来实现更智能、更符合逻辑的分割。

以 Markdown 结构分块为例针对结构清晰的 Markdown 文档，利用其标题层级进行分块是一种高效且保留了丰富语义的方法。LangChain 提供了 MarkdownHeaderTextSplitter 来处理。

实现原理: 该分块器的主要逻辑是“先按标题分组，再按需细分”。
1. 定义分割规则: 用户首先需要提供一个标题层级的映射关系，例如 [ ("#", "Header 1"), ("##", "Header 2") ]，告诉分块器 # 是一级标题，## 是二级标题。
2. 内容聚合: 分块器会遍历整个文档，将每个标题下的所有内容（直到下一个同级或更高级别的标题出现前）聚合在一起。每个聚合后的内容块都会被赋予一个包含其完整标题路径的元数据。
元数据注入的优势: 这是此方法的主要特点。例如，对于一篇关于机器学习的文章，某个段落可能位于“第三章：模型评估”下的“3.2节：评估指标”中。经过分割后，这个段落形成的文本块，其元数据就会是 {"Header 1": "第三章：模型评估", "Header 2": "3.2节：评估指标"}。这种元数据为每个块提供了精确的“地址”，极大地增强了上下文的准确性，让大模型能更好地理解信息片段的来源和背景。
局限性与组合使用: 单纯按标题分割可能会导致一个问题：某个章节下的内容可能非常长，远超模型能处理的上下文窗口。为了解决这个问题，MarkdownHeaderTextSplitter 可以与其它分块器（如 RecursiveCharacterTextSplitter）组合使用。具体流程是：
- 第一步，使用 MarkdownHeaderTextSplitter 将文档按标题分割成若干个大的、带有元数据的逻辑块。
- 第二步，对这些逻辑块再应用 RecursiveCharacterTextSplitter，将其进一步切分为符合 chunk_size 要求的小块。由于这个过程是在第一步之后进行的，所有最终生成的小块都会继承来自第一步的标题元数据。
RAG应用优势: 这种两阶段的分块方法，既保留了文档的宏观逻辑结构（通过元数据），又确保了每个块的大小适中，是处理结构化文档进行RAG的理想方案。

四、其他开源框架中的分块策略

这后面简单瞅一下，Unstructrured前面也用过了。

1. Unstructured：基于文档元素的智能分块

Unstructured是一个强大的文档处理工具，同样提供了实用的分块功能。

（1）分区 (Partitioning): 这是一个重要功能，负责将原始文档（如PDF、HTML）解析成一系列结构化的“元素”（Elements）。每个元素都带有语义标签，如 Title (标题)、NarrativeText (叙述文本)、ListItem (列表项) 等。这个过程本身就完成了对文档的深度理解和结构化。

（2）分块 (Chunking): 该功能建立在分区的结果之上。分块功能不是对纯文本进行操作，而是将分区产生的“元素”列表作为输入，进行智能组合。Unstructured 提供了两种主要的分块方法：

basic: 这是默认方法。这种方法会连续地组合文档元素（如段落、列表项），直到达到 max_characters 上限，尽可能地填满每个块。如果单个元素超过上限，则会对其进行文本分割。
by_title: 该方法在 basic 方法的基础上，增加了对“章节”的感知。该方法将 Title 元素视为一个新章节的开始，并强制在此处开始一个新的块，确保同一个块内不会包含来自不同章节的内容。这在处理报告、书籍等结构化文档时非常有用，效果类似于 LangChain 的 MarkdownHeaderTextSplitter，但适用范围更广。 Unstructured 允许将分块作为分区的一个参数在单次调用中完成，也支持在分区之后作为一个独立的步骤来执行分块。这种“先理解、后分割”的策略，使得 Unstructured 能在最大程度上保留文档的原始语义结构，特别是在处理版式复杂的文档时，优势尤为明显。

2. LlamaIndex：面向节点的解析与转换

LlamaIndex 将数据处理流程抽象为对“节点（Node）”的操作。文档被加载后，首先会被解析成一系列的“节点”，分块只是节点转换（Transformation）中的一环。

LlamaIndex 的分块体系有以下特点：

（1）丰富的节点解析器 (Node Parser): LlamaIndex 提供了大量针对特定数据格式和方法的节点解析器，可以大致分为几类：

结构感知型: 如 MarkdownNodeParser, JSONNodeParser, CodeSplitter 等，能理解并根据源文件的结构（如Markdown标题、代码函数）进行切分。
语义感知型:
- SemanticSplitterNodeParser: 与 LangChain 的 SemanticChunker 类似，这种解析器使用嵌入模型来检测句子之间的语义“断点”，在语义连续性明显减弱的地方切开，从而让每个 chunk 内部尽量连贯。
- SentenceWindowNodeParser: 这是一种巧妙的方法。该方法将文档切分成单个的句子，但在每个句子节点（Node）的元数据中，会存储其前后相邻的N个句子（即“窗口”）。这使得在检索时，可以先用单个句子的嵌入进行精确匹配，然后将包含上下文“窗口”的完整文本送给LLM，极大地提升了上下文的质量。
常规型: 如 TokenTextSplitter, SentenceSplitter 等，提供基于Token数量或句子边界的常规切分方法。

（2）灵活的转换流水线: 用户可以构建一个灵活的流水线，例如先用 MarkdownNodeParser 按章节切分文档，再对每个章节节点应用 SentenceSplitter 进行更细粒度的句子级切分。每个节点都携带丰富的元数据，记录着其来源和上下文关系。

（3）良好的互操作性: LlamaIndex 提供了 LangchainNodeParser，可以方便地将任何 LangChain 的 TextSplitter 封装成 LlamaIndex 的节点解析器，无缝集成到其处理流程中。

3. ChunkViz：简易的可视化分块工具

在本文开头部分展示的分块图就是通过 ChunkViz 生成的。可以将你的文档、分块配置作为输入，用不同的颜色块展示每个 chunk 的边界和重叠部分，方便快速理解分块逻辑。

Actor-Critic 主线：优势函数、GAE、TRPO 与 PPO

Fri, 27 Mar 2026 00:00:00 GMT

现在, 我们解决了最后的难题, value-based 2 policy-based, 让智能体真正地去学习有概率的策略, 关于这一点的必要性已经在个笔记开篇举例说明. 需要注意的是, Policy-based算法并非承接了笔记1-3的进化过程, 而是从另一个道路开始, 所以笔记4中介绍的算法作为开山鼻祖但是效果很差、局限很多. 所以我们要吸收value-based中的优势, 这就是今天的主题Actor-Critic框架.

前面从表格型方法一路推进到策略梯度之后，这一篇开始把 critic 重新请回来。也正是从这里起，强化学习真正进入现代工程里最常见的 Actor-Critic 主线。

一. 把Q值请回来

REINFORCE算法实际上遇到了两个问题:

方差太大. 因为是对每条轨迹的真实回报进行计算, 并不进行估算, 这是无偏性的必然结果. 在强化学习中, 偏差和方差是一个在权衡的过程.Reinforce没有偏差, 但是方差太大. 反观Q-learning和DQN都不是无偏的, 因为Q-learning是猜未来的Q值, 是不准确的; 而DQN本来就有偏差. 所以这两者方差都不会大.
要等到一个episode之后才能更新. 这还要求任务是有限步的.

如果回忆之前的内容, 我们就可以想到当时是从采样的MC方法, 进化到了单步更新的TD方法(默认TD(0)), 来达成不走完一条完整的轨迹也能更新Q的目的. 所以, 在策略梯度算法中, 我们同样可以借鉴类似的思路, 将回报替换成Q值来更新. 这样一来, 我们就可以用前面提到过的TD的方法来更新Q, 而不用等到整个trajectory采样完成. $$ \nabla \overline{R}{ \theta} \approx \frac{1}{N} \sum{n=1}^{N} \sum_{t=1}^{T_{n}}Q^{n} \left( s_{t}^{n},a_{t}^{n} \right) \nabla \log \pi_{ \theta} \left( a_{t}^{n}|s_{t}^{n} \right) \tag{1.1} $$ 我们会发现, 这样策略梯度算法的公式中, 引入回来了Q的部分, 也就是说将value-based的部分又带了回来, 并利用其优势为policy-based提供价值. 这种将Policy-based和Value-based结合的算法, 我们就称之为Actor-Critic算法. 其中, Critic网络负责得到Q值, 而Actor网络负责进行梯度策略的更新.

需要注意的是, 只要是将策略和价值相结合的方法, 我们就可以叫做是Actor- Critic算法. 也就是说除了“三”下面的, DDPG、PPO、TRPO、GRPO等也都属于AC框架, 只不过由于有些过于出名, 故单独拿出来介绍.

二. 优势函数

1. 定义

笔记4中, 我们介绍策略梯度的实现技巧时, 将G减去了一个基线b. 作用已经在那里详细举例阐述, 并且那里的一个可能的b就是采样总奖励的均值. 我们在那里提了一嘴, 这 ( REINFORCE with baseline )就是优势函数的雏形. 广义的优势函数, 就是用于衡量“这个动作比平均好多少“的量. 但是由于时A2C中第一次明确使用了优势函数 (Advantage Function) 的说法, 并且其中使用的基线为V(s), 所以狭义上来说, 优势函数的数学定义为: $$ A(s,a)=Q(s,a)-V(s) \tag{2.1.1} $$ 优势函数无疑是AC框架的核心. 但是其中的“优势”在不同算法中有不同的表示. 或者说, 不同算法实际上就是对这个优势函数进行了不同的定义/优化.

2. Generalized Advantage Estimation (GAE)

上式中的Q和V都是老朋友了, 在之前的笔记中我们对如何估计他们做了详细的学习, 包括DP、MC、TD等. 早期算法如QAC、A2C、A3C都是通过简单的TD(0)或者n步回报来估计优势函数, 就如同之前的value-based一样.

GAE是策略梯度算法中用于估计优势函数的一种高级技巧, 它提供了一种实用的估计方法来计算优势函数. 我们可以在这里将估计优势函数的方法进行对比总结.

估计方法	公式	特点
蒙特卡洛 (MC)	$A_t = \sum_{k=0}^∞ γ^k r_{t+k} - V(s_t)$	无偏估计, 但是高方差
TD(0)	$A_t = r_t + γV(s_{t+1}) - V(s_t)$	低方差, 但是有偏估计
TD(n)	$A_t = \sum_{k=0}^{n-1} γ^k r_{t+k} + γ^n V(s_{t+n}) - V(s_t)$	折中方案
GAE	$A_t^{GAE} = \sum_{l=0}^∞ (γλ)^l δ_{t+l}$	自适应均衡
怎么得到GAE, 我们现在将经典TD算法的式子展开, 来表示t时刻往前看k个step的情况下, 对当前形式的估计:
$$
A^{k}(t)=r_{t}+\gamma r_{t+1}+\gamma^{2}r_{t+2}+\cdot\cdot\cdot+\gamma^{k-1}r_ {t+k-1}+\gamma^{k}V(s_{t+k})-V(s_{t}) \tag{2.2.1}
$$
凡事都有两面性, 对于$A^{k}(t)$ 来说, k越大意味着观测值越多, 估计值越少, 那么偏差越小, 方差越大; 反之, 观测值越少, 估计值越多, 偏差越大, 方差越小. 所以为了trade-off偏差和方差, GAE考虑对原始的$A^{k}(t)$ 进行修改, 与估计奖励时的思想类似, 我们在估计优势函数时, 也综合考虑不同step的估计值, 于是可以对不同的$A^{k}(t)$ 加权求和:
$$
\begin{split} A_{t}^{\textit{GAE}{1}}&=A{t}^{1}+ \lambda A_{t}^{2}+\lambda^{2}A_{t}^{3}+\cdot\cdot\cdot\ &=\delta_{t}+\lambda(\delta_{t}+\gamma\delta_{t+1})+\lambda^{2}( \delta_{t}+\gamma\delta_{t+1}+\gamma^{2}\delta_{t+2})+\cdot\cdot\cdot\ &=\delta_{t}(1+\lambda+\lambda^{2}+\cdot\cdot\cdot)+\gamma\delta {t+1}(\lambda+\lambda^{2}+\cdot\cdot\cdot)+\gamma^{2}\delta{t+2}(\lambda^{2 }+\cdot\cdot\cdot)+\cdot\cdot\cdot\end{split} \tag{2.2.2}
$$
我们将$\delta$ 称为TD残差. 其中$\delta_t$ 是TD(0)算法中的$A_t$ , 加入的参数$\lambda \in [0,1]$, 观察上式, 我们就发现可以通过调节$\lambda$ 的值来进行tradeoff, 当其为0时, 就变成了简单的TD(0), 而当其为1时, 就变成了蒙特卡洛采样. 表示先假设不能取1. 然后我们进一步推导, 根据等比数列求和公式:
$$
A_{t}^{GAE_{1}}=\delta_{t}(\frac{1-\lambda^{k}}{1-\lambda})+\gamma\delta_{t+1 }(\frac{\lambda(1-\lambda^{k - 1})}{1-\lambda})+\gamma^{2}\delta_{t+2}( \frac{\lambda^{2}(1-\lambda^{k - 2})}{1-\lambda})+\cdots \tag{2.2.3}
$$
由于$1-\lambda$ 是一个常数, 可以两边同乘, 而当k趋向于无穷, 上面的$\lambda^{k-n}$趋向于0. 再直接用新的A替换, 得到:
$$
A_{t}^{GAE}=\delta_{t}+\gamma\lambda\delta_{t+1}+\gamma^{2}\lambda^{2}\delta_ {t+2}+\cdot\cdot\cdot=\sum_{k=0}^{ \infty} \left( \gamma \lambda \right)^{k} \delta_{t+k} \tag{2.2.4}
$$
上式就是GAE算法的核心公式. (乍一看没有baseline, 其实TD残差$\delta$ 中就包含了baseline了).

三. AC经典算法

1. QAC (Q-based Actor-Critic)

Actor是演员, 负责选择动作, 是一个以$\theta$ 参数化的策略函数$\pi_\theta(a|s)$ ; Critic是评论家, 用来评价动作的好坏, 用评估结果知道actor改进策略. 如果Critic用Q值来计算误差, 那么就称为基于Q值的Actor-Critic算法, QAC. 如果是基于$V(s')$ 值来计算的话, 用$R+\gamma V$ 代替Q值, 成为基于优势函数的Actor-Critic算法, 也叫Advantage-Actor-Critic算法, 也即A2C.

(1) 优化思想

QAC的优化是针对与REINFORCE而言的, 最大的好处就是引入了基线. Q值的求取, 我们采用学习笔记(二)中的时序差分学习TD算法. Critic是一个价值网络, 通过学习Q值, 逼近真实的$Q_\pi(s,a)$; Actor是策略更新.

Critic的更新是Sarsa算法: $$ Q(s_t,a_t) \leftarrow Q(s_t,a_t) + \alpha [r_{t+1} + \gamma Q(s_{t+1},a_{t+1}) - Q(s_t,a_t)] \tag{3.1.1} $$

Actor的更新则是策略梯度, 其实就是用Q值来作为梯度策略的奖励R: $$ \theta \leftarrow \theta+\alpha \nabla_\theta log \pi_\theta(a|s) \cdot Q(s,a) \tag{3.1.2} $$

(2) 优势函数

基本QAC中, 实质上没有显式的优势函数, 它直接使用Q值作为了基线. 它实际上就是式子1.1, 朴素的将Q函数引入了进来而已.

(3) 流程

QAC的流程如下: Actor观察当前状态, 按照当前策略随机执行一个动作, Agent从环境得到即时反馈, Actor按照当前的策略$\theta$ (一个策略网络) 随机一个动作, 但是只选不行动. 此时, Critic用当前价值网络计算当前状态动作对的估计价值$Q(s_t,a_t)$ 和下一个动作对的预估价值$Q(s_{t+1},a_{t+1})$ . 最后, 计算TD Target和TD Error. 然后用TD梯度下降更新参数.

2. Advantage Actor-Critic算法 (A2C)

(1) 优化思想

A2C与QAC相比, 首次显式计算了优势函数. 使用状态价值函数V作为Critic.

Critic是V函数的更新: $$ V(s_t) \leftarrow V(s_t) + \alpha (r_{t+1} + \gamma V(s_{t+1}) - V(s_t)) \tag{3.2.1} $$ 还记得吗, 这个式子是在笔记(二)引入TD的时候的式子, 实际上这里的TD Target就是Q的贝尔曼公式(可以回看笔记(一)).

Actor的更新则是使用了优势函数作为R的策略梯度: $$ \theta \leftarrow \theta+\alpha \nabla_\theta log \pi_\theta(a|s) \cdot A(s,a) \tag{3.2.2} $$

(2) 优势函数

利用前面的知识, 我们把Q值写为TD残差的形式, 从而得到: $$ A(s,a)=r_{t+1} + \gamma V(s_{t+1})-V(s_t) \tag{3.2.3} $$ A2C构造优势函数$A(s,a)=Q(s,a)-V(s)$, 状态s下选动作a, 比状态s的平均动作价值好多少. Critic的目标是让自己的预测最准确, 通过不断修正自己的估计, 来让$A(s,a)$ 最小化, 这意味着$V(s_t)$ 可以更精确表示从状态$s_t$ 出发的实际回报. 批评家的评价越准确, 演员的动作调整才越正确. (如果你详细研究了笔记1, 那里其实说明了最好的Q就等于V, 显然我们需要逼近最好的Q的策略, 让优势函数即亮着的差值最小).

说到这里, 显然这个优势函数可以看作是网络的Loss (实际上就是), 于是我们借鉴深度学习中的更新方法, 把这个Loss求一个平方损失误差, 来更新Critic网络. 我们把Critic网络的参数写做$\omega$ , 就有如下平方损失误差: $$ L(\omega)=\frac{1}{2}\left(r_{t}+\gamma V_{\omega}\left(s_{t+1}\right)-V_{\omega}\left(s_{t}\right)\right)^{2} \tag{3.2.4} $$ 对损失函数求导有不带系数的简洁形式: $$ \nabla_{\omega} L(\omega)=-\left(r_{t}+\gamma V_{\omega}\left(s_{t+1}\right)-V_{\omega}\left(s_{t}\right)\right) \nabla_{\omega} V_{\omega}\left(s_{t}\right) \tag{3.2.5} $$ 使用梯度下降来更新参数即可.

而且, 这个优势函数A值同时也会去用上述的3.2.2式子去更新策略$\theta$ 即Actor网络. 所以我们说, 在每个mini-batch中, 我们同时:

用优势函数A通过策略梯度更新Actor网络
用A相关的目标值通过MSE更新Critic网络

这样, Actor和Critic就可以协同进化. Actor需要Critic评估动作好坏, 而Critic需要Actor策略来准确估计价值(别忘了, Q函数是隐含策略的). 我们回想Q-learning, 其实是除了将AC算法看成是Policy-based引入了Q值, 也可以看成是Q-learning算法的贪心策略被替换成了Actor部分, 一个新的动作选择策略, 并且是概率分布形式的. 这是分别从Value和Policy出发, 得到AC算法的视角, 殊途同归.

3. Asynchronous Methods for Deep Reinforcement Learning算法 (A3C)

如名称所示, 这是一种异步强化的学习算法, 这是一种非常有效的算法, 在围棋、星际争霸等复杂任务上都取得了很好的效果. 不过有一点要说的, A3C其实比A2C出现的要早, A2C可以看作A2C的同步简化版.

A3C的最大优点就是可以加快强化学习的速度, 它同时使用多个进程 (worker), 这些进程会把所有的经验集合在一起, 所以对硬件也是有需求的.

A3C一开始有一个全局网络 (global network). 全局网络包含策略网络和价值网络, 它们在前几个层会绑定(tie)在一起. 每个进程在工作前都把全局网络的参数复制过来, 接下来与环境交互计算梯度, 再梯度去更新全局网络的参数.

A3C采用了平行探索的方法, 所有演员都是平行跑的, 每个演员各做各的, 当然传回去的参数可能发生覆盖, 但是没关系, 由于每次工作时复制, 所以总会以最新的参数去交互.

虽然速度上有提升, 但是多个worker同时更新网络, 可能会导致训练不稳定, 重新性差. 与之相比, A2C不仅简洁, 而且某些任务上性能会更好, 更重要的是可重新训练方法, 在对稳定性要求极高的RLHF中, A2C的设计更好.

四. Trust Region Policy Optimization (TRPO)算法

注: TRPO背后的数学原理比较复杂, 因此进行推导的过程繁琐, 引入的概念也很多, 请更注重了解其中的思想. TRPO也是PPO算法的基础, 但是PPO算法已经在效率上全面打败TRPO. 以下推导过程的公式完全可以略过, 仅做参考.

相比于深度学习, 我们面对的重大问题之一, 就是在面对复杂的未知函数形状的"山", 用梯度上升很难决定往哪走走多少, 也无法确保是凸函数. 而TRPO则设定了置信域 在旧策略的领域, 在这之中在优化策略. 相当于在目前未知"山"的形状, 每次画一个小圆圈, 在安全范围内大步走.

我们用KL散度来衡量新旧策略的远近, 并将其限制在阈值内. 并且, 从理论上证明了这是在单调改进.

策略$\pi$ 的期望回报:
$$ \eta(\pi)=\mathbb{E}{s_0,a_0,\ldots}\left[\sum{t=0}^\infty\gamma^tr(s_t)\right]\tag{4.1} $$ 而2002年, Kakade & Langford等人得出了这样的结论: 新策略的期望回报 = 旧策略的期望回报 + 新策略在旧策略优势函数上的累计期望: $$ \eta(\tilde{\pi})=\eta(\pi)+\mathbb{E}{s_0,a_0,\cdots\sim\tilde{\pi}}\left[\sum{t=0}^\infty\gamma^tA_\pi(s_t,a_t)\right] \tag{4.2} $$ 我们后面的推导, 将结合7.2式进行. 首先根据期望的线性可拆, 我可以将求和符号提出来: $$ \mathbb{E}{s{0},a_{0},\cdots\sim\tilde{\pi}}\left[\sum_{t=0}^{\infty}\gamma^{t}A_{\pi}(s_{t},a_{t})\right]=\sum_{t=0}^{\infty}\gamma^{t}\cdot\mathbb{E}{s{0},a_{0},\cdots\sim\tilde{\pi}}\left[A_{\pi}(s_{t},a_{t})\right] \tag{4.3} $$ 接下来, 我们引入折扣访问频率 (状态占据度量) , 来表示状态s在策略$\pi$ 之后的长期权重, 经过t步之后处于状态s的折扣概率之和: $$ \begin{aligned}&\rho_{\pi}(s)\

& {=}P(s_{0}=s){+}\gamma P(s_{1}=s){+}\gamma^{2}P(s_{2}=s){+}\ldots \

& =\sum_{t=0}^\infty\gamma^t\cdot\mathbb{P}{s_0\sim d,\tilde{\pi}}\left[s_t=s\right] \end{aligned}\tag{4.4} $$ 接下来, 我们把$A\pi(s_t,a_t)$ 视作随机变量, 指的就是在$s_t$ 这个状态下选择$a_t$ 动作的Q值, 比上选择a状态的平均Q值多出来的部分. 换言之, 就是跟AC算法中一样的优势函数. 它的期望可以进行分解:

$$ \begin{aligned}&\mathbb{E}{s_0, a_0, \cdots \sim \tilde{\pi}} \left[ A{\pi}(s_t, a_t) \right] \

&= \sum_s \sum_a A_{\pi}(s, a) \cdot \mathbb{P}{s_0, a_0, \cdots \sim \tilde{\pi}} \left( s_t = s, a_t = a \right)\end{aligned} \tag{4.5} $$ 将4.5求和的P写为条件概率的形式: $$ \mathbb{P}\left[s{t}=s,,a_{t}=a\right]=\mathbb{P}\left[s_{t}=s\right]\cdot\mathbb{P}\left[a_{t}=a\mid s_{t}=s\right]\tag{4.6} $$ 由于是马尔可夫链, 动作选择仅依赖于当前状态, 所以有:
$$ \mathbb{P}[a_t=a \mid s_t=s]=\tilde{\pi}(a \mid s)\tag{4.7} $$ 4.7代回4.6, 再代回4.5得到优势函数的期望实际为: $$ \begin{aligned}

&\mathbb{E}{s{0},a_{0},\ldots\sim\tilde{\pi}}\left[A_{\pi}(s_{t},a_{t})\right]\

&=\sum_{s}\sum_{a}A_{\pi}(s,a)\cdot\mathbb{P}{s{0},a_{0},\ldots\sim\tilde{\pi}}(s_{t}=s)\cdot\tilde{\pi}(a\mid s)\end{aligned}\tag{4.8} $$ 再代回4.2后半, 我们可得到新形式, 整理后发现出现了前面4.4引入的状态占据量:

$$ \begin{aligned}&\mathbb{E}{s_0,a_0,\cdots\sim\tilde{\pi}}\begin{bmatrix}&\gamma^tA\pi(s_t,a_t)\end{bmatrix}\

&=\gamma^t\cdot(\sum_s\sum_aA_\pi(s,a)\cdot\mathbb{P}(s_t=s)\cdot\tilde{\pi}(a\mid s))\

&=\sum_{s}\sum_{a}\left(\sum_{t=0}^{\infty}\gamma^{t}\cdot\mathbb{P}(s_{t}=s)\right)\cdot\widetilde{\pi}(a\mid s)\cdot A_{\pi}(s,a)\

&=\sum_s\rho_{\tilde{\pi}}(s)\sum_a\tilde{\pi}(a|s)A_\pi(s,a)\end{aligned}

\tag{4.9} $$ 将4.9代入4.2: $$ \eta(\tilde{\pi})=\eta(\pi)+\sum_s\rho_{\tilde{\pi}}(s)\sum_a\tilde{\pi}(a|s)A_\pi(s,a)\tag{4.10} $$ 这时我们发现, 要想求出这个值, 是需要新策略$\tilde{\pi}$ 的状态分布情况. 而这个值目前是得不到的. 所以我们引入代理函数, 用原策略来近似: $$ L_\pi(\tilde{\pi})=\eta(\pi)+\sum_s\rho_\pi(s)\sum_a\tilde{\pi}(a|s)A_\pi(s,a)\tag{4.11} $$ 我们发现, 在旧策略$\pi$ 处,$L_\pi$ 和$\eta$ 的梯度相同, 所以在旧策略附近优化$L_\pi$ 就近似于优化$\eta$ .

接下来, 我们还要引入KL散度来衡量两个概率分布的远近, 用来表示用q来近似p的时候的信息损失: $$ D_{KL}(P||Q)=E_p\left[\log\frac{P(x)}{Q(x)}\right]=\Sigma_ip_i\log\frac{p_i}{q_i}\tag{4.12} $$

另外还有一种总变差散度(TV散度) 也可以衡量: $$ D_{\mathrm{TV}}(P||Q) = \frac{1}{2} \Sigma_i |p_i - q_i|\tag{4.13} $$ 而 Pinsker不等式 就把两个散度联系到了一起: $$ |Q-P|{\text{TV}} \leq \sqrt{\frac{1}{2}D{\text{KL}}(Q|P)} \tag{4.14} $$ 简化形式: $$ D_{TV}(p||q)^2\leq D_{KL}(p||q)\tag{4.15} $$ TPRO论文, 证明了$L_\pi$ 和$\eta$ 的误差下界: $$ \eta(\pi_{new})\geq L_{\pi_{old}}(\pi_{new})-\frac{4\epsilon\gamma}{(1-\gamma)^2}\alpha^2 \tag{4.16} $$ 其中$\alpha$ 是新旧两个策略在所有状态下的最大TV散度, 且$\epsilon=\max_{s.a}|A_{\pi}(s,a)|$ , 我们把$\frac{4\epsilon\gamma}{(1-\gamma)^2}$ 当作常数C处理, 结合4.14不等式, 就可以导出: $$ \eta(\tilde{\pi})\geq L_\pi(\tilde{\pi})-C\cdot D_{KL}^{\max}(\pi,\tilde{\pi})\tag{4.17} $$ 这是一个很好的式子, 观察式子, 不等式右边可以成为新策略的性能下界, 即: $$ M(\pi)=L_\pi(\tilde{\pi})-C\cdot D_{KL}^{\max}(\pi,\tilde{\pi})\tag{4.18} $$ 换言之, 只要提升/最大化$M(\pi)$ , 就能保证$\eta$ 的性能单调上升. 这演变为了重要的MM 算法, 这是一种迭代的方法, 它利用函数的凸性来寻找它们的最大值或最小值. 本问题是目标函数最大化问题, 所以MM的具体表现为 Minorize-Maximization 算法: 每次迭代找到原非凸目标函数的一个下界函数 , 求下界函数的最大值. $$ \underset{\theta}{\operatorname*{\mathrm{maximize}}}\left[L_{\theta_{old}}(\theta)-C\cdot D_{KL}^{\max}(\theta_{old},\theta)\right]\tag{4.19} $$ 继续观察4.18, C因为分母带有1-折扣因子的平方, 当折扣因子取的很大时, 就会让C很大. 这就可以看出来, C其实是一个惩罚项的权重, 换而言之: 新旧策略的分布离得远和折扣因子偏大都会惩罚.

但是这里有个问题, $\gamma$ 如果取大一点, C就会变得超级大, 给策略距离超级加倍, 导致不敢更新策略了.

为了解决这个问题, 我们引入置信域, 我们把7.19中的这个惩罚项改成置信域, 变成带约束条件的最大化问题, 4.19变成了:

$$ \begin{aligned} &\underset{\theta}{maximize}\qquad L_{\theta_{old}}\

& subject\quad to \qquad \overline {D}_{KL}^{\rho _{\theta _{old}}}( \theta _{old}, \theta ) \leq \delta\end{aligned}\tag{4.20} $$

其中: $$ L_{\theta_{\mathrm{old}}}(\theta) = \mathbb{E}{s \sim \rho{\theta_{\mathrm{old}}}, a \sim \pi_{\theta}} \left[ A_{\pi_{\theta_{\mathrm{old}}}}(s, a) \right] \tag{4.21} $$

我们来看一下$\overline {D}{KL}^{\rho {\theta {old}}}( \theta {old}, \theta )$ 这个式子, 这其实是把最大KL散度变成了平均KL散度. 这是因为, 如果是最大KL散度的话, 我们就要要求所有状态的KL散度都小于某个值, 这是难以实现的. 而平均KL散度只约束旧策略访问到的平均KL散度: $$ \overline{D}{\mathrm{KL}}^\rho(\theta_1,\theta_2):=\mathbb{E}{s\sim\rho}\left[D{\mathrm{KL}}(\pi{\theta_1}(\cdot|s)\parallel\pi_{\theta_2}(\cdot|s))\right] \tag{4.22} $$ 这里又要引入强化学习的一个重要概念: 重要性采样. 我们要计算$E_{X\sim q}[f(X)]$, 但是从q上采样, 可能并非是最优的. 我们要改成p上采样的话, 可以推到出如下式子: $$ \begin{aligned}\mathbb{E}{X\sim q}[f(X)]&=\int f(x)q(x)dx\&=\int f(x)\cdot\frac{q(x)}{p(x)}\cdot p(x)dx\&=\mathbb{E}{X\sim p}\left[f(X)\cdot\frac{q(x)}{p(x)}\right]\end{aligned}\tag{4.23} $$

其中$\frac{q(x)}{p(x)}$ 被称为重要性权重, 代表的是从$p(x)$ 采样的样本修正到$q(x)$ 分布下的期望估计.

观察7.21, 我们引入的原因是, 虽然我们已经通过代理函数, 让状态从旧策略进行采样, 但是a依然是在新策略$\pi_{\theta}$ 下进行采样, 但是我们只能从旧策略中采样动作. 因此用重要性采样思想: $$ \mathbb{E}{a\sim\pi{\theta}}[f(a)]=\mathbb{E}{a\sim\pi{\theta_{\text{old}}}}\left[f(a)\cdot\frac{\pi_{\theta}(a|s)}{\pi_{\theta_{\text{old}}}(a|s)}\right]\tag{4.24} $$ 即: $$ L_{\theta_{\mathrm{old}}}(\theta) = \mathbb{E}{s \sim \rho{\theta_{\mathrm{old}}}, a \sim \pi_{\theta_{\mathrm{old}}}} \left[\frac{\pi_{\theta}(a|s)}{\pi_{\theta_{\mathrm{old}}}(a|s)} \cdot A_{\pi_{\theta_{\mathrm{old}}}}(s, a)\right]\tag{4.25} $$ 最后, TRPO还在$\theta = \theta_{old}$ 附近都做了近似: $L_{\theta_{\mathrm{old}}}(\theta)$ 在$\theta = \theta_{old}$ 做一阶泰勒展开; 约束条件(平均KL散度)做二阶泰勒展开: $$ L_{\theta_{old}}(\theta) \approx L_{\theta_{old}}(\theta_{old}) + \nabla_{\theta}L_{\theta_{old}}(\theta_{old}) \cdot (\theta - \theta_{old})\tag{4.26} $$ $$ \overline{D}{KL}^{\rho{\theta_{old}}}(\theta_{old},\theta)\approx\frac12\Delta\theta^TA\Delta\theta \tag{4.27} $$ 其中$\Delta\theta$ 是参数的更新量, A为平均KL散度在$\theta_{old}$ 处的Hessian矩阵 (海森矩阵是多元二阶偏导数构成的对称矩阵), 即: $$ A=\frac{\partial}{\partial\theta_{i}}\frac{\partial}{\partial\theta_{j}}\mathbb{E}{s\sim\rho{\pi}}\left[D_{\mathrm{KL}}\left(\pi(\cdot|s,\theta_{\mathrm{old}})\parallel\pi(\cdot|s,\theta)\right)\right]\bigg|{\theta=\theta{\mathrm{old}}}\tag{4.28} $$ 最终, 问题转化成了: $$ \begin{aligned}&\max~g^T(\theta-\theta_{old})\

& s.t.\frac12(\theta-\theta_{old})^TH(\theta-\theta_{old})\leq\delta \end{aligned} \tag{4.29} $$ 其中, g就是$\nabla_{\theta}L_{\theta_{old}}(\theta_{old})$ , H就是7.28的海森矩阵.

后面实际上就是一个拉格朗日函数函数求极值的问题,用到的Krylov子空间迭代求解和Fletcher - Reeves共轭梯度的算法.

推导到这里我们悬崖勒马, 其一是因为信任域的思想已经体现了出来, 后面就是纯数学推导和细节优化了, 其二是因为TRPO催生出的PPO算法, 已经全面优于TRPO, 执着于其完整推导没有意义. 等到有契机的话, 再回来对照代码好好推...

我们将TRPO的思想直观展现出来如下图, 人在上山的过程中, 先四周探路得到值得信任的下限, 按照下限上升方向直接冲过去就一定是优化.

六. Proximal Policy Optimization (PPO)算法

TRPO的复杂性催生了PPO算法, 它通过三种方式进行优化: 裁剪目标函数, 自适应惩罚和一阶优化. 既保持了TRPO的稳定性, 又大幅简化了实现和提高了运算效率. 已成为最主流的策略优化算法之一. 这个要认真看,特别是PPO-Clip, 公式看起来复杂实则简单.

PPO算法通过与环境交互采样数据/利用随机梯度上升优化一个代理目标函数交替进行. 与标准策略梯度方法每次仅对一个数据样本执行一次梯度更新不同, PPO算法提出了新颖的目标函数, 支持进行多轮小批量更新. 这种算法被称为近端策略优化 (Proximal Policy Optimization, PPO).

首先, 过去的算法存在或多或少的问题, 论文中列举如下:

带有函数近似的Q-learning在许多简单问题上都会失败, 且其原理尚不明确.
传统的梯度策略方法存在数据效率低和稳健型差的问题.
TRPO相对复杂, 且无法与包含噪声(如Dropout) 或参数共享 (在策略和价值函数之间, 或在辅助任务之间)

其中2和3都比较容易理解, 但是1我们要进行进一步说明. 虽然表格形Q-learning有坚实的理论保证, 我们在前进行了详细的推理和证明其可以收敛到最优Q函数, 但是变成DQN后, 这些理论基础实际上就失灵了. 非线性函数近似器 (如神经网络) 的表达能力极强, 但是它的优化landscape非常复杂, 是非凸的, 无法保证梯度下降能找到最优解, 甚至不能保证它能稳定在一个局部最优解.

再进一步来说, DQN包含了三个不稳定因素, 函数近似+自举+离策略学习. 函数近似就是前面说的, 这种近似器是泛化的, 当针对某一个Q更新网络的参数会意外改变多对Q值, 产生牵连效应. 而自举的性质更是给这个近似误差加上了放大镜, 因为它通过自己更新自己, 会造成误差传播的恶性循环. 最后, 离策略学习指的是其异策略的考量, 通过“不相关”的数据来拟合目前的目标, 导致的更新不稳定.

AC框架的Critic网络虽然避免了离策略学习, 避免了max操作的不稳定性, 但是自举和近似的挑战还在进行中. AC框架没有消除Critic训练的根本问题, 但通过它的系统架构设计, 将这些问题影响降到了可管理的水平.

所以说,在开发一种可拓展 (适用于大型模型和并行实现)、数据高效且稳健 (即无需调整超参数即可解决多种问题) 的方法方面, 仍有许多改进空间.

PPO算法在仅使用一阶优化的同时, 实现了与TRPO相当的数据效率和可靠性能. 新设计的目标函数在使用了截断的概率比, 从而对策略性能形成了一个悲观估计 (下界) . 为了优化策略, 我们从策略中采样数据与对所采样数据进行若干轮优化之间交替进行.

1. 重要性采样 (importance sampling)

假设我们不能从p中采集数据, 但是又想得到p的期望怎么办? 其中一个很自然的想法, 就是用到另一种q分布中采样. 注意, 我们的目的是通过采样来估计期望, 所以只要保证替换完之后的期望不变就可以: $$ \mathbb{E}{x\sim p}[f(x)]=\int f(x)p(x)\mathrm{d}x=\int f(x)\frac{p(x)}{q(x)}q(x)\mathrm{d}x=\mathbb{E}{x\sim q}[f(x)\frac{p(x)}{q(x)}] \tag{6.1.1} $$ 也就是说, 我们每次从q中采集数据, 都要乘以一个重要性权重(importance weight) 来修正两个分布的差距. 这种策略就叫做重要性采样.

需要注意的是, 虽然我们保证了E一致, 但是没有保持方差一致. 所以为了让两者更靠近, 必须要采集更多的数据, 我们考察下面一种情况: 我们无法保证采集都在一个区间, 为了尽可能缩小这样的情况, 我们必须要尽量更多的采样, 或者用某些手段来限制两个函数的差距. 这个后面会进行说明.

至于为什么要引入重要性采样. 一言以蔽之, PPO算法通过重要性采样来用旧策略更新新策略, 主要就是为了增加样本的效率和稳定性. :

样本效率: 在强化学习中, 与环境交互收集数据通常是非常耗时的, 如果每次更新策略后都要重新收集数据, 那么样本效率会很低. 重要性采样允许用旧策略收集的数据来估计新策略的梯度, 从而多次使用同一批数据.
稳定性: 通过旧策略的数据, 并约束新旧策略的差异, 可以避免策略更新步幅过大, 从而稳定训练.

2. PPO算法

PPO算法的核心是通过重要性采样, 将同策略变成异策略. 我们不需要策略$\theta$ 直接与环境交互, 而是使用旧策略$\pi_\theta'$ ,它的工作是做示范 (demonstration): $$ \nabla\bar{R}\theta=\mathbb{E}{\tau\sim p_{\theta^{\prime}(\tau)}}\left[\frac{p_\theta(\tau)}{p_{\theta^{\prime}}(\tau)}R(\tau)\nabla\log p_\theta(\tau)\right] \tag{6.2.1} $$

这里我插一嘴, 前面的章节中经常都把‘ 作为“下一步”, 但是这里的行为策略$\theta'$, 其实表示的“之前的”, 或者可以写作$\theta_{old}$ , 而$p$和$\pi$ 亦有混杂使用, 虽然都表示决策的概率. 可能我学习的主要资料之一蘑菇书EasyRL不同章节书写人员不同, 没有对符号进行统一, 这样要读懂全部公式很困扰... 所以我会在容易造成歧义的公式下面下上解释.

还有一点, EazyRL中将策略$\theta'$ 看成是另一个Actor, 这是很容易引起误解的说法, 其实更准确的说法是一个Actor在不同时间的快照, PPO是同策略的. 当然作者后面解释了通过KL、Clip约束, 其实这两个策略相近, 但是一开始就不用另一个Actor这种误导性比喻就行啦...

这样限制有显著的好处, 现在与环境交互的是$\theta'$ 而不是$\theta$, 所以采样的数据与$\theta$ 本身是没有关系的. 因此我们就可以让 $\theta'$ 与环境交互采样大量的数据, $\theta$ 可以多次更新参数, 一直到 $\theta$ 训练到一定的程度. 更新多次以后, $\theta'$ 再重新做采样.

我们可以将实际做策略梯度的时候, 并不是给整个轨迹$\tau$ 一样的分数, 而是将每一个状态-动作对分开计算, 实际更新梯度的过程可以写作下式: $$ \mathbb{E}{\left(\textit{s}{t},\textit{a}{t}\right)\sim\pi{ \theta}}\left[A^{\theta}\left(\textit{s}{t},\textit{a}{t}\right)\nabla\log p {\theta}\left(a{t}^{n}|\textit{s}{t}^{n}\right)\right] \tag{6.2.2} $$ 其中, 这个状态-动作对的优势$A^{\theta}\left(\textit{s}{t},\textit{a}_{t}\right)$ 是一个用累积奖励减去基线 (baseline)的量.

但是, 如上述理由如1中所说, 我们就需要一个量来限制两个人的差距. 为了得到两个分布的距离, 我们自然而然就想到通过一个量来限制.

需要注意的是, 虽然进行了重要性采样, 但是约束由于约束, 行为策略$\theta'$ 和目标策略$\theta$ 非常接近, 所以两者可以看成是同一个策略, 因此PPO是同策略算法.

至于怎么来限制, 具体而言有两种重要变种:

(1) 近端策略优化惩罚 (PPO-penalty)

$$ J_{{\mathrm{PPO}}}^{{\theta^{k}}}(\theta)=J^{{\theta^{k}}}(\theta)-\beta{\mathrm{KL}}\left(\theta,\theta^{k}\right) \tag{6.2.3} $$

TRPO把KL散度当作约束, 希望两者差距小于$\delta$, 而PPO直接把约束放在了要优化的式子里, 实现了自适应惩罚.

(2) 近端策略优化裁剪 (PPO-clip)

$$ J_{\text{PPO2}}^{\theta^{k}}(\theta) \approx \sum_{(s_{t},a_{t})} \min \left(\frac{p_{\theta}\left(a_{t}|s_{t}\right)}{p_{\theta^{k}}\left(a_{t}|s_{t}\right)}A^{\theta^{k}}\left(s_{t},a_{t}\right),\right. \left.\text{clip}\left(\frac{p_{\theta}\left(a_{t}|s_{t}\right)}{p_{\theta^{k}}\left(a_{t}|s_{t}\right)},1-\varepsilon,1+\varepsilon\right)A^{\theta^{k}}\left(s_{t},a_{t}\right)\right) \tag{6.2.4} $$

PPO算法的裁剪起到和信赖域相似的作用, 阻止了步子迈的太大, 但是不需要重新计算, 只做裁剪, 大大优化了性能. 本质上是设计了一个“动态信任域”, 因为对领域进行约束, 被称为近端策略优化.

直接看上面的式子, 我估计肯定是懵逼, 有一种自己学了这么久基础结果还是被一下子干碎的荒谬感. 别急, 我们来拆解一下. 首先, 我们想优化的期望是: $$ J(\theta)=\mathbb{E}{a \sim \pi\theta}\left[A(s,a)\right] \tag{6.2.5} $$ 这也是AC框架下的期望统一表达, 然后, 我们回忆策略梯度的期望形式, 将其中的奖励函数R变成现在的AC框架中的优势函数A, 即: $$ \nabla_{\theta}J(\theta)=\mathbb{E}{a \sim \pi{\theta}}\left[ \nabla_\theta log\pi_\theta(a|s)A(s,a) \right] \tag{6.2.6} $$ 但是, PPO没有直接采用这个梯度估计, 而是重新构建了一个目标函数. 所以我们从6.2.5出发, 不是进行求导, 而是通过另外的方式推演, 首先我们将前面的重要性采样引入, 式子变为: $$ J(\theta)=\mathbb{E}{a \sim \pi{\theta_{old}}}\left[ \frac{\pi_\theta(a|s)}{\pi_{\theta_{old}}(a|s)} A(s,a) \right] \tag{6.2.7} $$

为了简化书写, 我们可以把$\frac{\pi_\theta(a|s)}{\pi_{\theta_{old}}(a|s)}$ 写做概率比$r_t(\theta)$, 把整个$A(s,a)$ 记为优势策略估计$\hat{A}$. 然后, 在时间步t内的损失, 就可以写成很简洁的形式: $$ J(\theta)=\hat{\mathbb{E}}[(r_t(\theta)\hat{A})]\tag{6.2.8} $$ 然后, 我们希望限制更新的步子, 即在第t个时间步内, 最多只能在一定范围内更新. 这次我们使用一种简单粗暴的方法 -- 如果更新太多了, 就进行截断, 如下图所示:

为了实现这个目的, 我们可以引入截断函数clip, clip函数后面的两个量, 表示把函数值限制在这个范围内. 于是, 我们可以将式子进一步写成: $$ J(\theta)=\hat{\mathbb{E}}[min(r_t(\theta)\hat{A},clip(r_t(\theta),1-\epsilon,1+\epsilon)\hat{A})]\tag{6.2.9} $$

在梯度形式的式子6.2.7中, 按理说除去表示方向的得分函数, 优势函数和概率比的乘积应该是更新的幅度, 可是为什么是只对前面的概率比进行截断? 这是因为, 直接截断得分函数之外的部分, 实际上破坏了相对比较信息, 比如“很好”和“一般好”的动作可能被截断成一样的值, 这不是我们希望看到的. 我们只是希望更新的幅度被限制. 所以, 我们留下的得分函数表示方向, 留下优势函数表示优势比较.

上述是期望形式, 写成采样形式就是一开始给出的: $$ J^{\theta_{old}}(\theta) \approx \sum_{(s_{t},a_{t})} \min \left(\frac{p_{\theta}\left(a_{t}|s_{t}\right)}{p_{\theta_{old}}\left(a_{t}|s_{t}\right)}A^{\theta_{old}}\left(s_{t},a_{t}\right),\right. \left.\text{clip}\left(\frac{p_{\theta}\left(a_{t}|s_{t}\right)}{p_{\theta_{old}}\left(a_{t}|s_{t}\right)},1-\varepsilon,1+\varepsilon\right)A^{\theta_{old}}\left(s_{t},a_{t}\right)\right) \tag{6.2.10} $$

PPO-Clip既工程友好又理论单调改进, 该算法曾一度称为OpenAI的核心算法, 并迅速推广到Gym等框架示例中, 成为了很多人入门RL的选择. 这种工程化的约束思想, 启发了很多研究者, 继续沿着这条 “稳定优化+可控偏移” 的道路提出了很多变体. 它们将强化学习中RL最优解思想, 转化为大模型与人类对齐的优化框架, 开启了整个LLM对齐家族的演化历程.

FastAPI Bigger Applications：APIRouter、多文件应用与生命周期

Thu, 26 Mar 2026 00:00:00 GMT

FastAPI 的前面几章都还能在一个文件里完成，但一旦路由、依赖和安全逻辑变多，问题就会从“会不会写”变成“怎么组织”。

1. `APIRouter` 解决的不是功能，而是组织

APIRouter 不是另一个小型 FastAPI，它更像“可组合的路由组”。

官方 Bigger Applications 页里最值得留下来的直觉是：

应用不是只有一个 app
路由可以先在各自模块里组织好
最后再由主应用统一挂载

2. 最常见的多文件结构

这类结构是最典型的起点：

app/
├── __init__.py
├── main.py
├── dependencies.py
└── routers/
    ├── __init__.py
    ├── items.py
    └── users.py

这里的分层已经很清楚：

main.py：组装应用
routers/：各业务路由
dependencies.py：共享依赖

3. 在路由模块里定义 `APIRouter`

from fastapi import APIRouter, Depends, HTTPException

from ..dependencies import get_token_header

router = APIRouter(
    prefix="/items",
    tags=["items"],
    dependencies=[Depends(get_token_header)],
    responses={404: {"description": "Not found"}},
)


@router.get("/")
async def read_items():
    return [{"name": "Foo"}]

这一层最重要的点是：

prefix
tags
dependencies
responses

都可以直接挂在 APIRouter 上，而不用在每个路径操作里重复写。

4. 在主应用里 `include_router`

from fastapi import Depends, FastAPI

from .dependencies import get_query_token
from .routers import items, users, admin

app = FastAPI(dependencies=[Depends(get_query_token)])

app.include_router(users.router)
app.include_router(items.router)
app.include_router(
    admin.router,
    prefix="/admin",
    tags=["admin"],
    dependencies=[Depends(get_token_header)],
    responses={418: {"description": "I'm a teapot"}},
)

官方文档里这段很有代表性，因为它说明：

路由模块本身可以保持通用
应用层再决定怎么挂载它
include_router() 时还能继续补 prefix、tags、dependencies、responses

来源：Bigger Applications 官方页 https://fastapi.tiangolo.com/zh/tutorial/bigger-applications/

5. 这样组织的真正好处

这不是为了“目录看起来整齐”，而是为了几件更实在的事：

共享路由模块更容易
共享依赖逻辑更自然
主应用装配时灵活度更高
/docs 里的标签分组也更清楚

6. `lifespan`：把应用级初始化和清理写成一对

如果有些资源应该在应用启动时加载、关闭时释放，FastAPI 现在更推荐用 lifespan。

from contextlib import asynccontextmanager
from fastapi import FastAPI

ml_models = {}


def fake_answer_to_everything_ml_model(x: float):
    return x * 42


@asynccontextmanager
async def lifespan(app: FastAPI):
    ml_models["answer_to_everything"] = fake_answer_to_everything_ml_model
    yield
    ml_models.clear()


app = FastAPI(lifespan=lifespan)


@app.get("/predict")
async def predict(x: float):
    result = ml_models["answer_to_everything"](x)
    return {"result": result}

官方文档明确写到：

yield 之前在应用启动前执行
yield 之后在应用结束时清理

来源：Lifespan 官方页 https://fastapi.tiangolo.com/zh/advanced/events/

7. `lifespan` 和依赖里的 `yield` 有什么不同

它们都用到了 yield，但层级不一样：

依赖里的 yield：围绕一次请求
lifespan：围绕整个应用生命周期

所以适合放在 lifespan 里的，通常是：

模型预加载
全局连接池初始化
应用级缓存

而数据库 session 这种更短命的资源，还是更适合放依赖里。

LangChain 核心组件 01：Models

Thu, 26 Mar 2026 00:00:00 GMT

从这里开始，学习顺序正式进入“先组件，后 Agents”。Models 是最先该熟悉的，因为几乎所有上层能力最终都要落回模型调用。

1. 介绍

大语言模型是功能强大的人工智能工具，能够像人类一样理解和生成文本。它们用途广泛，无需针对每项任务进行专门训练，即可完成内容创作、语言翻译、文本摘要和问答等工作。

除文本生成外，许多模型还支持以下功能：

工具调用—— 调用外部工具（如数据库查询或 API 调用），并将结果应用于回复中。
结构化输出—— 约束模型的输出遵循指定格式。
多模态能力—— 处理并返回文本以外的数据，如图像、音频和视频。
推理能力—— 模型通过多步推理得出结论。

模型是智能体的推理引擎，驱动智能体的决策过程，决定调用哪些工具、如何解读结果以及何时给出最终答案。

你所选择模型的质量与能力，直接影响智能体的基础可靠性和运行性能。不同模型擅长不同任务 —— 部分模型更擅长遵循复杂指令，部分擅长结构化推理，还有部分支持更大的上下文。

当然。以上是废话。

2. Basic Usage

Models有两种方法使用，一种是作为agent的大脑，详见上一章；另一个是在agent loop外直接被调用

(1) 初始化模型

感觉其实不用我多说什么，主要用的就是init_chat_model和Model Class两种方案，在上上一章中已经尝试并使用过。前者是通用的创建方法，后者是特定代理商的。

import os
from langchain.chat_models import init_chat_model

os.environ["OPENAI_API_KEY"] = "sk-..."

model = init_chat_model("gpt-5.2")

import os
from langchain_openai import ChatOpenAI

os.environ["OPENAI_API_KEY"] = "sk-..."

model = ChatOpenAI(model="gpt-5.2")

(2) 支持的模型

看这里，主流的都支持。

3. 参数

Chat Model 在初始化时可以传入一系列参数来控制模型行为。不同模型、不同 Provider 支持的参数并不完全一致，但有一些是比较通用的。

常见参数如下：

model
指定要使用的具体模型名称或标识符。
有时也可以把 provider 一起写进去，比如 openai:gpt-5。
api_key
用于向模型提供商鉴权的密钥。
一般通过环境变量读取，也可以在初始化时直接传入。
temperature
控制输出的随机性。
值越高，回答通常越发散、越有创造性；值越低，回答越稳定、越接近确定性输出。
max_tokens
限制模型本次最多生成多少 token。
可以粗略理解为控制“回复最长能写多长”。
timeout
请求超时时间。
如果超过设定时间模型还没有返回结果，请求就会被取消。
max_retries
请求失败时的最大重试次数。
常见的网络超时、限流（429）或服务端错误（5xx）通常会自动重试；像 401、404 这类客户端错误一般不会重试。

使用 init_chat_model 时，这些参数通常可以直接作为关键字参数传入，例如：

from langchain.chat_models import init_chat_model

model = init_chat_model(
    "claude-sonnet-4-6",
    temperature=0.7,
    timeout=30,
    max_tokens=1000,
    max_retries=6,
)

4. 调用 (Invocation)

必须调用聊天模型才能生成输出结果。共有三种主要的调用方法，每种方法适用于不同的使用场景。

(1) Invoke

可以记得，agent就是使用invoke来创建一次回答的对象，model同样如此，很简单：

response = model.invoke("Why do parrots have colorful feathers?")
print(response)

可以向对话模型提供消息列表来表示对话历史。每条消息都带有一个角色，模型通过该角色来标识对话中消息的发送方。这里之后会在Messages组件中细聊：

conversation = [
    {"role": "system", "content": "You are a helpful assistant that translates English to French."},
    {"role": "user", "content": "Translate: I love programming."},
    {"role": "assistant", "content": "J'adore la programmation."},
    {"role": "user", "content": "Translate: I love building applications."}
]

response = model.invoke(conversation)
print(response)  # AIMessage("J'adore créer des applications.")

或：

from langchain.messages import HumanMessage, AIMessage, SystemMessage

conversation = [
    SystemMessage("You are a helpful assistant that translates English to French."),
    HumanMessage("Translate: I love programming."),
    AIMessage("J'adore la programmation."),
    HumanMessage("Translate: I love building applications.")
]

response = model.invoke(conversation)
print(response)  # AIMessage("J'adore créer des applications.")

我们这里，直接print来看一下AIMessage里面是什么内容。

AIMessage(
    content="J'adore creer des applications.",
    additional_kwargs={
        "refusal": None
    },
    response_metadata={
        "token_usage": {
            "completion_tokens": 7,
            "prompt_tokens": 48,
            "total_tokens": 55,
            "completion_tokens_details": {
                "accepted_prediction_tokens": 0,
                "audio_tokens": 0,
                "reasoning_tokens": 0,
                "rejected_prediction_tokens": 0
            },
            "prompt_tokens_details": {
                "audio_tokens": 0,
                "cached_tokens": 0
            }
        },
        "model_provider": "openai",
        "model_name": "gpt-4o-mini-2024-07-18",
        "system_fingerprint": "fp_eb37e061ec",
        "id": "chatcmpl-DNt7u2YGuVpI3LG99vAdG3aG486te",
        "finish_reason": "stop",
        "logprobs": None
    },
    id="lc_run--019d2d8e-ad56-7d90-9180-83c9de41a83b-0",
    tool_calls=[],
    invalid_tool_calls=[],
    usage_metadata={
        "input_tokens": 48,
        "output_tokens": 7,
        "total_tokens": 55,
        "input_token_details": {
            "audio": 0,
            "cache_read": 0
        },
        "output_token_details": {
            "audio": 0,
            "reasoning": 0
        }
    }
)

可以看到，其中 content 表示模型真正回复的文本；usage_metadata 是 LangChain 统一整理后的 token 使用情况；response_metadata 则更多保存模型提供商返回的原始元数据，例如模型名称、结束原因、logprobs 和更细粒度的 token usage 信息。如果本次回复涉及工具调用，还会在 tool_calls 中体现；如果没有，则通常是空列表。

现在你应该理解Model那一章从哪里得到的元数据字段（说实话不明白为什么官网Messages要放在Model后面呢，还有为什么Agents要放在Messages前面）。

对比一下Agents，它被invoke的时候一般返回agent当前的最终state，这是一个结果字典。我们用response["messages"][-1]看到的才是AIMessage。

如果这里print发现直接返回直接就是字符串，检查一下用的是不是对话模型。LangChain的对话模型都是用Chat作为前缀。

(2) Stream

大多数模型能够在生成输出内容的同时进行流式传输。通过逐步展示输出结果，流式传输可显著提升用户体验，对于较长的响应尤为明显。

调用stream()会返回一个迭代器，该迭代器会在输出片段生成时逐一产出。你可以使用循环来实时处理每个片段：

for chunk in model.stream("Why do parrots have colorful feathers?"):
    print(chunk.text, end="|", flush=True)

与invoke()不同，该方法会在模型完成完整响应生成后返回单个AIMessage；而stream()会返回多个AIMessageChunk对象，每个对象均包含输出文本的一部分。重要的是，流中的每个数据块都可通过累加方式拼接成完整消息：

full = None  # None | AIMessageChunk
for chunk in model.stream("What color is the sky?"):
    full = chunk if full is None else full + chunk
    print(full.text)

# The
# The sky
# The sky is
# The sky is typically
# The sky is typically blue
# ...

print(full.content_blocks)
# [{"type": "text", "text": "The sky is typically blue..."}]

这里最终生成的消息可以和invoke()生成的消息同等对待 —— 例如，可将其整合至消息历史中，并作为对话上下文回传给模型。

(3) Batch

将一批独立的模型请求进行批处理，能够显著提升性能并降低成本，因为处理过程可以并行执行：

responses = model.batch([
    "Why do parrots have colorful feathers?",
    "How do airplanes fly?",
    "What is quantum computing?"
])
for response in responses:
    print(response)

默认情况下batch()只会返回整个批次的最终输出结果，没如果需要每次都有结果需要用batch_as_completed()：

for response in model.batch_as_completed([
    "Why do parrots have colorful feathers?",
    "How do airplanes fly?",
    "What is quantum computing?"
]):
    print(response)

结果可能会乱序返回，但每个结果都会包含输入索引，可根据需要通过匹配来还原原始顺序。

5. 工具调用 (Tool calling)

模型可以请求调用工具来执行各类任务，例如从数据库获取数据、进行网络搜索或运行代码。工具由以下两部分配对组成：

一个schema，包含工具名称、描述以及 / 或者参数定义（通常为 JSON 模式）
用于执行的函数或协程。

注意function calling和tool calling在这里表示一个意思，混用。

下面是用户与模型之间的基本工具调用流程：

sequenceDiagram
    participant U as User
    participant M as Model
    participant T as Tools

    U->>M: "What's the weather in SF and NYC?"
    M->>M: Analyze request & decide tools needed

    par Parallel Tool Calls
        M->>T: get_weather("San Francisco")
        M->>T: get_weather("New York")
    end

    par Tool Execution
        T-->>M: SF weather data
        T-->>M: NYC weather data
    end

    M->>M: Process results & generate response
    M->>U: "SF: 72°F sunny, NYC: 68°F cloudy"

模型要想使用自定义工具，必须要通过bind_tools方法将其绑定，那么在后续调用过程中，模型就可以根据需要选择调用任意已绑定的工具。比如：

from langchain.tools import tool

@tool
def get_weather(location: str) -> str:
    """Get the weather at a location."""
    return f"It's sunny in {location}."


model_with_tools = model.bind_tools([get_weather])

response = model_with_tools.invoke("What's the weather like in Boston?")
for tool_call in response.tool_calls:
    # View tool calls made by the model
    print(f"Tool: {tool_call['name']}")
    print(f"Args: {tool_call['args']}")

在绑定用户自定义工具时，模型的响应会包含一个请求以执行工具。当独立于智能体使用模型时，需要由你自行执行所请求的工具，并将结果返回给模型，供其在后续推理中使用。而在使用智能体时，智能体循环会为你自动处理工具执行流程。（所以工具还是写在Agent里面好，咳咳）

6. Structured output

格式化输出有三种方式可以做，Pydantic、TypedDict和Json Schema，定义好了作为参数传给 model.with_structured_output函数即可。

7. Advanced topic

(1) Model profiles

LangChain 聊天模型可以通过profile属性公开一个包含其所支持功能与特性的字典，让应用根据模型能力动态适配（这部分数据很多来自 models.dev，并且这是 beta feature，格式后面可能会变）：

model.profile
# {
#   "max_input_tokens": 400000,
#   "image_inputs": True,
#   "reasoning_output": True,
#   "tool_calling": True,
#   ...
# }

(2) 多模态 (Multimodal)

部分模型能够处理并返回图像、音频和视频等非文本数据。你可以通过提供内容块（这一部分在Message中介绍）来向模型传递非文本数据。

然后有些模型还可以返回多模态数据，生成的AIMessage将包含带有多模态类型的内容块

response = model.invoke("Create a picture of a cat")
print(response.content_blocks)
# [
#     {"type": "text", "text": "Here's a picture of a cat"},
#     {"type": "image", "base64": "...", "mime_type": "image/jpeg"},
# ]

(3) 推理 (Reasoning)

许多模型支持推理，可以选择呈现推理过程。流式推理输出如下：

for chunk in model.stream("Why do parrots have colorful feathers?"):
    reasoning_steps = [r for r in chunk.content_blocks if r["type"] == "reasoning"]
    print(reasoning_steps if reasoning_steps else chunk.text)

Complete展现推理如下：

response = model.invoke("Why do parrots have colorful feathers?")
reasoning_steps = [b for b in response.content_blocks if b["type"] == "reasoning"]
print(" ".join(step["reasoning"] for step in reasoning_steps))

(4) 本地大模型

这……好像跟LangChain本身关系不大，如果用到的时候查一下接法。

(5) Prompt catching

也就是提示词缓存技术，以降低重复处理相同令牌时的延迟和成本。不同模型的供应商不同，OpenAI和Gemini其实等提供了隐式提示词缓存。服务器提供商也允许用户手动指定缓存节点，比如ChatOpenAI的prompt_cache_key。

(6) 服务端工具调用

pass

(7) 限额

pass

(8) Base URL and proxy settings

这个特性我们之前就用过，就是第三方

model = init_chat_model(
    model="MODEL_NAME",
    model_provider="openai",
    base_url="BASE_URL",
    api_key="YOUR_API_KEY",
)

(9) Log probabilities

做实验的时候可能会需要。某些模型可通过在初始化模型时设置logprobs参数，配置为返回代表指定令牌概率的令牌级对数概率：

model = init_chat_model(
    model="gpt-4.1",
    model_provider="openai"
).bind(logprobs=True)

response = model.invoke("Why do parrots talk?")
print(response.response_metadata["logprobs"])

返回回来的将是这样的结果：

{
  "content": [...],
  "refusal": None
}

content是模型生成出来的 token 明细列表，refusal是否触发拒答，这里是 None，说明没有拒答。

而content中的每一项，大概是这样的：

{
  "token": "Par",
  "bytes": [80, 97, 114],
  "logprob": -5.512236498361744e-07,
  "top_logprobs": []
}

字段的意思是，这一个token对应的字节显示，还有选中这个token的对数概率，越接近0越稳定。粗略可以记为0附近很有把握，-0.1到-1还比较合理，-2以下没这么稳了。（-0.69对应的概率差不多是0.5，-2.3对应的差不多是0.1）。

另外，注意到像 logprobs 这类更偏 provider-specific 的信息，则通常放在 response_metadata 中

(10) Token usage

多家模型提供商会在调用响应中返回令牌使用信息。如果该信息可用，将会被包含在对应模型生成的AIMessage对象中。但是不能按照response.tokens这种方式读，因为他们不是AIMessage的顶层属性，而是在usage_metadata中。

可以使用回调函数或上下文管理器来跟踪应用程序中不同模型的总令牌使用数量，如下所示：

from langchain.chat_models import init_chat_model
from langchain_core.callbacks import UsageMetadataCallbackHandler

model_1 = init_chat_model(model="gpt-4.1-mini")
model_2 = init_chat_model(model="claude-haiku-4-5-20251001")

callback = UsageMetadataCallbackHandler()
result_1 = model_1.invoke("Hello", config={"callbacks": [callback]})
result_2 = model_2.invoke("Hello", config={"callbacks": [callback]})
print(callback.usage_metadata)

或

from langchain.chat_models import init_chat_model
from langchain_core.callbacks import get_usage_metadata_callback

model_1 = init_chat_model(model="gpt-4.1-mini")
model_2 = init_chat_model(model="claude-haiku-4-5-20251001")

with get_usage_metadata_callback() as cb:
    model_1.invoke("Hello")
    model_2.invoke("Hello")
    print(cb.usage_metadata)

我们会得到如下的统计信息：

{
    'gpt-4.1-mini-2025-04-14': {
        'input_tokens': 8,
        'output_tokens': 10,
        'total_tokens': 18,
        'input_token_details': {'audio': 0, 'cache_read': 0},
        'output_token_details': {'audio': 0, 'reasoning': 0}
    },
    'claude-haiku-4-5-20251001': {
        'input_tokens': 8,
        'output_tokens': 21,
        'total_tokens': 29,
        'input_token_details': {'cache_read': 0, 'cache_creation': 0}
    }
}

(11) Invocation config

调用模型时，你可以通过config参数，使用RunnableConfig字典传递额外配置。这能够在运行时对执行行为、回调函数以及元数据追踪进行控制，如：

response = model.invoke(
    "Tell me a joke",
    config={
        "run_name": "joke_generation",      # Custom name for this run
        "tags": ["humor", "demo"],          # Tags for categorization
        "metadata": {"user_id": "123"},     # Custom metadata
        "callbacks": [my_callback_handler], # Callback handlers
    }
)

这些配置值在以下场景中尤为实用：

使用LangSmith追踪进行调试
实现自定义日志记录或监控
控制生产环境中的资源使用
追踪复杂流程中的调用过程

(12) Configurable models

你还可以通过指定configurable_fields来创建可在运行时配置的模型。若你未指定模型取值，那么'model'和'model_provider'将默认处于可配置状态。

from langchain.chat_models import init_chat_model

configurable_model = init_chat_model(temperature=0)

configurable_model.invoke(
    "what's your name",
    config={"configurable": {"model": "gpt-5-nano"}},  # Run with GPT-5-Nano
)
configurable_model.invoke(
    "what's your name",
    config={"configurable": {"model": "claude-sonnet-4-6"}},  # Run with Claude
)

LangGraph 应用思路 02：典型工作流与 Agent 模式

Thu, 26 Mar 2026 00:00:00 GMT

用LangGraph实现典型工作模式

这一章介绍常见的工作流和agent模式。

工作流具有预设的代码路径，设计上按特定顺序运行。
智能体则具备动态性，可自主定义执行流程与工具使用方式。

LangGraph 在构建智能体与工作流时具备多项优势，包括持久化、流式输出，同时支持调试以及部署功能。

1. Prompt Chaining

提示词链式调用是指每次大语言模型调用都会处理上一次调用的输出结果。它通常用于执行可拆解为更小、可验证步骤的明确任务。例如：

将文档翻译成不同语言
验证生成内容的一致性
...

from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from IPython.display import Image, display


# Graph state
class State(TypedDict):
    topic: str
    joke: str
    improved_joke: str
    final_joke: str


# Nodes
def generate_joke(state: State):
    """First LLM call to generate initial joke"""

    msg = llm.invoke(f"Write a short joke about {state['topic']}")
    return {"joke": msg.content}


def check_punchline(state: State):
    """Gate function to check if the joke has a punchline"""

    # Simple check - does the joke contain "?" or "!"
    if "?" in state["joke"] or "!" in state["joke"]:
        return "Pass"
    return "Fail"


def improve_joke(state: State):
    """Second LLM call to improve the joke"""

    msg = llm.invoke(f"Make this joke funnier by adding wordplay: {state['joke']}")
    return {"improved_joke": msg.content}


def polish_joke(state: State):
    """Third LLM call for final polish"""
    msg = llm.invoke(f"Add a surprising twist to this joke: {state['improved_joke']}")
    return {"final_joke": msg.content}


# Build workflow
workflow = StateGraph(State)

# Add nodes
workflow.add_node("generate_joke", generate_joke)
workflow.add_node("improve_joke", improve_joke)
workflow.add_node("polish_joke", polish_joke)

# Add edges to connect nodes
workflow.add_edge(START, "generate_joke")
workflow.add_conditional_edges(
    "generate_joke", check_punchline, {"Fail": "improve_joke", "Pass": END}
)
workflow.add_edge("improve_joke", "polish_joke")
workflow.add_edge("polish_joke", END)

# Compile
chain = workflow.compile()

# Show workflow
display(Image(chain.get_graph().draw_mermaid_png()))

# Invoke
state = chain.invoke({"topic": "cats"})
print("Initial joke:")
print(state["joke"])
print("\n--- --- ---\n")
if "improved_joke" in state:
    print("Improved joke:")
    print(state["improved_joke"])
    print("\n--- --- ---\n")

    print("Final joke:")
    print(state["final_joke"])
else:
    print("Final joke:")
    print(state["joke"])

flowchart TD
    A([START]) --> B[generate_joke<br/>根据 topic 生成初始 joke]

    B --> C{check_punchline<br/>joke 是否包含 ? 或 !}

    C -- Pass --> D([END<br/>直接输出 joke])
    C -- Fail --> E[improve_joke<br/>基于 joke 做改写]
    E --> F[polish_joke<br/>基于 improved_joke 再润色]
    F --> G([END<br/>输出 final_joke])

    B -.-> H[(state.joke)]
    E -.-> I[(state.improved_joke)]
    F -.-> J[(state.final_joke)]

2. Parallelization

借助并行化，大语言模型可同时处理一项任务。实现方式包括同时运行多个独立子任务，或多次运行同一任务以校验不同输出结果。并行化通常用于：

拆分子任务并并行执行，从而提升处理速度
多次运行任务以校验不同输出结果，从而提高结果可信度

3. Routing

路由工作流会处理输入内容，然后将其导向对应上下文的特定任务。这使你能够为复杂任务定义专用流程。例如，一个用于解答产品相关问题的工作流，可先处理问题类型，再将请求路由至定价、退款、退换货等专属处理流程。

from typing_extensions import Literal
from langchain.messages import HumanMessage, SystemMessage


# Schema for structured output to use as routing logic
class Route(BaseModel):
    step: Literal["poem", "story", "joke"] = Field(
        None, description="The next step in the routing process"
    )


# Augment the LLM with schema for structured output
router = llm.with_structured_output(Route)


# State
class State(TypedDict):
    input: str
    decision: str
    output: str


# Nodes
def llm_call_1(state: State):
    """Write a story"""

    result = llm.invoke(state["input"])
    return {"output": result.content}


def llm_call_2(state: State):
    """Write a joke"""

    result = llm.invoke(state["input"])
    return {"output": result.content}


def llm_call_3(state: State):
    """Write a poem"""

    result = llm.invoke(state["input"])
    return {"output": result.content}


def llm_call_router(state: State):
    """Route the input to the appropriate node"""

    # Run the augmented LLM with structured output to serve as routing logic
    decision = router.invoke(
        [
            SystemMessage(
                content="Route the input to story, joke, or poem based on the user's request."
            ),
            HumanMessage(content=state["input"]),
        ]
    )

    return {"decision": decision.step}


# Conditional edge function to route to the appropriate node
def route_decision(state: State):
    # Return the node name you want to visit next
    if state["decision"] == "story":
        return "llm_call_1"
    elif state["decision"] == "joke":
        return "llm_call_2"
    elif state["decision"] == "poem":
        return "llm_call_3"


# Build workflow
router_builder = StateGraph(State)

# Add nodes
router_builder.add_node("llm_call_1", llm_call_1)
router_builder.add_node("llm_call_2", llm_call_2)
router_builder.add_node("llm_call_3", llm_call_3)
router_builder.add_node("llm_call_router", llm_call_router)

# Add edges to connect nodes
router_builder.add_edge(START, "llm_call_router")
router_builder.add_conditional_edges(
    "llm_call_router",
    route_decision,
    {  # Name returned by route_decision : Name of next node to visit
        "llm_call_1": "llm_call_1",
        "llm_call_2": "llm_call_2",
        "llm_call_3": "llm_call_3",
    },
)
router_builder.add_edge("llm_call_1", END)
router_builder.add_edge("llm_call_2", END)
router_builder.add_edge("llm_call_3", END)

# Compile workflow
router_workflow = router_builder.compile()

# Show the workflow
display(Image(router_workflow.get_graph().draw_mermaid_png()))

# Invoke
state = router_workflow.invoke({"input": "Write me a joke about cats"})
print(state["output"])

flowchart TD
    A([START<br/>输入 input]) --> B[llm_call_router<br/>LLM 进行结构化路由判断]

    B --> C{route_decision<br/>decision = story / joke / poem}

    C -- story --> D[llm_call_1<br/>生成 story]
    C -- joke --> E[llm_call_2<br/>生成 joke]
    C -- poem --> F[llm_call_3<br/>生成 poem]

    D --> G([END<br/>输出 output])
    E --> G
    F --> G

    B -.-> H[(state.decision)]
    D -.-> I[(state.output)]
    E -.-> I
    F -.-> I

4. Orchestrator-worker

在协调器 - 工作节点架构中，协调器负责：

将任务拆解为子任务
将子任务分配给工作节点执行
整合各工作节点的输出结果形成最终成果

from typing import Annotated, List
import operator


# Schema for structured output to use in planning
class Section(BaseModel):
    name: str = Field(
        description="Name for this section of the report.",
    )
    description: str = Field(
        description="Brief overview of the main topics and concepts to be covered in this section.",
    )


class Sections(BaseModel):
    sections: List[Section] = Field(
        description="Sections of the report.",
    )


# Augment the LLM with schema for structured output
planner = llm.with_structured_output(Sections)

协调器 - 工作流模式十分常见，LangGraph 已内置对该模式的支持。Send API 可动态创建工作节点并向其发送指定输入。每个工作节点拥有独立状态，所有工作节点的输出都会写入一个共享状态键，协调器图可访问该键。这使得协调器能够获取所有工作节点的输出，并将其整合为最终输出。下面的示例会遍历章节列表，并通过 Send API 将每个章节分发给对应工作节点。

from langgraph.types import Send


# Graph state
class State(TypedDict):
    topic: str  # Report topic
    sections: list[Section]  # List of report sections
    completed_sections: Annotated[
        list, operator.add
    ]  # All workers write to this key in parallel
    final_report: str  # Final report


# Worker state
class WorkerState(TypedDict):
    section: Section
    completed_sections: Annotated[list, operator.add]


# Nodes
def orchestrator(state: State):
    """Orchestrator that generates a plan for the report"""

    # Generate queries
    report_sections = planner.invoke(
        [
            SystemMessage(content="Generate a plan for the report."),
            HumanMessage(content=f"Here is the report topic: {state['topic']}"),
        ]
    )

    return {"sections": report_sections.sections}


def llm_call(state: WorkerState):
    """Worker writes a section of the report"""

    # Generate section
    section = llm.invoke(
        [
            SystemMessage(
                content="Write a report section following the provided name and description. Include no preamble for each section. Use markdown formatting."
            ),
            HumanMessage(
                content=f"Here is the section name: {state['section'].name} and description: {state['section'].description}"
            ),
        ]
    )

    # Write the updated section to completed sections
    return {"completed_sections": [section.content]}


def synthesizer(state: State):
    """Synthesize full report from sections"""

    # List of completed sections
    completed_sections = state["completed_sections"]

    # Format completed section to str to use as context for final sections
    completed_report_sections = "\n\n---\n\n".join(completed_sections)

    return {"final_report": completed_report_sections}


# Conditional edge function to create llm_call workers that each write a section of the report
def assign_workers(state: State):
    """Assign a worker to each section in the plan"""

    # Kick off section writing in parallel via Send() API
    return [Send("llm_call", {"section": s}) for s in state["sections"]]


# Build workflow
orchestrator_worker_builder = StateGraph(State)

# Add the nodes
orchestrator_worker_builder.add_node("orchestrator", orchestrator)
orchestrator_worker_builder.add_node("llm_call", llm_call)
orchestrator_worker_builder.add_node("synthesizer", synthesizer)

# Add edges to connect nodes
orchestrator_worker_builder.add_edge(START, "orchestrator")
orchestrator_worker_builder.add_conditional_edges(
    "orchestrator", assign_workers, ["llm_call"]
)
orchestrator_worker_builder.add_edge("llm_call", "synthesizer")
orchestrator_worker_builder.add_edge("synthesizer", END)

# Compile the workflow
orchestrator_worker = orchestrator_worker_builder.compile()

# Show the workflow
display(Image(orchestrator_worker.get_graph().draw_mermaid_png()))

# Invoke
state = orchestrator_worker.invoke({"topic": "Create a report on LLM scaling laws"})

from IPython.display import Markdown
Markdown(state["final_report"])

flowchart TD
    A([START<br/>输入 topic]) --> B[orchestrator<br/>规划报告 sections]

    B --> C{assign_workers<br/>为每个 section 创建一个 worker}

    C --> D[llm_call Worker 1<br/>写 section 1]
    C --> E[llm_call Worker 2<br/>写 section 2]
    C --> F[llm_call Worker N<br/>写 section N]

    D --> G[synthesizer<br/>汇总 completed_sections]
    E --> G
    F --> G

    G --> H([END<br/>输出 final_report])

    B -.-> I[(state.sections)]
    D -.-> J[(state.completed_sections += section.content)]
    E -.-> J
    F -.-> J
    G -.-> K[(state.final_report)]

5. Evaluator-optimizer

在评估器 - 优化器工作流中，一个大语言模型生成响应，另一个则对该响应进行评估。若评估器或人工介入环节判定响应需要优化，系统会提供反馈并重新生成响应。该循环持续进行，直至生成符合要求的响应。

评估器 - 优化器工作流常用于任务存在明确成功标准、但需通过迭代才能达标的场景。例如，两种语言间的文本翻译往往难以一次完美匹配，可能需要多次迭代，才能生成语义一致的译文。

# Graph state
class State(TypedDict):
    joke: str
    topic: str
    feedback: str
    funny_or_not: str


# Schema for structured output to use in evaluation
class Feedback(BaseModel):
    grade: Literal["funny", "not funny"] = Field(
        description="Decide if the joke is funny or not.",
    )
    feedback: str = Field(
        description="If the joke is not funny, provide feedback on how to improve it.",
    )


# Augment the LLM with schema for structured output
evaluator = llm.with_structured_output(Feedback)


# Nodes
def llm_call_generator(state: State):
    """LLM generates a joke"""

    if state.get("feedback"):
        msg = llm.invoke(
            f"Write a joke about {state['topic']} but take into account the feedback: {state['feedback']}"
        )
    else:
        msg = llm.invoke(f"Write a joke about {state['topic']}")
    return {"joke": msg.content}


def llm_call_evaluator(state: State):
    """LLM evaluates the joke"""

    grade = evaluator.invoke(f"Grade the joke {state['joke']}")
    return {"funny_or_not": grade.grade, "feedback": grade.feedback}


# Conditional edge function to route back to joke generator or end based upon feedback from the evaluator
def route_joke(state: State):
    """Route back to joke generator or end based upon feedback from the evaluator"""

    if state["funny_or_not"] == "funny":
        return "Accepted"
    elif state["funny_or_not"] == "not funny":
        return "Rejected + Feedback"


# Build workflow
optimizer_builder = StateGraph(State)

# Add the nodes
optimizer_builder.add_node("llm_call_generator", llm_call_generator)
optimizer_builder.add_node("llm_call_evaluator", llm_call_evaluator)

# Add edges to connect nodes
optimizer_builder.add_edge(START, "llm_call_generator")
optimizer_builder.add_edge("llm_call_generator", "llm_call_evaluator")
optimizer_builder.add_conditional_edges(
    "llm_call_evaluator",
    route_joke,
    {  # Name returned by route_joke : Name of next node to visit
        "Accepted": END,
        "Rejected + Feedback": "llm_call_generator",
    },
)

# Compile the workflow
optimizer_workflow = optimizer_builder.compile()

# Show the workflow
display(Image(optimizer_workflow.get_graph().draw_mermaid_png()))

# Invoke
state = optimizer_workflow.invoke({"topic": "Cats"})
print(state["joke"])

flowchart TD
    A([START<br/>输入 topic]) --> B[llm_call_generator<br/>生成 joke]

    B --> C[llm_call_evaluator<br/>评价 joke 并给出 feedback]

    C --> D{route_joke<br/>funny_or_not?}

    D -- Accepted --> E([END<br/>输出 joke])
    D -- Rejected + Feedback --> B

    B -.-> F[(state.joke)]
    C -.-> G[(state.funny_or_not)]
    C -.-> H[(state.feedback)]

6. Agents

智能体通常由大语言模型实现，通过工具执行操作。它们在持续的反馈循环中运行，适用于问题与解决方案均不可预测的场景。智能体比工作流具有更高的自主性，能够自主决定使用何种工具以及如何解决问题。你仍可定义可用的工具集及智能体的行为准则。

from langgraph.graph import MessagesState
from langchain.messages import SystemMessage, HumanMessage, ToolMessage


# Nodes
def llm_call(state: MessagesState):
    """LLM decides whether to call a tool or not"""

    return {
        "messages": [
            llm_with_tools.invoke(
                [
                    SystemMessage(
                        content="You are a helpful assistant tasked with performing arithmetic on a set of inputs."
                    )
                ]
                + state["messages"]
            )
        ]
    }


def tool_node(state: dict):
    """Performs the tool call"""

    result = []
    for tool_call in state["messages"][-1].tool_calls:
        tool = tools_by_name[tool_call["name"]]
        observation = tool.invoke(tool_call["args"])
        result.append(ToolMessage(content=observation, tool_call_id=tool_call["id"]))
    return {"messages": result}


# Conditional edge function to route to the tool node or end based upon whether the LLM made a tool call
def should_continue(state: MessagesState) -> Literal["tool_node", END]:
    """Decide if we should continue the loop or stop based upon whether the LLM made a tool call"""

    messages = state["messages"]
    last_message = messages[-1]

    # If the LLM makes a tool call, then perform an action
    if last_message.tool_calls:
        return "tool_node"

    # Otherwise, we stop (reply to the user)
    return END


# Build workflow
agent_builder = StateGraph(MessagesState)

# Add nodes
agent_builder.add_node("llm_call", llm_call)
agent_builder.add_node("tool_node", tool_node)

# Add edges to connect nodes
agent_builder.add_edge(START, "llm_call")
agent_builder.add_conditional_edges(
    "llm_call",
    should_continue,
    ["tool_node", END]
)
agent_builder.add_edge("tool_node", "llm_call")

# Compile the agent
agent = agent_builder.compile()

# Show the agent
display(Image(agent.get_graph(xray=True).draw_mermaid_png()))

# Invoke
messages = [HumanMessage(content="Add 3 and 4.")]
messages = agent.invoke({"messages": messages})
for m in messages["messages"]:
    m.pretty_print()

flowchart TD
    A([START<br/>输入 messages]) --> B[llm_call<br/>LLM 决定直接回答还是调用工具]

    B --> C{should_continue<br/>last_message.tool_calls ?}

    C -- Yes --> D[tool_node<br/>执行工具并生成 ToolMessage]
    D --> B

    C -- No --> E([END<br/>输出最终 AIMessage])

    B -.-> F[(AIMessage<br/>可能包含 tool_calls)]
    D -.-> G[(ToolMessage<br/>工具执行结果)]
    E -.-> H[(messages 完整对话历史)]

PyTorch RNN：序列建模与 LSTM 入门

Thu, 26 Mar 2026 00:00:00 GMT

这一篇主要整理自 liuer_pytorch/14-15.ipynb。在前面几篇里，输入大多可以看成“彼此独立的特征向量”；到了序列建模，这个假设就不成立了。

1. 为什么会需要 RNN

课程里给出的切入点很朴素：
如果要根据前几天的天气预测今天的天气，把所有天直接拼成一个长向量喂进全连接层当然可以，但参数会很大，也不自然。

序列任务更在意的是：

前后顺序
上下文依赖
可变长度

这就是 RNN 这类模型出现的原因。

2. RNN 的最小心智

我自己记 RNN，不是先记公式，而是先记这件事：

RNN 不是把整段序列一次性塞进一个全连接层，而是让同一个 Cell 沿时间步重复处理信息。

所以图里那些同色的 RNN Cell，本质上共享的是同一组参数。
时间在往前走，隐藏状态在传递。

3. one-hot 的问题，和 embedding 为什么重要

课程在字符级示例里先用了 one-hot 编码，比如学 "hello" -> "ohlol" 这种简单序列。
然后很快指出 one-hot 的三个问题：

高维（high-dimension）
稀疏（sparse）
硬编码（hardcoded）

这正好引出 embedding。

embedding 的意义不是“把离散 token 变成稠密向量”这么简单，
更关键的是：它允许模型去学习“词和词之间的相对关系”。

4. LSTM 是在解决什么

当序列变长，普通 RNN 很容易碰到长期依赖问题。
课程在这一节里把 LSTM 作为升级版介绍，我觉得最重要的不是立刻背门结构，而是先知道：

普通 RNN 容易遗忘长距离信息
LSTM 引入了更强的记忆与控制机制
它的目的就是让信息保存和遗忘变得更可控

5. 一个完整的小任务：名字-国家分类

在 15.ipynb 里，这个任务很适合做入门示例：

输入是一串字符
输出是一个国家类别
它不是每个时间步都分类，而是整段序列最终分类

所以课程里特别提醒了一点：

因为任务是一句话/一段话之分一个类别，而不是每个词都分一个类别，所以不用保留每个时间步的 outputs，而是使用最终状态 hidden。

这句话非常重要。它让我们知道：

序列任务不一定都是 token-level 任务
有些任务只关心最终整体表示

6. 学 RNN 阶段别急着追复杂架构

我现在回头看，这一阶段最应该建立的是：

为什么序列不能像普通表格特征那样粗暴拼接
隐状态在序列传播里扮演什么角色
one-hot 和 embedding 的区别
什么时候该取每个时间步输出，什么时候只看最终 hidden

如果这些没通，后面看 GRU、Attention、Transformer 也会很容易失去主线。

7. 这一阶段该记住什么

如果只留最核心的几句：

RNN 处理的是有顺序依赖的数据。
同一个 RNN Cell 会沿时间步重复使用。
one-hot 是起点，但 embedding 更适合真实任务。
LSTM 是在解决长期依赖和信息保留问题。

有了这些直觉，再去看更现代的序列模型，就会顺很多。

RAG 索引基础：向量嵌入、相似度与向量数据库

Thu, 26 Mar 2026 00:00:00 GMT

这一篇开始真正进入 RAG 的“索引层”。如果说前面两篇是在准备语料，那么这里就是在回答：这些文本为什么能被表示成向量，又为什么可以被高效检索出来。

RAG - 索引构建

一、向量嵌入

1. 向量嵌入基础

上一章语义分块的时候就用到了语义嵌入模型，简单介绍了一下嵌入的过程。实际上，准确来说向量嵌入（Embedding）是一种将真实世界中复杂、高维的数据对象（如文本、图像、音频、视频等）转换为数学上易于处理的、低维、稠密的连续数值向量的技术。

Embedding 的真正意义在于，它产生的向量不是随机数值的堆砌，而是对数据语义的数学编码。在 Embedding 构建的向量空间中，语义上相似的对象，其对应的向量在空间中的距离会更近；而语义上不相关的对象，它们的向量距离会更远。

我们用以下方式来衡量向量之间的距离（相似度）：

度量方式	核心含义	优点	缺点	适用场景
余弦相似度（Cosine Similarity）	衡量两个向量夹角的余弦值，关注方向是否一致，而不太关注向量长度	对向量长度不敏感，能更好反映语义方向上的相似性；在文本检索和语义搜索中最常用	忽略了向量模长所携带的信息；如果模型特意利用向量长度编码重要性，余弦相似度可能损失这部分信息	语义检索、文本相似度计算、RAG 向量召回的主流选择
点积（Dot Product）	计算两个向量对应维度乘积之和，同时受方向和模长影响	计算高效；当向量已归一化时，与余弦相似度等价；适合大规模向量检索实现	若向量未归一化，结果会受到长度影响，可能把“向量更长”误当成“更相似”	向量已归一化的检索系统；高性能近似最近邻搜索；深度学习训练中的相似度计算
欧氏距离（Euclidean Distance）	衡量两个向量在空间中的直线距离，距离越小表示越接近	几何意义直观，容易理解；适合确实关心“空间位置差异”的任务	对向量尺度敏感；在高维空间中区分度可能下降；文本语义检索中通常不如余弦相似度稳定	低维空间分析、聚类任务、对空间距离本身有明确意义的场景

2. Embedding在RAG中的作用

RAG 的“检索”环节通常以基于 Embedding 的语义搜索为核心。通用流程如下：

离线索引构建：将知识库内文档切分后，使用 Embedding 模型将每个文档块（Chunk）转换为向量，存入专门的向量数据库中。
在线查询检索：当用户提出问题时，使用同一个 Embedding 模型将用户的问题也转换为一个向量。
相似度计算：在向量数据库中，计算“问题向量”与所有“文档块向量”的相似度。
召回上下文：选取相似度最高的 Top-K 个文档块，作为补充的上下文信息，与原始问题一同送给大语言模型（LLM）生成最终答案。

Embedding 的质量直接决定了 RAG 检索召回内容的准确性与相关性。一个优秀的 Embedding 模型能够精准捕捉问题和文档之间的深层语义联系，即使用户的提问和原文的表述不完全一致。

3. Embedding技术

注：由于目前主要关注RAG，本章略写

Word2Vec -> 动态嵌入 -> 更高要求。
主要训练：自监督训练。主流嵌入模型是BERT的变体，所以详细可以看BERT的训练，也就是MLM和NSP那边。
除了原本的训练，还会引入增强效果的训练，比如度量学习、对比学习等。
选择嵌入模型，我们可以从MTEB (Massive Text Embedding Benchmark) 入手，是一个由 Hugging Face 维护的、全面的文本嵌入模型评测基准。它涵盖了分类、聚类、检索、排序等多种任务，并提供了公开的排行榜，为评估和选择嵌入模型提供了重要的参考依据。

针对RAG而言，要格外注意以下维度：

任务 (Task) ：对于 RAG 应用，需要重点关注模型在 Retrieval (检索) 任务下的排名。
语言 (Language) ：模型是否支持你的业务数据所使用的语言？对于中文 RAG，应选择明确支持中文或多语言的模型。
模型大小 (Size) ：模型越大，通常性能越好，但对硬件（显存）的要求也越高，推理速度也越慢。需要根据你的部署环境和性能要求来权衡。
维度 (Dimensions) ：向量维度越高，能编码的信息越丰富，但也会占用更多的存储空间和计算资源。
最大 Token 数 (Max Tokens) ：这决定了模型能处理的文本长度上限。这个参数是你设计文本分块（Chunking）策略时必须考虑的重要依据，块大小不应超过此限制。
得分与机构 (Score & Publisher) ：结合模型的得分排名和其发布机构的声誉进行初步筛选。知名机构发布的模型通常质量更有保障。
成本 (Cost) ：如果是使用 API 服务的模型，需要考虑其调用成本；如果是自部署开源模型，则需要评估其对硬件资源的消耗（如显存、内存）以及带来的运维成本。

当然，我们一般会用基线测试上面几个维度，然后构建私有测评集，迭代优化，选出该场景下最合适的模型。

二、多模态嵌入

偏科普，可跳

现代 AI 的一项重要突破，是将简单的词向量发展成了能统一理解图文、音视频的复杂系统。这一发展建立在注意力机制、Transformer 架构和对比学习等关键技术之上，它们解决了在共享向量空间中对齐不同数据模态的核心挑战。其发展环环相扣：Word2Vec 为 BERT 的上下文理解铺路，而 BERT 又为 CLIP 等模型的跨模态能力奠定了基础……

反正知道最终多模态信息也能被嵌入成高维稠密向量就行了。

三、向量数据库

在前面我们学习了如何使用嵌入模型将文本、图像等非结构化数据转换为高维向量。这些向量是 RAG 系统能够进行语义理解的基础。然而，当向量数量从几百个增长到数百万甚至数十亿时，一个核心问题随之而来：如何快速、准确地从海量向量中找到与用户查询最相似的那几个？

1. 向量数据库的功能

向量数据库的核心价值在于其高效处理海量高维向量的能力。其主要功能可以概括为以下几点：

高效的相似性搜索：这是向量数据库最重要的功能。它利用专门的索引技术（如 HNSW, IVF），能够在数十亿级别的向量中实现毫秒级的近似最近邻（ANN）查询，快速找到与给定查询最相似的数据。
高维数据存储与管理：专门为存储高维向量（通常维度成百上千）而优化，支持对向量数据进行增、删、改、查等基本操作。
丰富的查询能力：除了基本的相似性搜索，还支持按标量字段过滤查询（例如，在搜索相似图片的同时，指定年份 > 2023）、范围查询和聚类分析等，满足复杂业务需求。
可扩展与高可用：现代向量数据库通常采用分布式架构，具备良好的水平扩展能力和容错性，能够通过增加节点来应对数据量的增长，并确保服务的稳定可靠。
数据与模型生态集成：与主流的 AI 框架（如 LangChain, LlamaIndex）和机器学习工作流无缝集成，简化了从模型训练到向量检索的应用开发流程。

2. 向量数据库 vs 传统数据库

传统的数据库（如 MySQL）擅长处理结构化数据的精确匹配查询（例如，WHERE age = 25），但它们并非为处理高维向量的相似性搜索而设计的。在庞大的向量集合中进行暴力、线性的相似度计算，其计算成本和时间延迟无法接受。向量数据库 (Vector Database) 很好的解决了这一问题，它是一种专门设计用于高效存储、管理和查询高维向量的数据库系统。在 RAG 流程中，它扮演着“知识库”的角色，是连接数据与大语言模型的关键桥梁。

维度	向量数据库	传统数据库（RDBMS）
核心数据类型	高维向量（Embeddings）	结构化数据（文本、数字、日期）
查询方式	相似性搜索（ANN）	精确匹配
索引机制	HNSW、IVF、LSH 等 ANN 索引	B-Tree、Hash Index
主要应用场景	AI 应用、RAG、推荐系统、图像 / 语音识别	业务系统（ERP、CRM）、金融交易、数据报表
数据规模	轻松应对千亿级向量	通常在千万到亿级行数据，更大规模需复杂分库分表
性能特点	高维数据检索性能极高，计算密集型	结构化数据查询快，高维数据查询性能呈指数级下降
一致性	通常为最终一致性	强一致性（ACID 事务）

向量数据库的核心是高效处理高维向量的相似性搜索。向量是一组有序的数值，可以表示文本、图像、音频等复杂数据的特征或属性。在 RAG 系统中，向量一般通过嵌入模型将原始数据转换为高维向量表示，比如上一节的图文示例。向量数据库通常采用四层架构，通过存储层、索引层、查询层和服务层的协同工作来实现高效相似性搜索，其中存储层负责存储向量数据和元数据，优化存储效率并支持分布式存储；索引层维护索引算法（HNSW、LSH、PQ等），负责索引的创建与优化，并支持索引调整；查询层处理查询请求，支持混合查询并实现查询优化；服务层管理客户端连接，提供监控和日志能力，并实现安全管理。

主要技术手段包括：

基于树的方法：如 Annoy 使用的随机投影树，通过树形结构实现对数复杂度的搜索
基于哈希的方法：如 LSH（局部敏感哈希），通过哈希函数将相似向量映射到同一“桶”
基于图的方法：如 HNSW（分层可导航小世界图），通过多层邻近图结构实现快速搜索
基于量化的方法：如 Faiss 的 IVF 和 PQ，通过聚类和量化压缩向量

3. 主流数据库介绍

四、FAISS尝试

尝试利用 LangChain 和 FAISS 完成一个完整的“创建 -> 保存 -> 加载 -> 查询”流程。

from langchain_community.vectorstores import FAISS
from langchain_community.embeddings import HuggingFaceEmbeddings
from langchain_core.documents import Document

# 1. 示例文本和嵌入模型
texts = [
    "张三是法外狂徒",
    "FAISS是一个用于高效相似性搜索和密集向量聚类的库。",
    "LangChain是一个用于开发由语言模型驱动的应用程序的框架。"
]
docs = [Document(page_content=t) for t in texts]
embeddings = HuggingFaceEmbeddings(model_name="BAAI/bge-small-zh-v1.5")

# 2. 创建向量存储并保存到本地
vectorstore = FAISS.from_documents(docs, embeddings)

local_faiss_path = "./faiss_index_store"
vectorstore.save_local(local_faiss_path)

print(f"FAISS index has been saved to {local_faiss_path}")

# 3. 加载索引并执行查询
# 加载时需指定相同的嵌入模型，并允许反序列化
loaded_vectorstore = FAISS.load_local(
    local_faiss_path,
    embeddings,
    allow_dangerous_deserialization=True
)

# 相似性搜索
query = "FAISS是做什么的？"
results = loaded_vectorstore.similarity_search(query, k=1)

print(f"\n查询: '{query}'")
print("相似度最高的文档:")
for doc in results:
    print(f"- {doc.page_content}")

LLM 对齐训练：RLHF、奖励模型与规则化分支

Thu, 26 Mar 2026 00:00:00 GMT

从学习笔记一到四, 我们从强化学习的引入基础开始, 慢慢往前推进, 终于是走到了当代算法的门口. 其实, PPO算法很多时候都是初学者的第一选择, 但是我们为了更好理解其来源, 还是从源头进行了学习. 不过, 接下来才是LLM+RL梦开始的地方, 真正将强化学习应用于大模型.

一. LLM对齐家族

在笔记(一)中, 我们就曾经讨论了SFT的对齐鸿沟, 但是开始那些离散的、有限的强化学习方法, 完全没有办法处理我们对齐LLM的需求, 无论是DP, MC还是TD, 又或者后来的DQN, 基于Policy的Reinforce算法 ... 这时, 有一个非常重要的事情 -- TRPO的提出, 它通过目标函数平衡了策略更新和KL散度之间的关系, 确保即使在不可能的更新方向上, 策略性能依然提升. 从这之后, 这一领域各种研究接踵而至.

PPO基于TRPO的思想, 但是用简单的clip函数进行暴力直接限制, 就达到了和GRPO相同的性能, 实际应用中完全超越TRPO. 这种稳定更新+可控偏移的思想启发了很多研究者, 在工程化的思想上, 将强化学习中RL最优解思想, 转化为大模型与人类对齐的优化框架, 开启了整个LLM对齐家族的演化历程.

我们可以现在这里简单描述一下, 图片比较好, 这里就再放了一次:

DPO: 绕过了PPO的显式奖励建模, 直接将人类偏好信号融入策略目标的对齐方法. 它简化了RLHF pipeline, 是近期的重要进展. 后面都是对其的简化和改进.
ReMax (REINFORCE+argmax)在REINFORCE基础上加个baseline, 放弃critic函数; GRPO (Group Relative Policy Optimiztion) 完全摒弃了价值网络, 通过组内相对奖励来估计优势函数; DAPO则这对GRPO进行改进...
RLAIF: 对齐技术路径, 是RLHF的变体, 用AI反馈来代替人类反馈训练奖励模型. Constitutional AI则是RLAIF的具体实现和拓展.
KTO: 在DPO基础上进一步优化, 引入效用函数...

二. 基于人类反馈的强化学习 (Reinforcement Learning from Human Feedback, RLHF)

回忆我们在笔记(一)中讨论的第一个鸿沟, 其实就是基于大语言模型来说的. LLM基于互联网上的大量文本数据训练, 而这其中不有很多不好的数据, 比如Toxic language, Aggressive responses, Providing dangerous information等. 并且LLM通过SFT无法完全理解深层含义, 容易给出意想之外的回答. 我们将这些问题进行一下总结, 就可以发现, 我们期望模型/Agent应该是要符合人类价值观的. 这些重要人类价值观, 有用(Helpful), 诚实(Honest)和无害(Harmless), 有时统称HHH. 现在我们举例一些模型表现不好的情况 (注, knock, knock实际上是一个游戏, LLM没有分辨出深层含义):

1. 最优解问题到与人类对齐

早在2020年, OpenAI的研究人员就发表过一篇论文(Fine-tuning with human feedback), 探讨了如何通过人类反馈进行微调, 训练模型编写文本文章的简短摘要. 结果发现人类反馈微调的模型的反应优于预训练模型和指令微调模型, 甚至超过了人类基准水平.

这种用人类反馈微调语言模型的流行技术, 被称为基于人类反馈的强化学习, 或简称RLHF. 这种技术的令人振奋之处, 在于可以对不同场景的LLMs进行个性化定制, 让模型通过持续的反馈过程学习每个用户的偏好.

下图, 指导智能体动作的策略是LLM; 最终目标是生成被认为与人类偏好相符合的文本; 环境是模型的上下文窗口, 可以通过提示在其中输入文本的空间; 动作是生成文本的行为, 动作空间是Token词汇, 模型可以选择生成输出结果的所有可能Token (LLM决定生成序列中的下个token取决于它在训练期间学到的语言的统计表示; 模型采取的行动也就是选择哪个token, 取决于上下文的提示文本和词汇空间的概率分布).

但是, 获取人类反馈可能既耗时又昂贵, 作为一个实用和可替代的方案, 可以使用一个额外的模型, 被称为奖励模型 (Reward Model, RM), 来分类LLM输出并评估与人类偏好的对齐程度. 我们把人类对于文本的反馈作为标量 (比如是否有毒 ), 可以从少量的人类示例开始, 用传统监督学习方式训练次级模型. 一旦训练完成, 就可以用RM来评估LLM的输出并分配奖励值, 这个奖励值友反过来更新LLM的权重, 训练出一个新的符合人类偏好的版本. 至于模型输出结果评估时权重如何更新, 取决于用于优化策略的算法.

这里, 行动和状态的序列被称为展开 (Rollout), 而不是在经典强化学习中使用的playout. (虽说我貌似之前也就用的rollout没做区分...)

2. 奖励模型 (Reward Model)

首先, 我们要准备一个数据集, 包含了人类的反馈, 这是基础. 我们用一个提示集数据库, 用LLM针对每一个sample生成一个Model Completions.

下一步, 我们需要收集人类标注员对LLM生成结果的反馈. 在收集反馈的过程中, 有以下两步:

定义模型对齐的标准. 比如上述提到的, HHH准则, 例如帮助性和毒性
根据对齐标准, 要求标注员对数据集中的生成结果进行标注

如下图我们以Helpful为例子, 让人工标注了排序. 其中1最有用, 3最无关.

在这之后, 标注员根据“提示词-生成结果”数据集的记录逐一重复这个过程, 从而建立一个可以用来训练奖励模型的数据集, 最终代替人类完成这项工作.

“提示词-生成效果”数据集通常会分配给多个人类标注员, 以确保大家的答案更一致, 降低某个人标记不准确的风险.

另外, 指令越清晰, 得到的反馈就越清晰, 我们为人类标注员编写指示示例. 如下图:

选择标注员时也会倾向于选择那些能代表多元文化和全球观点的人, 在标注前让他们阅读这些内容并且工作中随时参考.

在这之后, 我们根据排名的数据, 转化成两两对比的数据集, 将它们标记为0分或1分, 作为奖励模型的训练数据, 所以会产生N选2组合的数据集, 然后排序让1分的在前面 (奖励模型期待首选的生成结果$y_j$ , 注意这里的1和0是为了排序, 而不是绝对的奖励值).

一个奖励模型, 通常也是一个语言模型. 对于给定的提示词, 奖励模型一般会按照如下过程:

输入: \[提示(prompt) + 完成(completion)] → 语言模型编码器 → 标量输出层 → 奖励分数

而我们训练的时候, 会输入共用promt的两个completion (yj和yk), 得到奖励rj和rk, 由于我们的最终目标是要RM鼓励rj>rk这样的排序, 我们需要一个概率模型来表示yj优于yk的可能性, 再去提高它. 这里非常常用的模型就是Bradley-Terry模型. 它可以说是成对比较(Paired Comparisons) 模型的开山鼻祖. 接下来我们就要插入介绍.

3. Bradley-Terry模型

在生活中, 经常需要对一组对象进行比较和排序, 但是一些比较中无法给出绝对的分数, 不同人的评价标准和尺度不一致, 直接打分有主观上的偏差. 早在1952年, Rank analysis of incomplete block designs: I. The method of paired comparisons中就提出了这类问题的解决方法, 其核心思想就是现在RM中构建目标函数所用到的Bradley-Terry模型.

它假设, 每个对象i都有一个潜在的“能力”用参数$\pi_i$ ($\pi_i$ >0) 表示, 我们可以将其理解为对象i的一种能力或置信度. 当i与j进行对比的时候, i被选择的概率定义为: $$ P \left( i \succ j \right)= \frac{ \pi_{i}}{ \pi_{i}+ \pi_{j}} \tag{2.3.1} $$ 观察可以得知, $\pi_i =\pi_j$ 的时候, 两个对象呗选中的概率相等, 而如果前者远大于后者, 则i基本总是胜出. 这样, 我们只需要根据若干次i于j之间的排序结果, 利用最大似然估计就可以估计到$P \left( i \succ j \right)$ 的概率.

概率论可能有的有点忘了, 当我们只知道采样结果但是不知道概率函数的参数时, 我们可以直接将采样的结果代入函数相乘, 调整未知参数 (求导) 让乘积最大, 这样就可以估计原本不知道的参数. 这个方法的原理直观来看, 是正确的参数 (正确的原本概率函数) 一定会使采样发生的概率最大, 乘积最大. 作为无偏估计, 最大似然估计的方差很小, 当采样数量非常多的时候就接近真实值.

而为了方便计算和归一化, 通常将$\pi_i$ 写成指数形式, $\pi_{i}=e^{ r_{j}}$ (奖励有可能是负数), 所以, 原式子可以写作: $$ P \left( j \succ k \right)= \frac{e^{ r_{j}}}{e^{ r_{j}}+e^{ r_{k}}}=\frac{1}{1+e^{-({r_{j}-r_k})}}=\sigma(r_j-r_k) \tag{2.3.2} $$ 我们写成对数似然函数的形式: $$ \ln L= \sum_{jk}n_{jk} \ln P \left( j>k \right) \tag{2.3.3} $$ 我们需要让P尽可能大, 可以让每个对数似然函数都大, 但是机器学习通常是最小化损失函数, 所以我们将其写成负对数似然的形式, 得到我们需要的损失函数: $$ loss=-log(L)=-log(\sigma(r_j-r_k)) \tag{2.3.4} $$

也就得到了上图中的loss了.

一旦训练完成之后, 就可以将奖励模型作为二元分类器, 为正类和负类提供一组logits (深度学习模型预测过程中的最后一层输出的原始值, 激活之前). 再使用softmax函数得到概率值.

4. 利用强化学习进行微调

通过1-3, 我们已经得到了可以取代人类的RM, 接下来我们就要利用这个RM+强化学习来对LLM进行微调. 过程如下图所示, 我们不断迭代更新Instruct LLM, 将得到的中间过程称为RL-updated LLM. 如果更新顺利, 我们可以看到每次迭代后奖励分数都在提高. 继续这个过程, 直到你的模型的对齐结果达到一定的评估标准 (步长或者阈值) , 最终我们会得到我们需要的Human-aligned LLM .

其中RL algorithm可以选择很多种不同的算法. 而正如前面所说, PPO是其中的热门算法, 需要说明的是, 虽然前面已经介绍过了PPO算法, 但是这里依然要讨论PPO在大语言模型的特定背景下是如何工作的.

5. PPO算法的应用

笔记(四)中已经介绍了PPO算法, 一言以蔽之就是用重要性采样的方式使用旧策略数据更新目前策略, 并用KL散度或者clip函数限制新旧策略差距, 从而达到有效率又稳定的更新.

(1) Policy loss

我们首先把单个时间步t的PPO的策略挪过来: $$ L^{POLICY}=\min \left(\frac{\pi_{\theta}\left(a_{t}|s_{t}\right)}{\pi_{\theta_{old}}\left(a_{t}|s_{t}\right)}\hat{A_t},\right. \left.\text{clip}\left(\frac{\pi_{\theta}\left(a_{t}|s_{t}\right)}{\pi_{\theta_{old}}\left(a_{t}|s_{t}\right)},1-\varepsilon,1+\varepsilon\right)\hat{A_t}\right) \tag{2.5.1} $$ 我们现在要做的就是理解在具体RLHF的情境中, 以上的量分别表示什么. 我们将LLM生成文本的过程看成马尔可夫决策过程, 动作a是模型选择生成的下一个词元 (token), 状态s则是在生成这个词元之前看到的所有上文 (包含prompt和已经生成的词元). 我们的目标是让生成词元的策略变成最优.

$\pi_\theta$ 是正在被训练的新策略 (当前版本的LLM) 在给定$s_t$ 后, 选择下一个词元$a_t$ 的概率. $\pi_{\theta_{old}}$ 是旧策略 (收集这批数据时版本的LLM) 在相同上下文$s_t$ 后, 选择同一个词元$a_t$ 的概率.

$\hat{A_t}$ 就是优势函数的估计, 它衡量的在状态$s_t$ 下选择$a_t$ , 相比在该状态下选择“平均”动作要好多少, 这个前面已经说过, 它基于的是baseline的方法, 将价值转化为优势. 而这个信号, 最终来源于奖励模型, 它会对整个生成的序列 (一个completion) 给出一个分数, 然后通过GAE等技术分配给每一个词元.

(2) Value loss

首先我们需要强调一下, PPO算法属于Actor-Critic框架, 所以有两个可以训练的框架.

其中之一是Actor网络 (策略网络) $\pi_\theta(a|s)$ , 这就是要微调的语言模型本身, 负责决定给定上下文生成什么词, 这个网络是通过$L^{POLICY}$ 和$L^{ENT}$ 来更新.

而另一个就是Critic网络 (价值网络) $V_\phi(s)$ , 这是一个独立的神经网络, 负责预测状态价值, 而不参与文本生成.

在训练中, 对于每个生成序列, 奖励模型RM给出最终奖励R, 然后对于序列中的每个位置, 都会计算折扣回报$R_t$ , 我们最终让Critic网络的预测更加接近这个实际回报. $$ {L^{VF}}=\frac{1}{2}\left|V_{\theta}(s)-\left(\sum_{t=0}^{T}\gamma^{t} r_{t}\mid s_{0}=s\right)\right|_{2}^{2} \tag{2.5.2} $$ 我们已经有了RM来给出整个序列的奖励, 但是PPO算法中, 是需要每个时间步 (每生成每一个token后) 的奖励.

我们来举个例子, 假设真实情况下, A dog is a奖励为0.34, A dog is a furry奖励是1.23, A dog is a furry animal奖励是1.87, 所以总奖励真实值为1.87. 我们来看看细致的过程:

初始化
数据(序列)收集
获得奖励
计算回报
Critic网络预测
计算Value Loss更新Critic
计算优势函数
计算策略损失并更新Actor
熵正则化
整体效果

(3) Entropy loss

$$ L^{\mathit{ENT}}=\mathrm{entropy}\left(\pi_{\theta}\left(\cdot\mid s_{t} \right)\right) \tag{2.5.3} $$ 这里还有一个组件, 熵损失 (Entropy Loss). 当策略损失模型将模型向对齐目标移动时, 熵允许模型保持创造性. 如果低熵状态下, 可能总会按照同样的方式来生成词语. 这有点类似于LLM的温度设置, 不同的是温度在推理时影响模型的创新性, 而熵则是在训练期间就影响模型的创新性.

(4) PPO目标

接下来, 我们对PPO在RLHF中的公式进行总结, 它是一个由三个部分组成的公式, 为了理解, 我们现在再次总结其中各个量在RLHF中的应用.

策略损失: 它来自于PPO算法本身, 是策略优化的核心, 可以看成AC框架的Actor部分, 用于update原本的LLM, 从而使模型倾向于生成能获得高奖励的文本.
价值损失: 它来自于Critic网络的训练目标.
熵正则项

5. 奖励投机行为 (reward hacking)

有时候, 代理通过选择使其获得最大奖励的行为来欺骗系统, 即使这些行动并不符合原始的目标. 奖励投机行为可以表现为在输出中加入能得到高分数的单词或短语, 但是却降低了语言的整体质量.

下面的例子中, 为了降低Toxicity, LLM更新权重后加入了很多夸张的短语, LLM也可能通过无意义的、语法不正确的文本, 只是恰好以类似的方式最大化奖励. 为了避免这种行为, 可以用最初的指导的LLM作为性能参考, 冻结其参数, 称为参考模型 (reference model). 然后, 我们在每个prompt生成的completion中将两者每一个生成的词元都比较计算KL散度(这是一个相对计算密集的过程), 然后将这个和Reward一并交给PPO算法.

我们在笔记(五)中说明了PPO有两个重要变种即PPO-Clip和PPO-Penalty. 这里把Reference Model和RL-updated LLM进行KL散度的计算, 然后也交给PPO算法, 实际上可以看成是两者的结合. 这种混合方法更加鲁棒.

这里也可以和PEFT进行结合, 这样只要更新适配器的权重, 而不用更新全部LLM的权重.

6. Constitutional AI

人力是有限的资源, 通常需要数以千计的人来进行标注, 所以扩大人类反馈也是一个研究的方向. 其中一种方法就是Constitutional AI. 这是一套根据管理模式行为的规则和原则来训练模型的策略. 通过和样本提示词结合, 构建了模型的Constitution. 接着, 会教模型自我评估并根据这些准则调整生成结果.

Constitutional AI不仅可以扩大人类反馈的规模, 也可以帮助模型在RLHF中表现更好 -- 向模型提供一组Constitution有助于模型在冲突的利益中找到平衡, 避免意外情况. 比如在某些情景优先考虑有用性而忘记了有害性的控制.

下面是2022年的“Constitutional AI: Harmlessness from AI Feedback”中constitutional principles例子:

在这个流程中, 我们又将SFT给拿了回来. 模型开始会根据宪法原则, 自我批判其初始回答并进行修改, 并通过这个过程, 让模型学会如何依据原则来改进输出.

然后, 我们再进入强化学习的阶段, 一个AI模型 (标注者) 会根据宪法原则, 来对不同回答的偏好进行判断, 基于这些判断来训练一个奖励模型RM, 这就是RLAIF (Reinforce Learning from AI Feedback) 思想的体现. 再之后就和之前的过程一样, 用PPO算法优化策略.

flowchart TD
    A[开始] --> B[“监督学习阶段<br>自我批判与修改”]
    B --> C[“训练奖励模型<br>RLAIF范式”]
    C --> D[“强化学习阶段<br>使用PPO算法优化”]
    D --> E[产出对齐模型]
    
    subgraph 宪法原则
        F[预先定义的原则库]
    end
    
    F --> B
    F --> C

所以, 这里的关键就是怎么用AI来替代人类排序和微调. 我们的方法有以下三个方面:

使用使用高质量的、由人类编写的指令数据对一个大语言模型进行 SFT. 这些数据通常包含了符合人类价值观的复杂推理和判断
让该模型深入学习并理解那套成文的“宪法”原则. 这些原则是具体、可操作的指令, 例如：选择那个更无害、更不会冒犯他人的回答”、 “选择那个更诚实、避免胡编造的回答”、“选择那个更有帮助、更清晰地解决问题的回答”.
训练或引导该模型在做出判断时, 必须输出其推理过程

这样一来, 我们就得到了一个可靠的AI标注者. 我们可以通过这个标注者批量生成偏好数据, 然后用这个偏好数据来训练RM.

现在, 我们终于可以完全看懂2022年Training a Helpful and Harmless Assistant with RLHF论文的图了

FastAPI 扩展层：中间件、CORS 与后台任务

Wed, 25 Mar 2026 00:00:00 GMT

写到这里之后，FastAPI 里的“路由函数”已经不是唯一重点了。请求在进入路由前、离开路由后，还会经过另外一层东西。

1. 中间件的基本形状

import time
from fastapi import FastAPI, Request

app = FastAPI()


@app.middleware("http")
async def add_process_time_header(request: Request, call_next):
    start_time = time.perf_counter()
    response = await call_next(request)
    process_time = time.perf_counter() - start_time
    response.headers["X-Process-Time"] = str(process_time)
    return response

中间件可以直接理解成：

请求先经过它
它再把请求交给路由
路由返回响应后，它还能继续处理响应

所以它特别适合做：

请求耗时统计
日志
统一响应头
跨域

官方中间件页还特地提到，测耗时更适合用 time.perf_counter() 而不是 time.time()。
来源：Middleware 官方页 https://fastapi.tiangolo.com/zh/tutorial/middleware/

2. 多个中间件的顺序

如果有多个中间件，最后添加的会在最外层。

app.add_middleware(MiddlewareA)
app.add_middleware(MiddlewareB)

请求流会是：

请求：MiddlewareB -> MiddlewareA -> 路由
响应：路由 -> MiddlewareA -> MiddlewareB

这一点一开始不容易直觉化，但把它想成洋葱模型就清楚了：后加的包在外面。

3. CORS 不是 FastAPI 特性，而是浏览器跨域规则

很多人第一次碰 CORS 时，会觉得这是框架自带的怪东西。其实本质上它是浏览器的跨域限制，FastAPI 只是提供了一个标准中间件来处理。

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

origins = [
    "http://localhost.tiangolo.com",
    "https://localhost.tiangolo.com",
    "http://localhost",
    "http://localhost:8080",
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

官方文档里有一个特别值得记的细节：

如果 allow_credentials=True
那么 allow_origins、allow_methods、allow_headers 不能都写成 ["*"]

它们必须显式指定。
来源：CORS 官方页 https://fastapi.tiangolo.com/zh/tutorial/cors/

4. CORS 参数真正值得理解的几个

最常用的就是这些：

allow_origins
allow_origin_regex
allow_methods
allow_headers
allow_credentials
expose_headers
max_age

第一次配置时最容易出问题的通常是：

前端地址没写对
明明带 cookie / token，却还在用全通配符

5. `BackgroundTasks` 的位置

后台任务不是任务队列系统，它更像“响应返回后，顺手把一个小尾巴继续做完”。

from fastapi import BackgroundTasks, FastAPI

app = FastAPI()


def write_notification(email: str, message: str = ""):
    with open("log.txt", mode="a") as email_file:
        email_file.write(f"notification for {email}: {message}\\n")


@app.post("/send-notification/{email}")
async def send_notification(email: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(write_notification, email, message="some notification")
    return {"message": "Notification sent in the background"}

它的意思是：

先把响应返回给客户端
再在后台补做一些轻量工作

6. 后台任务也能进依赖系统

官方文档特别提到：

BackgroundTasks 也可以参与依赖注入
在路径函数、依赖、子依赖里声明都可以
FastAPI 会把它们合并到同一个对象上

from typing import Annotated
from fastapi import BackgroundTasks, Depends, FastAPI

app = FastAPI()


def write_log(message: str):
    with open("log.txt", mode="a") as log:
        log.write(message)


def get_query(background_tasks: BackgroundTasks, q: str | None = None):
    if q:
        background_tasks.add_task(write_log, f"found query: {q}\\n")
    return q


@app.post("/send-notification/{email}")
async def send_notification(
    email: str,
    background_tasks: BackgroundTasks,
    q: Annotated[str | None, Depends(get_query)],
):
    background_tasks.add_task(write_log, f"message to {email}\\n")
    return {"message": "Message sent"}

来源：Background Tasks 官方页 https://fastapi.tiangolo.com/zh/tutorial/background-tasks/

7. 这一层的边界

中间件、CORS、后台任务这三件事放在一起很合理，因为它们都属于“不是业务字段本身，但又会围绕请求工作”的层。

它们不像路径参数或请求体那样直接决定接口数据结构，却会很明显地影响：

请求经过的路径
浏览器能不能调通
响应返回后的尾部动作

LangChain 核心组件 02：Messages

Wed, 25 Mar 2026 00:00:00 GMT

官方文档里 Messages 放在 Models 后面、但 Agents 前面，而且很多地方又提前引用它。我这里把它明确放在第二个组件位置，因为模型真正吃进去的上下文，本质上就是消息。

1. 介绍

消息是 LangChain 中模型上下文的基本单元，它们代表模型的输入与输出，在与大语言模型交互时，承载着表征对话状态所需的内容和元数据。

消息是包含以下内容的对象：

角色 - 标识消息类型（例如系统、用户）
内容 - 表示消息的实际内容（如文本、图像、音频、文档等）
元数据 - 可选字段，例如响应信息、消息 ID 和令牌使用量

LangChain 提供了适用于所有模型提供商的标准消息类型，确保无论调用何种模型，行为都保持一致。

2. 基础使用

最简单的应用方法就是invoke模型（或者agent）的时候传入，下面给了用messages包里的传入方法，也可以直接像之前一样写成一个字典：

from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage, AIMessage, SystemMessage

model = init_chat_model("gpt-5-nano")

system_msg = SystemMessage("You are a helpful assistant.")
human_msg = HumanMessage("Hello, how are you?")

# Use with chat models
messages = [system_msg, human_msg]
response = model.invoke(messages)  # Returns AIMessage

(1) 文本提示词

文本提示词是字符串 —— 非常适合无需保留对话历史的简单生成任务。调用也很简单：

response = model.invoke("Write a haiku about spring")

(2) 消息提示词

或者，你也可以通过提供消息对象列表的方式，向模型传入一组消息。

from langchain.messages import SystemMessage, HumanMessage, AIMessage

messages = [
    SystemMessage("You are a poetry expert"),
    HumanMessage("Write a haiku about spring"),
    AIMessage("Cherry blossoms bloom...")
]
response = model.invoke(messages)

只有这样，才能启动多轮对话、加入多模态内容、加入系统提示等。

(3) 字典形式

只是(2)的一种变体，一般写这个更方便：

messages = [
    {"role": "system", "content": "You are a poetry expert"},
    {"role": "user", "content": "Write a haiku about spring"},
    {"role": "assistant", "content": "Cherry blossoms bloom..."}
]
response = model.invoke(messages)

3. 消息类型 (Message types)

System message - 告知模型行为方式并为交互提供上下文
Human message - 代表用户输入以及与模型的交互
AI message - 由模型生成的响应，包含文本内容、工具调用和元数据
Tool message - 代表工具调用的输出结果

(1) System message

SystemMessage是一组初始指令，用于设定模型的行为模式。你可以通过系统消息来设定沟通基调、定义模型角色，并制定回复准则，如下：

from langchain.messages import SystemMessage, HumanMessage

system_msg = SystemMessage("""
You are a senior Python developer with expertise in web frameworks.
Always provide code examples and explain your reasoning.
Be concise but thorough in your explanations.
""")

messages = [
    system_msg,
    HumanMessage("How do I create a REST API?")
]
response = model.invoke(messages)

(2) Human message

HumanMessage代表用户的输入与交互行为。它们可以包含文本、图像、音频、文件以及任意数量的多模态内容。

response = model.invoke([
  HumanMessage("What is machine learning?")
])

也可以给消息添加一些元数据。这个部分需要查看运营商具体支持的字段，如：

human_msg = HumanMessage(
    content="Hello!",
    name="alice",  # Optional: identify different users
    id="msg_123",  # Optional: unique identifier for tracing
)

(3) AI message

AIMessage代表模型调用的输出结果。它们可以包含多模态数据、工具调用以及可供后续访问的服务提供商专属元数据。我们上一章已经拆解过AIMessage里面都有什么了，这里不再细说。

需要注意一点就是不同服务提供方对消息类型的权重分配与语境处理方式各不相同，这意味着有时手动创建一个新的AIMessage对象，并将其插入消息历史中，使其看起来像是由模型生成的，会很有帮助，比如：

from langchain.messages import AIMessage, SystemMessage, HumanMessage

# Create an AI message manually (e.g., for conversation history)
ai_msg = AIMessage("I'd be happy to help you with that question!")

# Add to conversation history
messages = [
    SystemMessage("You are a helpful assistant"),
    HumanMessage("Can you help me?"),
    ai_msg,  # Insert as if it came from the model
    HumanMessage("Great! What's 2+2?")
]

response = model.invoke(messages)

(4) Tool message

对于支持工具调用的模型，AI 消息可以包含工具调用。工具消息用于将单次工具执行的结果回传给模型。

不过工具可以直接生成ToolMessage对象。下面我们展示一个简单示例，具体在Tool那一章细说：

from langchain.messages import AIMessage
from langchain.messages import ToolMessage

# After a model makes a tool call
# (Here, we demonstrate manually creating the messages for brevity)
ai_message = AIMessage(
    content=[],
    tool_calls=[{
        "name": "get_weather",
        "args": {"location": "San Francisco"},
        "id": "call_123"
    }]
)

# Execute tool and create result message
weather_result = "Sunny, 72°F"
tool_message = ToolMessage(
    content=weather_result,
    tool_call_id="call_123"  # Must match the call ID
)

# Continue conversation
messages = [
    HumanMessage("What's the weather in San Francisco?"),
    ai_message,  # Model's tool call
    tool_message,  # Tool execution result
]
response = model.invoke(messages)  # Model processes the result

4. 消息内容 (Message content)

你可以将消息的内容视作发送给模型的数据载荷。消息具备content属性，该属性为松散类型，支持字符串以及无类型对象列表（如字典）。这使得 LangChain 聊天模型能够直接兼容服务商原生结构，例如多模态内容及其他数据。

此外，LangChain 还为文本、推理、引用、多模态数据、服务端工具调用及其他消息内容提供了专用的内容类型。详见下方的content block的说明。

LangChain 聊天模型通过content属性接收消息内容。该属性可包含以下任一形式：

字符串
服务商原生格式的内容块列表
LangChain 标准内容块的列表

这里提供一个多模态的例子：

from langchain.messages import HumanMessage

# String content
human_message = HumanMessage("Hello, how are you?")

# Provider-native format (e.g., OpenAI)
human_message = HumanMessage(content=[
    {"type": "text", "text": "Hello, how are you?"},
    {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
])

# List of standard content blocks
human_message = HumanMessage(content_blocks=[
    {"type": "text", "text": "Hello, how are you?"},
    {"type": "image", "url": "https://example.com/image.jpg"},
])

(1) 标准内容块 (Standard content blocks)

消息对象实现了 content_blocks 属性，该属性会惰性解析 content 属性，将其转换为标准的类型安全表示形式。例如，由 ChatAnthropic 或 ChatOpenAI 生成的消息会包含对应服务商格式的 thinking 或 reasoning 内容块，但可被惰性解析为统一的 ReasoningContentBlock表示形式：

from langchain.messages import AIMessage

message = AIMessage(
    content=[
        {
            "type": "reasoning",
            "id": "rs_abc123",
            "summary": [
                {"type": "summary_text", "text": "summary 1"},
                {"type": "summary_text", "text": "summary 2"},
            ],
        },
        {"type": "text", "text": "...", "id": "msg_abc123"},
    ],
    response_metadata={"model_provider": "openai"}
)
print(message.content_blocks)

打印结果如下，证明被成功解析。

[{'type': 'reasoning', 'id': 'rs_abc123', 'reasoning': 'summary 1'},
 {'type': 'reasoning', 'id': 'rs_abc123', 'reasoning': 'summary 2'},
 {'type': 'text', 'text': '...', 'id': 'msg_abc123'}]

(2) 多模态

多模态指的是处理文本、音频、图像和视频等不同形式数据的能力。LangChain 包含可在不同服务提供商之间通用的此类数据标准类型。

聊天模型能够接收多模态数据作为输入，并将其生成为输出。我们只需要简单的将content的类型设置成需要的类型，比如text、image、file（pdf）、audio、video等。前面不少地方都举过例子。

(3) Content block reference

content_blocks 是 LangChain v1 引入的标准化消息内容表示方式。
它不是对 content 的替代，而是把不同 Provider 的消息内容统一整理成一组带类型的字典，便于跨模型访问和处理。

每个 block 都会带一个 type 字段，常见类型可以分为下面几类。

1. Core

最基础的内容类型。

text
标准文本内容。
常见字段包括：
- type="text"
- text
- annotations
- extras
reasoning
模型的推理内容。
常见字段包括：
- type="reasoning"
- reasoning
- extras

2. Multimodal

用于多模态输入或输出。

image
图片内容。常见字段：
- type="image"
- url / base64
- id
- mime_type
audio
音频内容。常见字段：
- type="audio"
- url / base64
- id
- mime_type
video
视频内容。常见字段：
- type="video"
- url / base64
- id
- mime_type
file
通用文件内容，例如 PDF。常见字段：
- type="file"
- url / base64
- id
- mime_type
text-plain
纯文本文档内容，例如 .txt、.md。常见字段：
- type="text-plain"
- text
- mime_type

3. Tool Calling

和工具调用有关的内容块。

tool_call
普通工具调用。常见字段：
- type="tool_call"
- name
- args
- id
tool_call_chunk
流式输出中的工具调用片段。常见字段：
- type="tool_call_chunk"
- name
- args
- id
- index
invalid_tool_call
无法正确解析的工具调用，一般用于捕获 JSON 解析失败等问题。常见字段：
- type="invalid_tool_call"
- name
- args
- error

4. Server-Side Tool Execution

和服务端工具执行有关的内容块。

server_tool_call
服务端执行的工具调用。常见字段：
- type="server_tool_call"
- id
- name
- args
server_tool_call_chunk
服务端工具调用的流式片段。常见字段：
- type="server_tool_call_chunk"
- id
- name
- args
- index
server_tool_result
服务端工具执行结果。常见字段：
- type="server_tool_result"
- tool_call_id
- id
- status
- output

5. Provider-Specific

用于放置服务商特有、暂时无法标准化的内容。

non_standard
Provider 专有的逃生口。常见字段：
- type="non_standard"
- value

总的来说，content_blocks 的意义就在于：即使不同模型底层返回的原始格式不一样，LangChain 也尽量帮我们统一成一套更稳定的访问方式。

(4) Use with chat models

Chat model 接收一组 messages 作为输入，并通常返回一个 AIMessage 作为输出。
如果消息中包含标准化的 content_blocks，那么我们就可以更稳定地处理文本、推理、多模态数据以及工具调用结果，而不用总是去适配不同 Provider 的原始格式。

不过需要注意的是，content_blocks 主要是 LangChain 提供的一层标准化抽象，它并不意味着所有模型都支持所有类型的内容。像图片、音频、PDF、视频等输入形式，仍然要以具体 Provider 的能力说明为准。

PyTorch 手写 Transformer：从模块拆解到 toy task

Wed, 25 Mar 2026 00:00:00 GMT

这一篇主要整理自 pytorch_using/transformer.py。这份代码的价值不在于“重新发明一个工业级 Transformer”，而在于把 Transformer 拆成可验证、可训练、可调试的模块。

1. 为什么要手写一版 Transformer

直接用 nn.Transformer 当然更快，但我自己一直觉得，想真的理解 Transformer，至少要完整看一遍这些模块是怎么拼起来的：

位置编码
padding mask
causal mask
scaled dot-product attention
multi-head attention
feed-forward
encoder / decoder layer

把这些都走通一遍之后，再回去看高级封装，心里会稳很多。

2. 这份实现统一采用 `batch_first`

代码一开头就明确了形状约定：

token id: [B, S]
embedding 后: [B, S, D]

这个约定非常好，因为后面所有 shape 变化都能围绕它来理解。

3. 位置编码：让模型知道“顺序”

这份实现里的 PositionalEncoding 很标准：

class PositionalEncoding(nn.Module):
    def __init__(self, d_model, max_len=5000):
        super().__init__()
        pe = torch.zeros(max_len, d_model, dtype=torch.float32)
        position = torch.arange(max_len, dtype=torch.float32).unsqueeze(1)
        div_term = torch.exp(
            torch.arange(0, d_model, 2, dtype=torch.float32)
            * (-math.log(10000.0) / d_model)
        )
        pe[:, 0::2] = torch.sin(position * div_term)
        pe[:, 1::2] = torch.cos(position * div_term)
        pe = pe.unsqueeze(0)
        self.register_buffer("pe", pe)

    def forward(self, x):
        s = x.size(1)
        return x + self.pe[:, :s, :]

这段最关键的是：

输入输出都保持 [B, S, D]
位置向量不是参数，而是 buffer
它解决的是“Attention 本身不带顺序感”的问题

4. Mask：谁该被遮住

这份代码把两种最重要的 mask 都单独实现了：

4.1 Padding Mask

def make_padding_mask(seq, pad_id=0):
    mask = (seq == pad_id)
    return mask.unsqueeze(1).unsqueeze(2)

它解决的是：
补齐出来的 PAD 不应该参与有效注意力。

4.2 Causal Mask

def make_causal_mask(seq_len, device=None):
    return (
        torch.triu(torch.ones(seq_len, seq_len, device=device), diagonal=1)
        .unsqueeze(0)
        .unsqueeze(0)
        == 1
    )

它解决的是：
Decoder 在生成当前 token 时，不能偷看未来位置。

5. Attention 的核心主线

这一段我特别喜欢原代码里写的复习清单，因为它几乎就是最短背诵版：

QK^T
/ sqrt(d_k)
masked_fill
softmax
@ V

真正实现就是：

def scaled_dot_product_attention(q, k, v, mask=None):
    d_k = k.size(-1)
    scores = q @ k.transpose(-2, -1) / math.sqrt(d_k)
    if mask is not None:
        scores = scores.masked_fill(mask, float("-inf"))
    attn = F.softmax(scores, dim=-1)
    return attn @ v

这一段如果 shape 能看懂，Transformer 就已经通了一半。

6. Multi-Head Attention 真正增加了什么

多头注意力的重点，不只是“多做几次 attention”，而是：

先把同一个表示投影到不同子空间
每个头学不同的关注模式
最后再拼回来

原代码里把这条 shape 变化写得很清楚：

[B, S, D]
→ [B, S, H, Dh]
→ [B, H, S, Dh]
→ attention
→ [B, S, D]

这是理解多头机制最值得反复看的地方。

7. Encoder / Decoder 是怎么组起来的

这份实现保持了 Transformer 最经典的结构：

EncoderLayer

self-attention
residual + layer norm
FFN
residual + layer norm

DecoderLayer

masked self-attention
cross-attention
FFN
每段后都有 residual + layer norm

这时候 Transformer 就不再神秘了，它就是把这些标准模块一层层堆起来。

8. 用 toy task 跑通：反转序列

我很喜欢这份代码没有直接上复杂任务，而是先做了一个最小的可验证任务：
把输入序列反转。

数据构造函数也写得很清楚：

def generate_reverse_data(batch_size, content_len, vocab_size, pad_id=0, bos_id=1, eos_id=2):
    content = torch.randint(3, vocab_size, (batch_size, content_len))
    bos = torch.full((batch_size, 1), bos_id, dtype=torch.long)
    eos = torch.full((batch_size, 1), eos_id, dtype=torch.long)
    src = torch.concat((bos, content, eos), dim=1)
    reversed_content = torch.flip(content, dims=[1])
    tgt = torch.concat((bos, reversed_content, eos), dim=1)
    tgt_input = tgt[:, :-1]
    tgt_output = tgt[:, 1:]
    return src, tgt_input, tgt_output

这段非常适合理解 seq2seq 训练里的两个关键点：

tgt_input 和 tgt_output 是错位的
Decoder 训练时吃的是前一个位置的真实 token

9. 训练循环和 greedy decode

最后这段代码把完整流程跑通了：

训练时：
- src -> encoder
- tgt_input -> decoder
- logits -> CrossEntropyLoss
推理时：
- 从 BOS 开始
- 每次取最后一个位置的 logits
- 贪心生成下一个 token

这就是最小版的 seq2seq 生成闭环。

10. 这一阶段该记住什么

如果只保留最少几句话：

Transformer 不是黑盒，它是多个标准模块的组合。
位置编码、mask、多头注意力是最关键的三个部件。
理解 shape 变化，比死背公式更重要。
一个 toy task 足够把整条训练与推理链跑通。

我觉得这份手写实现最有价值的地方，不是“性能”，而是它把 Transformer 变成了一套可以亲手拆开的积木。

Milvus 入门：集合、索引与检索流程

Wed, 25 Mar 2026 00:00:00 GMT

前面已经把向量数据库的通用心智搭起来了，这一篇就落到 Milvus 本身，理解它在真实系统里是怎么组织数据和执行搜索的。

RAG - 向量数据库与Milvus基础知识

1. 简介

Milvus 是一个开源的、专为大规模向量相似性搜索和分析而设计的向量数据库。它诞生于 Zilliz 公司，并已成为 LF AI & Data 基金会的顶级项目，在AI领域拥有广泛的应用。

与 FAISS、ChromaDB 等轻量级本地存储方案不同，Milvus 从设计之初就瞄准了生产环境。其采用云原生架构，具备高可用、高性能、易扩展的特性，能够处理十亿、百亿甚至更大规模的向量数据。

官网地址: https://milvus.io/

GitHub: https://github.com/milvus-io/milvus

2. 用Docker部署安装

Docker的使用我另有总结，如果还不熟练可以先看那边复习。

我们可以直接拉下来官方的docker-compose.yml，用wget https://github.com/milvus-io/milvus/releases/download/v2.5.14/milvus-standalone-docker-compose.yml -O docker-compose.yml

我们瞅一眼文件内容：

version: '3.5'

services:
  etcd:
    container_name: milvus-etcd
    image: quay.io/coreos/etcd:v3.5.18
    environment:
      - ETCD_AUTO_COMPACTION_MODE=revision
      - ETCD_AUTO_COMPACTION_RETENTION=1000
      - ETCD_QUOTA_BACKEND_BYTES=4294967296
      - ETCD_SNAPSHOT_COUNT=50000
    volumes:
      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/etcd:/etcd
    command: etcd -advertise-client-urls=http://etcd:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
    healthcheck:
      test: ["CMD", "etcdctl", "endpoint", "health"]
      interval: 30s
      timeout: 20s
      retries: 3

  minio:
    container_name: milvus-minio
    image: minio/minio:RELEASE.2024-05-28T17-19-04Z
    environment:
      MINIO_ACCESS_KEY: minioadmin
      MINIO_SECRET_KEY: minioadmin
    ports:
      - "9001:9001"
      - "9000:9000"
    volumes:
      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/minio:/minio_data
    command: minio server /minio_data --console-address ":9001"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3

  standalone:
    container_name: milvus-standalone
    image: milvusdb/milvus:v2.5.14
    command: ["milvus", "run", "standalone"]
    security_opt:
      - seccomp:unconfined
    environment:
      MINIO_REGION: us-east-1
      ETCD_ENDPOINTS: etcd:2379
      MINIO_ADDRESS: minio:9000
    volumes:
      - ${DOCKER_VOLUME_DIRECTORY:-.}/volumes/milvus:/var/lib/milvus
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"]
      interval: 30s
      start_period: 90s
      timeout: 20s
      retries: 3
    ports:
      - "19530:19530"
      - "9091:9091"
    depends_on:
      - "etcd"
      - "minio"

networks:
  default:
    name: milvus

我们可以看到，Docker 将会自动拉取所需的镜像并启动三个容器：milvus-standalone, milvus-minio, 和 milvus-etcd，其中前者依赖于后两者的，然后将他们放入同一子网起名为milvus。然后注意，standalone通过19530和9091端口提供服务。

3. Milvus的核心组件 - Collection

用一个图书馆例子来比喻Collection的存储方式：

Collection (集合): 相当于一个图书馆，是所有数据的顶层容器。一个 Collection 可以包含多个 Partition，每个 Partition 可以包含多个 Entity。
Partition (分区): 相当于图书馆里的不同区域（如“小说区”、“科技区”），将数据物理隔离，让检索更高效。
Schema (模式): 相当于图书馆的图书卡片规则，定义了每本书（数据）必须登记哪些信息（字段）。
Entity (实体): 相当于一本具体的书，是数据本身。
Alias (别名): 相当于一个动态的推荐书单（如“本周精选”），它可以指向某个具体的 Collection，方便应用层调用，实现数据更新时的无缝切换。

(1) Collection

Collection是Milvus中的最基本数据组织单位，类似于关系型数据库里面的Table。是我们存储、管理和查询向量及相关元数据的容器。所有的数据操作，如插入、删除、查询等，都是围绕 Collection 展开的。

一个Collection由Schema定义

(2) Schema

在创建 Collection 之前，必须先定义它的 Schema。 Schema 规定了 Collection 的数据结构，定义了其中包含的所有字段 (Field) 及其属性。一个设计良好的 Schema 是能够保证数据一致性并提升查询性能。

Schema 通常包含以下几类字段：

主键字段 (Primary Key Field): 每个 Collection 必须有且仅有一个主键字段，用于唯一标识每一条数据（实体）。它的值必须是唯一的，通常是整数或字符串类型。
向量字段 (Vector Field): 用于存储核心的向量数据。一个 Collection 可以有一个或多个向量字段，以满足多模态等复杂场景的需求。
标量字段 (Scalar Field): 用于存储除向量之外的元数据，如字符串、数字、布尔值、JSON 等。这些字段可以用于过滤查询，实现更精确的检索。

上图以一篇新闻文章为例，展示了一个典型的多模态、混合向量 Schema 设计。它将一篇文章拆解为：唯一的 Article (ID)、文本元数据（如 Title、Author Info）、图像信息（Image URL），并为图像和摘要内容分别生成了密集向量（Image Embedding, Summary Embedding）和稀疏向量（Summary Sparse Embedding）。

我们来看看，常见的字段有哪些，他们的作用又是什么：

字段类型	含义	例子
`BOOL`	布尔值	`true/false`
`INT8/16/32/64`	整数	年份、数量、ID
`FLOAT/DOUBLE`	小数	分数、价格、概率
`VARCHAR`	字符串	标题、类别、作者
`JSON`	结构化对象	`{"author":"Tom","year":2024}`
`ARRAY`	数组	标签列表、多个分类
`FLOAT_VECTOR` 等	向量	文本 embedding

(3) Partition

Partition 是 Collection 内部的一个逻辑划分。每个 Collection 在创建时都会有一个名为 _default 的默认分区。我们可以根据业务需求创建更多的分区，将数据按特定规则（如类别、日期等）存入不同分区。

为什么使用分区？

提升查询性能: 在查询时，可以指定只在一个或几个分区内进行搜索，从而大幅减少需要扫描的数据量，显著提升检索速度。
数据管理: 便于对部分数据进行批量操作，如加载/卸载特定分区到内存，或者删除整个分区的数据。

一个 Collection 最多可以有 1024 个分区。合理利用分区是 Milvus 性能优化的重要手段之一。

(4) Alias

Alias (别名) 是为 Collection 提供的一个“昵称”。通过为一个 Collection 设置别名，我们可以在应用程序中使用这个别名来执行所有操作，而不是直接使用真实的 Collection 名称。

为什么使用别名？

安全地更新数据：想象一下，你需要对一个在线服务的 Collection 进行大规模的数据更新或重建索引。直接在原 Collection 上操作风险很高。正确的做法是：
1. 创建一个新的 Collection (collection_v2) 并导入、索引好所有新数据。
2. 将指向旧 Collection (collection_v1) 的别名（例如 my_app_collection）原子性地切换到新 Collection (collection_v2) 上。
代码解耦：整个切换过程对上层应用完全透明，无需修改任何代码或重启服务，实现了数据的平滑无缝升级。

4. Milvus的核心组件 - 索引 (Index)

https://milvus.io/docs/zh/index-explained.md

如果说 Collection 是 Milvus 的骨架，那么索引 (Index) 就是其加速检索的神经系统。从宏观上看，索引本身就是一种为了加速查询而设计的复杂数据结构。对向量数据创建索引后，Milvus 可以极大地提升向量相似性搜索的速度，代价是会占用额外的存储和内存资源。

如下图所示，Milvus 中的索引类型由三个核心部分组成，即数据结构、量化和细化器。量化和精炼器是可选的，但由于收益大于成本的显著平衡而被广泛使用。

在创建索引时，Milvus 会结合所选的数据结构和量化方法来确定最佳扩展率。在查询时，系统会检索topK × expansion rate 候选向量，应用精炼器以更高的精度重新计算距离，最后返回最精确的topK 结果。这种混合方法通过将资源密集型细化限制在候选矢量的过滤子集上，在速度和精确度之间取得了平衡。

数据结构：数据结构是索引的基础层，常见类型包括反转文件（IVF）和基于图的结构（比如HNSW）。
量化(可选)：数据压缩技术，通过降低向量精度来减少内存占用和加速计算。有标量量化（如SQ8）和乘积量化（PQ）。
- 这里简单补充一下，SQ和PQ都是向量压缩/量化技术，但是SQ是把每个维度都单独压缩，而PQ是把整个向量切成多个子向量，每个子向量聚类后在codebook中找一个最接近的值，然后只保存这个值的标号。
- codebook是从真实向量中聚类学出来的（通常是K-means），每个聚类中心会成为一个codebook entry。

flowchart TD
    A[原始训练向量集合] --> B[将每个向量切分为多个子向量]
    B --> C1[子空间 1 的所有子向量]
    B --> C2[子空间 2 的所有子向量]
    B --> C3[子空间 3 的所有子向量]
    B --> C4[子空间 4 的所有子向量]

    C1 --> D1[对子空间 1 做 K-Means 聚类]
    C2 --> D2[对子空间 2 做 K-Means 聚类]
    C3 --> D3[对子空间 3 做 K-Means 聚类]
    C4 --> D4[对子空间 4 做 K-Means 聚类]

    D1 --> E1[得到 Codebook 1<br/>若干聚类中心]
    D2 --> E2[得到 Codebook 2<br/>若干聚类中心]
    D3 --> E3[得到 Codebook 3<br/>若干聚类中心]
    D4 --> E4[得到 Codebook 4<br/>若干聚类中心]

    F[一个新的原始向量] --> G[切分成多个子向量]

    G --> H1[子向量 1]
    G --> H2[子向量 2]
    G --> H3[子向量 3]
    G --> H4[子向量 4]

    E1 --> I1[在 Codebook 1 中寻找最近中心]
    E2 --> I2[在 Codebook 2 中寻找最近中心]
    E3 --> I3[在 Codebook 3 中寻找最近中心]
    E4 --> I4[在 Codebook 4 中寻找最近中心]

    H1 --> I1
    H2 --> I2
    H3 --> I3
    H4 --> I4

    I1 --> J1[记录编号 id1]
    I2 --> J2[记录编号 id2]
    I3 --> J3[记录编号 id3]
    I4 --> J4[记录编号 id4]

    J1 --> K[PQ 编码结果<br/>id1, id2, id3, id4]
    J2 --> K
    J3 --> K
    J4 --> K

    K --> L[存储时只保存编号<br/>大幅减少存储空间]

    K --> M[检索时根据编号回查各个 Codebook]
    E1 --> M
    E2 --> M
    E3 --> M
    E4 --> M

    M --> N[拼接出近似向量]
    N --> O[用于近似距离计算与 ANN 检索]

    P[核心思想] --> Q[不用保存原始浮点向量]
    P --> R[只保存每个子向量最接近的中心编号]
    P --> S[用少量精度损失换取更高压缩率与检索效率]

结果精炼(可选)：量化本身就是有损的。为了保持召回率，量化始终会产生比所需数量更多的前 K 个候选结果，这使得精炼器可以使用更高的精度从这些候选结果中进一步选择前 K 个结果，从而提高召回率。

Milvus 支持对标量字段和向量字段分别创建索引。

标量字段索引：主要用于加速元数据过滤，对于标量字段，始终使用推荐的索引类型即可。
向量字段索引：这是 Milvus 的核心。选择合适的向量索引是在查询性能、召回率和内存占用之间做出权衡的艺术。

现在给出字段数据类型与适用索引类型之间的适应关系：

字段数据类型	适用索引类型
`FLOAT_VECTOR`	平面、`IVF_FLAT`、`IVF_SQ8`、`IVF_PQ`、`IVF_RABITQ`、`HNSW`、`HNSW_SQ`、`HNSW_PQ`、`HNSW_PRQ`、`DISKANN`、`SCANN`、`AISAQ`、`GPU_CAGRA`、`GPU_IVF_FLAT`、`GPU_IVF_PQ`、`GPU_BRUT_FORCE`
`FLOAT16_VECTOR`	平面、`IVF_FLAT`、`IVF_SQ8`、`IVF_PQ`、`IVF_RABITQ`、`HNSW`、`HNSW_SQ`、`HNSW_PQ`、`HNSW_PRQ`、`DISKANN`、`SCANN`、`AISAQ`、`GPU_CAGRA`、`GPU_IVF_FLAT`、`GPU_IVF_PQ`、`GPU_BRUT_FORCE`
`BFLOAT16_VECTOR`	平面、`IVF_FLAT`、`IVF_SQ8`、`IVF_PQ`、`IVF_RABITQ`、`HNSW`、`HNSW_SQ`、`HNSW_PQ`、`HNSW_PRQ`、`DISKANN`、`SCANN`、`AISAQ`、`GPU_CAGRA`、`GPU_IVF_FLAT`、`GPU_IVF_PQ`、`GPU_BRUT_FORCE`
`INT8_VECTOR`	平面、`IVF_FLAT`、`IVF_SQ8`、`IVF_PQ`、`IVF_RABITQ`、`HNSW`、`HNSW_SQ`、`HNSW_PQ`、`HNSW_PRQ`、`DISKANN`、`SCANN`、`AISAQ`、`GPU_CAGRA`、`GPU_IVF_FLAT`、`GPU_IVF_PQ`、`GPU_BRUT_FORCE`
二进制向量	`BIN_FLAT`、`BIN_IVF_FLAT`、`MINHASH_LSH`
稀疏浮点矢量	稀疏反转索引
`VARCHAR`	反转（推荐）、`BITMAP`、三角形
`BOOL`	`BITMAP`（推荐）、反转
`INT8`	反转、`STL_SORT`
`INT16`	反转、`STL_SORT`
`INT32`	反转、`STL_SORT`
`INT64`	反转、`STL_SORT`
`FLOAT`	反转
`DOUBLE`	反转
数组（`BOOL`、`INT8/16/32/64` 和 `VARCHAR` 类型的元素）	`BITMAP`（推荐）
数组（`BOOL`、`INT8/16/32/64`、`FLOAT`、`DOUBLE` 和 `VARCHAR` 类型的元素）	反转
`JSON`	反转

(1) 索引算法 - 标量

前面提到，对于标量索引，直接用推荐值即可。这里学习一下标量索引是怎么做的：

标量索引方法	具体解释	主要用处	适合字段	优点 / 局限
反转索引（Inverted Index）	为每个字段值维护一个倒排表，记录“这个值出现在哪些记录里”	等值过滤、关键词过滤、多条件筛选	`VARCHAR`、`JSON`、`ARRAY`、部分数值字段	优点：等值查询快，适合文本和标签类过滤。局限：对连续数值范围查询通常不如排序类索引直接
BITMAP 索引	用位图记录某个值在每条记录中是否出现，1 表示有，0 表示无	低基数字段过滤、多条件组合查询	`BOOL`、枚举类字段、部分数组字段	优点：集合交并运算非常快。局限：字段取值特别多时不划算
STL_SORT	按字段值排序保存，查询时通过范围定位快速找到满足条件的记录	数值范围查询、排序、区间筛选	`INT8`、`INT16`、`INT32`、`INT64`	优点：范围查询高效。局限：更偏数值型场景，不适合复杂文本检索

有些地方解释一下。首先，反转索引的具体做法，其实就是维持一个“值 -> 文档列表”的索引。比如文档1、3的类型是medical，就会medical->[1,3]，查询的时候会直接那这个列表，不用扫记录；如果是多条件，比如AND，那就做交集。

位图，学过OS的应该很熟悉，就是将值对应到一串0/1。

STL_SORT是先将字段值排好序，然后直接用二分查找做范围过滤，适合数值字段。查大于等于这样的数字也是先二分查这个数字的左边界，然后从这里往后查。

稀疏反转索引

(2) 索引算法 - 向量

Milvus 提供了多种向量索引算法，以适应不同的应用场景。以下是几种最核心的类型：

FLAT (精确查找)
- 原理：暴力搜索（Brute-force Search）。它会计算查询向量与集合中所有向量之间的实际距离，返回最精确的结果。
- 优点：100% 的召回率，结果最准确。
- 缺点：速度慢，内存占用大，不适合海量数据。
- 适用场景：对精度要求极高，且数据规模较小（百万级以内）的场景。
IVF 系列 (倒排文件索引)
- 原理：类似于书籍的目录。它首先通过聚类将所有向量分成多个“桶”(nlist)，查询时，先找到最相似的几个“桶”，然后只在这几个桶内进行精确搜索。IVF_FLAT、IVF_SQ8、IVF_PQ 是其不同变体，主要区别在于是否对桶内向量进行了压缩（量化）。
- 优点：通过缩小搜索范围，极大地提升了检索速度，是性能和效果之间很好的平衡。
- 缺点：召回率不是100%，因为相关向量可能被分到了未被搜索的桶中。
- 适用场景：通用场景，尤其适合需要高吞吐量的大规模数据集。
以下分别是文件和向量的倒排索引，向量的IVF吸取了文件的思想
HNSW (Hierarchical Navigable Small Worlds，分层-可导航-小世界-图，是一种基于图的索引)
- 原理：构建一个多层的邻近图。查询时从最上层的稀疏图开始，快速定位到目标区域，然后在下层的密集图中进行精确搜索。
- 优点：检索速度极快，召回率高，尤其擅长处理高维数据和低延迟查询。
- 缺点：内存占用非常大，构建索引的时间也较长。
- 适用场景：对查询延迟有严格要求（如实时推荐、在线搜索）的场景。
DiskANN (基于磁盘的索引)
- 原理：一种为在 SSD 等高速磁盘上运行而优化的图索引。
- 优点：支持远超内存容量的海量数据集（十亿级甚至更多），同时保持较低的查询延迟。
- 缺点：相比纯内存索引，延迟稍高。
- 适用场景：数据规模巨大，无法全部加载到内存的场景。

(3) 索引算法 - 性能均衡

除了暴力搜索能精确索引到近邻，所有搜索算法只能在性能、召回率、内存三者之间权衡。

在评估性能的时候，平衡构建时间、每秒查询次数（QPS）和召回率至关重要，一般性的规则如下：

就QPS 而言，基于图形的索引类型通常优于IVF 变体。
IVF 变体尤其适用于topK 较大的情况（例如，超过 2,000 个）。
与SQ相比，PQ通常能在相似的压缩率下提供更好的召回率，但后者的性能更快。
将硬盘用于部分索引（如DiskANN）有助于管理大型数据集，但也会带来潜在的 IOPS 瓶颈。

另外，根据处理容量问题的时候，要考虑以下几点：

如果有四分之一的原始数据适合存储在内存中，则应考虑使用延迟稳定的 DiskANN。
如果所有原始数据都适合在内存中存储，则应考虑基于内存的索引类型和 mmap。
可以使用量化应用索引类型和 mmap 来换取最大容量的准确性。

从召回率考虑，召回率涉及过滤率，即搜索前过滤掉的数据。处理召回问题，应考虑以下几点：

如果过滤率小于 85%，则基于图的索引类型优于 IVF 变体。
如果过滤比在 85% 到 95% 之间，则使用 IVF 变体。
如果过滤率超过 98%，则使用 "蛮力"（FLAT）来获得最准确的搜索结果。

从性能考虑，搜索性能通常涉及top-K，即搜索返回记录数。处理性能时会考虑以下问题：

对于 Top-K 较小的搜索（如 2,000），需要较高的召回率，基于图的索引类型优于 IVF 变体。
对于 top-K 较大的搜索（与向量嵌入的总数相比），IVF 变体比基于图的索引类型是更好的选择。
对于 top-K 中等且过滤率较高的搜索，IVF 变体是更好的选择。

最后总结一下决策矩阵：

方案	推荐索引	注释
原始数据适合内存	HNSW、IVF + 精炼	使用 HNSW 实现低 k / 高召回率
磁盘、固态硬盘上的原始数据	磁盘 ANN	最适合对延迟敏感的查询
磁盘上的原始数据，有限的 RAM	IVFPQ / SQ + mmap	平衡内存和磁盘访问
高过滤率（>95%）	强制（FLAT）	避免微小候选集的索引开销
大型 k（≥ 数据集的 1%）	IVF	簇剪枝减少了计算量
极高的召回率（>99%）	蛮力（FLAT）+ GPU	--

5. Milvus的核心组件 - 检索 (Search)

拥有了数据容器 (Collection) 和检索引擎 (Index) 后，最后一步就是从海量数据中高效地检索信息。这是 Milvus 的核心功能之一，近似最近邻 (Approximate Nearest Neighbor, ANN) 检索。与需要计算全部数据的暴力检索（Brute-force Search）不同，ANN 检索利用预先构建好的索引，能够极速地从海量数据中找到与查询向量最相似的 Top-K 个结果。这是一种在速度和精度之间取得极致平衡的策略。

主要参数:

anns_field: 指定要在哪个向量字段上进行检索。
data: 传入一个或多个查询向量。
limit (或 top_k): 指定需要返回的最相似结果的数量。
search_params: 指定检索时使用的参数，例如距离计算方式 (metric_type) 和索引相关的查询参数。

ANN通常是一种思想而不是算法，前文中向量字段索引算法除了FLAT，IVF、HNSW、DiskANN都是ANN，还有很多种。

在基础ANN检索之上，Milvus还提供了多种增强检索功能，以满足更加复杂的业务需求。

(1) 过滤检索 (Filtered Search)

在实际应用中，我们很少只进行单纯的向量检索。更常见的需求是“在满足特定条件的向量中，查找最相似的结果”，这就是过滤检索。它将向量相似性检索与标量字段过滤结合在一起。

工作原理：先根据提供的过滤表达式 (filter) 筛选出符合条件的实体，然后仅在这个子集内执行 ANN 检索。这极大地提高了查询的精准度。
应用示例：
- 电商："检索与这件红色连衣裙最相似的商品，但只看价格低于500元且有库存的。"
- 知识库："查找与‘人工智能’相关的文档，但只从‘技术’分类下、且发布于2023年之后的文章中寻找。"

(2) 范围检索 (Range Search)

有时我们关心的不是最相似的 Top-K 个结果，而是“所有与查询向量的相似度在特定范围内的结果”。

工作原理：范围检索允许定义一个距离（或相似度）的阈值范围。Milvus 会返回所有与查询向量的距离落在这个范围内的实体。
应用示例：
- 人脸识别："查找所有与目标人脸相似度超过 0.9 的人脸"，用于身份验证。
- 异常检测："查找所有与正常样本向量距离过大的数据点"，用于发现异常。

(3) 多向量混合检索 (Hybrid Search)

这是 Milvus 提供的一种极其强大的高级检索模式，它允许在一个请求中同时检索多个向量字段，并将结果智能地融合在一起。

工作原理：
1. 并行检索：应用针对不同的向量字段（如一个用于文本语义的密集向量，一个用于关键词匹配的稀疏向量，一个用于图像内容的多模态向量）分别发起 ANN 检索请求。
2. 结果融合 (Rerank)：Milvus 使用一个重排策略（Reranker）将来自不同检索流的结果合并成一个统一的、更高质量的排序列表。常用的策略有 RRFRanker（平衡各方结果）和 WeightedRanker（可为特定字段结果加权）。
应用示例：
- 多模态商品检索：用户输入文本“安静舒适的白色耳机”，系统可以同时检索商品的文本描述向量和图片内容向量，返回最匹配的商品。
- 增强型 RAG: 结合密集向量（捕捉语义）和稀疏向量（精确匹配关键词），实现比单一向量更精准的文档检索效果。

(4) 分组检索 (Grouping Search)

分组检索解决了一个常见的痛点：检索结果多样性不足。想象一下，你检索“机器学习”，返回的前10篇文章都来自同一本教科书不同章节。这显然不是理想的结果。

工作原理：分组检索允许指定一个字段（如 document_id）对结果进行分组。Milvus 会在检索后，确保返回的结果中每个组（每个 document_id）只出现一次（或指定的次数），且返回的是该组内与查询最相似的那个实体。
应用示例：
- 视频检索：检索“可爱的猫咪”，确保返回的视频来自不同的博主。
- 文档检索：检索“数据库索引”，确保返回的结果来自不同的书籍或来源。

通过这些灵活的检索功能组合，开发者可以构建出满足各种复杂业务需求的向量检索应用。

6. Milvus包的使用

上面讲了一大堆Milvus的概念和内容，但是没有讲操作Milvus的SDK，还没法上手使用。接下来就介绍一下PyMilvus的一些常用操作吧。文档在这里。

首先，我们通过pip安装：

python3 -m pip install pymilvus==2.6.10

安装正确之后，我们就可以使用它的如下包：

API / 写法	作用	常见参数	什么时候用
`from pymilvus import MilvusClient, FieldSchema, CollectionSchema, DataType`	导入客户端、Schema 和字段类型	无	开始写 PyMilvus 代码时
`MilvusClient(uri="http://localhost:19530")`	连接 Milvus 服务	`uri`	初始化客户端
`client.has_collection(name)`	判断某个 collection 是否存在	`collection_name`	创建前检查
`client.drop_collection(name)`	删除 collection	`collection_name`	demo 重跑、清理旧数据
`FieldSchema(...)`	定义单个字段	`name`、`dtype`、`is_primary`、`auto_id`、`dim`、`max_length`	自定义 schema 时
`CollectionSchema(fields, description=...)`	把多个字段组合成完整 schema	`fields`、`description`	创建 collection 前
`client.create_collection(collection_name=..., schema=schema)`	按 schema 创建 collection	`collection_name`、`schema`	建表
`client.describe_collection(collection_name=...)`	查看 collection 结构详情	`collection_name`	验证建表结果
`client.insert(collection_name=..., data=data)`	插入数据	`collection_name`、`data`	入库向量和元数据
`client.prepare_index_params()`	创建索引参数对象	无	建索引前准备
`index_params.add_index(...)`	向索引参数对象里添加一个索引定义	`field_name`、`index_type`、`metric_type`、`params`	配置向量索引
`client.create_index(collection_name=..., index_params=index_params)`	真正创建索引	`collection_name`、`index_params`	插入数据后建索引
`client.describe_index(collection_name=..., index_name=...)`	查看索引详情	`collection_name`、`index_name`	验证索引是否建好
`client.load_collection(collection_name=...)`	将 collection 加载到内存，供检索使用	`collection_name`	搜索前
`client.search(...)`	执行向量检索	`collection_name`、`data`、`limit`、`output_fields`、`search_params`	真正做相似度搜索
`client.release_collection(collection_name=...)`	从内存中释放 collection	`collection_name`	结束实验、释放资源

下面，我们也提供一个最小工作流，看一眼就理解这个向量数据库是怎么工作的了：

from pymilvus import MilvusClient, FieldSchema, CollectionSchema, DataType

# 1. 连接
client = MilvusClient(uri="http://localhost:19530")

# 2. 定义 schema
fields = [
    FieldSchema(name="id", dtype=DataType.INT64, is_primary=True, auto_id=True),
    FieldSchema(name="vector", dtype=DataType.FLOAT_VECTOR, dim=768),
    FieldSchema(name="text", dtype=DataType.VARCHAR, max_length=512),
]
schema = CollectionSchema(fields, description="demo")

# 3. 创建 collection
client.create_collection(collection_name="demo", schema=schema)

# 4. 插入数据
data = [
    {"vector": [0.1] * 768, "text": "hello"},
    {"vector": [0.2] * 768, "text": "world"},
]
client.insert(collection_name="demo", data=data)

# 5. 建索引
index_params = client.prepare_index_params()
index_params.add_index(
    field_name="vector",
    index_type="HNSW",
    metric_type="COSINE",
    params={"M": 16, "efConstruction": 200}
)
client.create_index(collection_name="demo", index_params=index_params)

# 6. 加载 collection
client.load_collection(collection_name="demo")

# 7. 搜索
res = client.search(
    collection_name="demo",
    data=[[0.1] * 768],
    limit=2,
    output_fields=["text"],
    search_params={"metric_type": "COSINE", "params": {"ef": 64}},
)
print(res)

上述代码，描述了建立一个Collection，包含id、vector和text，我们插入了两个全0.1和0.2的768维向量作为vector，然后给text写成hello、world。紧接着，我们创建索引，采用HNSW索引模式来索引向量字段，余弦相似度作为向量相似度度量，并用M=16、efConstruction=20作为建图参数（什么意思呢，就是每个节点做多连接16条邻居边，建索引时，为了给每个点找到更好的邻居，搜索候选集合开为200。合在一起就是建图的时候找考查200个候选点，然后找出真正合适的16个连边，200是一个经验值，M大图更密但召回更好，M小省资源）。

然后，我们已经做好了向量数据库，就进行搜索。在demo中查询链表用一个768维的0.1的向量，返回两条结果（也就是top-2检索）。output_fields固定除了返回id、distance这些，还要把text字段返回（通常是元数据之类的），最后是搜索时用余弦相似度，然后ef说明了会维持64大小的候选集合再选出top-2.（ef越大搜索越充分，召回率通常更高，但是搜索更慢）。

由于余弦相似度只看方向不看长度，所以它们和query的相似度都会接近于1（超过1一点通常是浮点误差），两个distance极度相近，所以排序排序谁前谁后都有可能。

Off-Policy 偏好优化：DPO 与新分支

Wed, 25 Mar 2026 00:00:00 GMT

DPO算法是对PPO的流程进一步简化,

一. 直接偏好优化 (Direct Preference Optimization, DPO)

以PPO为优化目标产生最优Policy的条件下推出了reward的表达式, 然后将该reward的表达式代入了以Bradley-Terry模型建模的最大似然估计中, 即可得到DPO的Loss. (DPO与PPO的目标是一致的，PPO以强化学习的方式实现了这个目标的优化，DPO认为这个目标有一个解析解，所以把这个解析解推导了出来，最后得到了DPO的loss)

DPO的核心洞察在于原始强化学习问题存在解析最优解，表明最优策略与奖励函数存在一一映射关系。DPO将此关系反解后代入Bradley-Terry偏好模型，将对奖励函数的似然最大化，等价地转化为直接对策略的似然最大化。因此，优化DPO损失函数即是在直接寻找那个能同时最大化人类偏好概率且满足最优解形式的策略，避免了先用偏好数据拟合奖励模型再进行强化学习过程寻找最优策略.

Hot100的ACM模式题解

Wed, 25 Mar 2026 00:00:00 GMT

两数之和

1. 题面

1. 两数之和

难度：简单

给定一个整数数组 nums 和一个整数目标值 target，请你在该数组中找出 和为目标值 target 的那两个整数，并返回它们的数组下标。

你可以假设每种输入只会对应一个答案，并且你不能使用两次相同的元素。

你可以按任意顺序返回答案。

示例 1：

输入：nums = [2,7,11,15], target = 9
输出：[0,1]
解释：因为 nums[0] + nums[1] == 9 ，返回 [0, 1] 。

示例 2：

输入：nums = [3,2,4], target = 6
输出：[1,2]

示例 3：

输入：nums = [3,3], target = 6
输出：[0,1]

提示：

2 <= nums.length <= 10^4
-10^9 <= nums[i] <= 10^9
-10^9 <= target <= 10^9
只会存在一个有效答案

进阶： 你可以想出一个时间复杂度小于 O(n^2) 的算法吗？

2. 解法

# 梦开始的地方
# 如果强硬做需要n方二重循环，首先体现出哈希表空间换时间

# 打一个哈希表值:下标，每一次找哈希表中target-val的数字，如果找到了就返回下标列表，找不到就存入哈希表
def solution(nums,target)->list:
    dict = {}
    for i,val in enumerate(nums):
        if target-val in dict:
            return [i,dict[target-val]]
        else:
            dict[val] = i
    # 假设都对应答案不用考虑找不到

if __name__ == "__main__":
    # 我们让输入两行，一行为逗号隔开的数字，另一行target
    nums = list(map(int,input().strip().split(',')))
    target = int(input().strip())
    print(solution(nums,target))

3. 反思

本题是基础哈希表空间换时间，第一次做的时候没有加else，虽然这题无所谓，但是别的题可能会有区别。
还有一个细节，我用了dict，实际上覆盖了内置的dict，还是用mp比较好

4. 二刷

成功考虑到了要不要else要不要加，另外，这题还有其他的解法。算是哈希表的基础应用题。

字母的同分异构词

1. 题面

49. 字母异位词分组

难度：中等

给你一个字符串数组，请你将字母异位词组合在一起。可以按任意顺序返回结果列表。

示例 1:

输入: strs = ["eat", "tea", "tan", "ate", "nat", "bat"]

输出: [["bat"],["nat","tan"],["ate","eat","tea"]]

解释：

在 strs 中没有字符串可以通过重新排列来形成 "bat"。
字符串 "nat" 和 "tan" 是字母异位词，因为它们可以重新排列以形成彼此。
字符串 "ate" ，"eat" 和 "tea" 是字母异位词，因为它们可以重新排列以形成彼此。

示例 2:

输入: strs = [""]

输出: [[""]]

示例 3:

输入: strs = ["a"]

输出: [["a"]]

提示：

1 <= strs.length <= 10^4
0 <= strs[i].length <= 100
strs[i] 仅包含小写字母

2. 解法 1 · {}

# 白痴做法是排序判断，python快排是onlogn
# 保持on可以用哈希表，这题的意思换句话就是将字母出现个数一样的放在一起
# 维持一个字母表:字符串列表

def solution(strs)->list[list[str]]:
    mp = {}
    for s in strs:
        ap = [0]*26
        for i in s:
            ap[ord(i)-ord('a')] += 1
        # 注意list不能当key
        key = tuple(ap)
        if key not in mp:
            mp[key]=[]
        mp[key].append(s)
    # 现在按照每个ap返回组成的字符串列表
    return list(mp.values())


if __name__ == "__main__":
    # 输入一串str
    strs = [s.strip().strip('"') for s in input().strip().split(',')]
    print(solution(strs))

3. 解法 2 · defaultdict

from collections import defaultdict

def solution(strs)->list[list[str]]:
    # defaultdict可以避免查空建表，遇到没见过的key默认开辟
    # defaultdict(list)就是默认传进来没见过的用list()先构造，也就是list()默认值空列表
    # 同理defaultdict(int)，int()的默认值是0
    # defaultdict(set)还可以叠去重
    groups = defaultdict(list)
    for s in strs:
        count = [0] * 26
        for c in s:
            count[ord(c) - ord("a")] += 1
        groups[tuple(count)].append(s)
    return list(groups.values())


if __name__ == "__main__":
    # 输入一串str
    strs = [s.strip().strip('"') for s in input().strip().split(',')]
    print(solution(strs))

4. 反思

实际上做到这里的时候想到用这种方法，但是还是有点小梗塞。容易出错的点：list不能作为key，需要tuple；ord函数别忘了；mp.values()的用法，返回values的迭代器，用list转为答案数组
如果使用默认数组，不需要先判key空产生[]再append，直接用defaultdict(list)，等于设置了键值的值默认为list的默认值空列表；同理，这里设置为int就是默认值为0
注意输入处理，因为默认复制力扣的输入是有"的，而想去掉双引号，需要用单引号包裹来strip('"')。

5. 二刷

哎呀，二刷错了啊！！竟然直接把哈希表转tuple当key了，哈希表本身tuple之后只能得到key的元组，计算实在想当也需要key = tuple(sorted(Counter(s).items()))用这种包含完整信息的，但是这样太麻烦了，要么直接用sorted之后当key，要么就是按照原本的做法，打字母表就行了。每个单词的结果作为记数列表当做tuple才是最自然的。不过这次好在想到了空的时候建[]

最长连续序列

1. 题面

128. 最长连续序列

难度：中等

给定一个未排序的整数数组 nums ，找出数字连续的最长序列（不要求序列元素在原数组中连续）的长度。

请你设计并实现时间复杂度为 O(n) 的算法解决此问题。

示例 1：

输入：nums = [100,4,200,1,3,2]
输出：4
解释：最长数字连续序列是 [1, 2, 3, 4]。它的长度为 4。

示例 2：

输入：nums = [0,3,7,2,5,8,4,6,0,1]
输出：9

示例 3：

输入：nums = [1,0,1,2]
输出：3

提示：

0 <= nums.length <= 10^5
-10^9 <= nums[i] <= 10^9

2. 解法

# 需要on解决问题，只能遍历一遍，必须空间换时间
# 我们先遍历一遍，将数组放进集合，然后找下一个有可能的数字。虽然是循环套循环，但是终归是有限次查找，所以为on

def solution(nums)->int:
    num_set = set(nums)
    longest = 0
    current_length = 0
    for num in num_set:
        current = num
        current_length = 1
        # 循环找有限个后续
        while current + 1 in num_set:
            current += 1
            current_length += 1 
        longest = max(longest,current_length)
    return longest

if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    print(solution(nums))

3. 反思

这题肯定也是第一时间想到空间换时间，但是没想到哈希存什么。主要是害怕for套for复杂度超过on，但是其实里面是有限次循环，还是on。
不用set的话问了题友，也是哈希打一遍标记，然后前后找。

4. 二刷

秒了

移动零

1. 题面

283. 移动零

难度：简单

给定一个数组 nums，编写一个函数将所有 0 移动到数组的末尾，同时保持非零元素的相对顺序。

请注意 ，必须在不复制数组的情况下原地对数组进行操作。

示例 1:

输入: nums = [0,1,0,3,12]
输出: [1,3,12,0,0]

示例 2:

输入: nums = [0]
输出: [0]

提示 :

1 <= nums.length <= 10^4
-2^31 <= nums[i] <= 2^31 - 1

**进阶：**你能尽量减少完成的操作次数吗？

2. 解法

# 双指针搬运法，很简单
def solution(nums):
    i,j = 0, 0
    n = len(nums)
    if n<=1:
        return nums
    while j<n:
        if nums[j]!=0:
            nums[i]=nums[j]
            i+=1
        j+=1
    # 如果i没走完，则后面全部置零
    while i<n:
        nums[i]=0
        i+=1
    return nums

if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    print(solution(nums))

3. 反思

没啥好说的，就是简单的移动插入，跟插入排序有点像，需要注意的是while循环下面别忘了移动变量，这个经常忘记。

4. 二刷

直接i、j都定义为0就不需要特判n<=1了。

5. 三刷

啊呀才发现一刷有重大问题！！i、j必须从0开始，特判小于等于1也没必要。如果j默认从1开始，就默许了0号位是有效的了，测试点会出错！！

盛水最多的容器

1. 题面

11. 盛最多水的容器

难度：中等

给定一个长度为 n 的整数数组 height 。有 n 条垂线，第 i 条线的两个端点是 (i, 0) 和 (i, height[i]) 。

找出其中的两条线，使得它们与 x 轴共同构成的容器可以容纳最多的水。

返回容器可以储存的最大水量。

说明： 你不能倾斜容器。

示例 1：

输入：[1,8,6,2,5,4,8,3,7]
输出：49 
解释：图中垂直线代表输入数组 [1,8,6,2,5,4,8,3,7]。在此情况下，容器能够容纳水（表示为蓝色部分）的最大值为 49。

示例 2：

输入：height = [1,1]
输出：1

提示：

n == height.length
2 <= n <= 10^5
0 <= height[i] <= 10^4

2. 题解

# 这题其实是双指针，一前一后，每次贪心移动比较矮的柱子（因为木桶效应，矮柱子比较碍事）
def solution(heights):
    n = len(heights)
    i, j = 0, n-1
    max_pool = 0
    while i !=j:
        min_height = min(heights[i],heights[j])
        max_pool = max(max_pool,min_height*(j-i))
        if heights[i]<=heights[j]:
            i+=1
        else:
            j-=1
    return max_pool

if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    print(solution(nums))

3. 反思

这题老是幻视成单调栈，但是实际上不是需求“第一个比xx大/小”的量，卡了半天不知道怎么写。
但是这题实际上是一个贪心，理论依据是“移动高的那边一定不可能得到更优解”，所以只能移动矮的那边去保留希望。这个解释还是让人感觉懵懵的。
询问码u，最好的解释是“移动小的那根不一定能让水更多，但是大的那根肯定会变少”，因为移动大的那根，小的那根被限制住了，无论如何都不会变大，反而使宽度减小。

4. 二刷

秒，移动短边获得希望。

三数之和

1. 题面

15. 三数之和

难度：中等

给你一个整数数组 nums ，判断是否存在三元组 [nums[i], nums[j], nums[k]] 满足 i != j、i != k 且 j != k ，同时还满足 nums[i] + nums[j] + nums[k] == 0 。请你返回所有和为 0 且不重复的三元组。

注意： 答案中不可以包含重复的三元组。

示例 1：

输入：nums = [-1,0,1,2,-1,-4]
输出：[[-1,-1,2],[-1,0,1]]
解释：
nums[0] + nums[1] + nums[2] = (-1) + 0 + 1 = 0 。
nums[1] + nums[2] + nums[4] = 0 + 1 + (-1) = 0 。
nums[0] + nums[3] + nums[4] = (-1) + 2 + (-1) = 0 。
不同的三元组是 [-1,0,1] 和 [-1,-1,2] 。
注意，输出的顺序和三元组的顺序并不重要。

示例 2：

输入：nums = [0,1,1]
输出：[]
解释：唯一可能的三元组和不为 0 。

示例 3：

输入：nums = [0,0,0]
输出：[[0,0,0]]
解释：唯一可能的三元组和为 0 。

提示：

3 <= nums.length <= 3000
-10^5 <= nums[i] <= 10^5

2. 题解

# 第一个想法比较直白，二重循环来找第三个数，从而变成两数之和，但是这样就on方了
# 好吧只能on方，想什么呢。既然只有on方，那排序也是可以的了，然后用更优雅的方法：固定一个数+双指针移动
def solution(nums):
    nums.sort()
    ans = []
    for i in range(len(nums)):
        if i > 0 and nums[i] == nums[i - 1]:
            continue
        left, right = i + 1, len(nums) - 1
        while left < right:
            s = nums[i] + nums[left] + nums[right]
            # 以0为分界决定移动哪个指针
            if s < 0:
                left += 1
            elif s > 0:
                right -= 1
            else:
                ans.append([nums[i], nums[left], nums[right]])
                left += 1
                right -= 1
                while left < right and nums[left] == nums[left - 1]:
                    left += 1
                while left < right and nums[right] == nums[right + 1]:
                    right -= 1
    return ans

if __name__=="__main__":
    nums = list(map(int,input().strip().split(',')))
    print(solution(nums))

3. 二刷

这一题的去重是大坑。我使用tuple化list，勉强去重成功。但是最好的方法，其实是移动的时候直接忽略相同元素（排序后相同元素在一起）。所以按照题解一样，如果移动后元素还是一样，直接什么也不做跳过去。
可以剪枝到len(nums)-2

接雨水

1. 题面

42. 接雨水

难度：困难

给定 n 个非负整数表示每个宽度为 1 的柱子的高度图，计算按此排列的柱子，下雨之后能接多少雨水。

示例 1：

输入：height = [0,1,0,2,1,0,1,3,2,1,2,1]
输出：6
解释：上面是由数组 [0,1,0,2,1,0,1,3,2,1,2,1] 表示的高度图，在这种情况下，可以接 6 个单位的雨水（蓝色部分表示雨水）。

示例 2：

输入：height = [4,2,0,3,2,5]
输出：9

提示：

n == height.length
1 <= n <= 2 * 10^4
0 <= height[i] <= 10^5

2. 题解1 - 单调栈法

# 经典单调栈的题目，只要能识别为找到第一个比xxx大/小的题目都可以单调栈
# 本题要找左侧第一个比它高的，还要找右侧第一个比它高的，这样才能形成水洼。左侧最高可以用递减栈记录，右侧最高只能通过出栈的瞬间判断。不过不用担心有的栈不会被弹出，因为找不到右侧比它更高的，就行不成水洼；左侧同理，找left的时候要进行一次保护。
# 坐标语言，(right-left-1)*(左右那个比较矮的和当前的高度差)=累积的水泊
from collections import deque

def solution(height:list):
    # 存储 值:下标
    q = deque()
    pool = 0
    for i,h in enumerate(height):
        while q and q[-1][0]<h:
            curr_val,curr = q.pop()
            right = i
            rigth_val = h
            # 左边第一个比它高的是弹出后的栈顶。如果左边没了，形不成水洼
            if not q:
                break
            left_val,left = q[-1]
            # 加池子
            pool += (min(left_val,rigth_val)-curr_val)*(right-left-1)
        # 进栈
        q.append((h,i))
    return pool

if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    print(solution(nums))

3. 反思

实际解题的思路已经写的很清楚了，重要的就是单调栈的思想。
注意这里不需要全部弹出，右侧可能没有更高的边界；需要注意的是左侧可能会没有水洼，所以要保护一下空栈。
这里right、right_val就是当前的i、h，更简的话可以不定义right相关变量

4. 二刷

二刷的时候把问题想简单了，直接把val做单调栈没有带上坐标，然后直接只看高度差来积水。比较好的思维方式是，看到弹出结算的加上的水，其实是以curr高度托底，左右第一个比较高的柱子之间的差。

每次比较担心的思维陷阱其实是4、6会不会重复计算水？排除这种情况就可以大胆用长度差*高度差来积水了。

5. 题解2 - 前后缀最大值法

# 另一种比较直观的解法，前后缀最大值法。
# 我们在每个位置记忆左侧更高的高度、右侧更高的高度，然后遍历一遍，只拿下这个洼地上方一列的存水量（高度差）。
import ast

def solution(height: list[int]) -> int:
    n = len(height)
    if n == 0:
        return 0

    left_max = [0] * n
    right_max = [0] * n

    left_max[0] = height[0]
    for i in range(1, n):
        left_max[i] = max(left_max[i - 1], height[i])

    right_max[n - 1] = height[n - 1]
    for i in range(n - 2, -1, -1):
        right_max[i] = max(right_max[i + 1], height[i])

    ans = 0
    for i in range(n):
        ans += min(left_max[i], right_max[i]) - height[i]

    return ans


if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    print(solution(nums))

6. 题解3 - 双指针法

上面的前后缀只要算自己头上的水泊，还是比较清晰的。不过仔细观察就会发现开两个数组没必要，用两个变量就可以了，这样就可以压缩成双变量法。

def trap(height):
    left, right = 0, len(height) - 1
    leftMax = rightMax = 0
    res = 0

    while left < right:
        leftMax = max(leftMax, height[left])
        rightMax = max(rightMax, height[right])

        if leftMax < rightMax:
            res += leftMax - height[left]
            left += 1
        else:
            res += rightMax - height[right]
            right -= 1

    return res

无重复字符的最长子串

1. 题面

3. 无重复字符的最长子串

难度：中等

给定一个字符串 s ，请你找出其中不含有重复字符的 最长子串 的长度。

示例 1:

输入: s = "abcabcbb"
输出: 3 
解释: 因为无重复字符的最长子串是 "abc"，所以其长度为 3。注意 "bca" 和 "cab" 也是正确答案。

示例 2:

输入: s = "bbbbb"
输出: 1
解释: 因为无重复字符的最长子串是 "b"，所以其长度为 1。

示例 3:

输入: s = "pwwkew"
输出: 3
解释: 因为无重复字符的最长子串是 "wke"，所以其长度为 3。
     请注意，你的答案必须是 子串 的长度，"pwke" 是一个子序列，不是子串。

提示：

0 <= s.length <= 5 * 10^4
s 由英文字母、数字、符号和空格组成

2. 题解

# 一眼滑动窗口，维持一个哈希表记录window里面的字母有没有重复。每次窗口有效时，记录window长度，更新最大值
def solution(s: str) -> int:
    window = {}
    left = 0
    max_length = 0
    for right, ch in enumerate(s):
        window[ch] = window.get(ch, 0) + 1
        # 这里写只要不合法，就移动左边
        while window[ch] > 1:
            window[s[left]] -= 1
            left += 1
        max_length = max(max_length, right - left + 1)
    return max_length


if __name__ == "__main__":
    s = input()
    print(solution(s))

3. 反思

我其实感觉滑动窗口的思路比较简单，但是比较考验码力，特别是边界和条件判断的地方，特别容易绕晕。
我第一版有很多疏漏，现在是更新过的版本。易错点1：left移动的条件不对，应该写在while里面的是“不合法”的条件，移动left直到合法；易错点2：不能用len(window)，即使哈希值归0了，键值对还在。

4. 二刷

想到用滑动窗口了，但是收缩条件一时想不到，还想着遍历整个哈希表看看大于1有无，其实只要看当前位置就行了。另外还有一个坑点，我有时候会在left收缩的时候复用c，其实多数情况没事，但是收缩的条件这次是包含c的，就不能直接覆盖了，还是建议以后写成d吧。

5. 解法 - 标准滑动窗口法

def solution(s:str) -> int:
    # 维持一个滑动窗口，当重复出现的时候，开始收缩左窗口，直到不重复
    left,right = 0,0
    window = {}
    max_length = 0
    while right<len(s):
        c = s[right]
        right += 1
        window[c] = window.get(c,0)+1
        # 需要收缩的条件
        while window[c]>1:
            d = s[left]
            window[d] -= 1
            left += 1
        max_length = max(max_length,right-left)
    return max_length


if __name__ == "__main__":
    s = input().strip()
    print(solution(s))

6. 三刷

这次写对了，但是多加了两个没用的if。if只会被用来判断need，window肯定是加一次删一次，不用if。

找到字符串中所有字母异位词

1. 题面

438. 找到字符串中所有字母异位词

难度：中等

给定两个字符串 s 和 p，找到 s 中所有 p 的 异位词 的子串，返回这些子串的起始索引。不考虑答案输出的顺序。

示例 1:

输入: s = "cbaebabacd", p = "abc"
输出: [0,6]
解释:
起始索引等于 0 的子串是 "cba", 它是 "abc" 的异位词。
起始索引等于 6 的子串是 "bac", 它是 "abc" 的异位词。

示例 2:

输入: s = "abab", p = "ab"
输出: [0,1,2]
解释:
起始索引等于 0 的子串是 "ab", 它是 "ab" 的异位词。
起始索引等于 1 的子串是 "ba", 它是 "ab" 的异位词。
起始索引等于 2 的子串是 "ab", 它是 "ab" 的异位词。

提示:

1 <= s.length, p.length <= 3 * 10^4
s 和 p 仅包含小写字母

2. 题解

# 依旧滑动窗口
# 换言之，我们需要将p的哈希表和s中滑动窗口的哈希表一样，我们可以用validation记录一样的键时值一样，即合法键值对个数，如果和p的哈希表一样长就对了（为什么不直接==两个哈希表呢？因为哈希表全等是逐元素判断，写上时间就爆了。
def solution(s: str, p: str) -> list[int]:
    need = {}
    window = {}
    # 填充需求哈希表
    for c in p:
        need[c] = need.get(c, 0) + 1
    left = 0
    right = 0
    # 满足条件的元素个数，后面和len(need)比较
    valid = 0
    ans = []

    while right < len(s):
        c = s[right]
        right += 1
        # 右侧扩张，并判断是否增加valid
        if c in need:
            window[c] = window.get(c, 0) + 1
            if window[c] == need[c]:
                valid += 1
        # 我们当有效元素达到要求时，再来看长度，如果满足要求就加上答案，否则left移动
        while valid == len(need):
            if right - left == len(p):
                ans.append(left)

            # 这部分逻辑与right的对称
            d = s[left]
            left += 1

            if d in need:
                if window[d] == need[d]:
                    valid -= 1
                # 无论怎么样移动后都要给这个window最后调整-1
                window[d] -= 1

    return ans

if __name__ == "__main__":
    s = input().strip()
    p = input().strip()
    print(solution(s,p))

3. 反思

这题是非常值得反复练习的滑动窗口题目，我重写的时候又弄错了，将right - left == len(p)作为while条件，这样还要先移动right，非常复杂容易出错。正确的一体化思路，应当是将valid个数合格作为左边收缩的起点，收缩一直进行到valid不满足为止。
左右的操作实际上是对称的，取值、移动，右侧先动哈希再看valid，左侧先看valid再动哈希。其中的区别在于，left是看先满足再丢弃，right是先拿取再看是否满足。

4. 二刷

哎哟我，二刷的时候又弄错了，混淆了固定窗口的滑动和变长度窗口的滑动。上面的题解是为了和其他窗口valid放在while中对上从而做的调整，ans判读也移动到了收缩内部。但是我们可以写这题的标准滑动窗口，将判断放后面，然后对于固定窗口的题，可以直接把长度作为while的判断。

5. 题解2 - 标准固定窗口

def solution(s: str, p: str) -> list[int]:
    ans = []
    need = {}
    window = {}
    left, right = 0, 0
    valid = 0

    for c in p:
        need[c] = need.get(c, 0) + 1

    while right < len(s):
        c = s[right]
        right += 1
        # 只统计需要的
        if c in need:
            window[c] = window.get(c, 0) + 1
            if window[c] == need[c]:
                valid += 1

        # 固定窗口长度，超过 len(p) 就收缩
        while right - left > len(p):
            d = s[left]
            left += 1

            if d in need:
                if window[d] == need[d]:
                    valid -= 1
                window[d] -= 1

        # 长度刚好且所有字符频次都匹配，记录答案
        if right - left == len(p) and valid == len(need):
            ans.append(left)

    return ans


if __name__ == "__main__":
    s = input().strip()
    p = input().strip()
    print(solution(s, p))

和为k的子数组

1. 题面

560. 和为 K 的子数组

难度：中等

给你一个整数数组 nums 和一个整数 k ，请你统计并返回 该数组中和为 k 的子数组的个数 。

子数组是数组中元素的连续非空序列。

示例 1：

输入：nums = [1,1,1], k = 2
输出：2

示例 2：

输入：nums = [1,2,3], k = 3
输出：2

提示：

1 <= nums.length <= 2 * 10^4
-1000 <= nums[i] <= 1000
-10^7 <= k <= 10^7

2. 题解

# 前缀和+哈希表，和两数之和、路径总和III是同一个模板
def solution(nums,k):
    prefix = {0: 1}
    cur = ans = 0
    for v in nums:
        cur += v
        ans += prefix.get(cur - k, 0)
        prefix[cur] = prefix.get(cur, 0) + 1
    return ans

if __name__ == “__main__”:
    nums = list(map(int,input().strip().split(',')))
    k = int(input())
    print(solution(nums,k))

3. 反思

本题一开始用滑动窗口写，但滑动窗口要求窗口扩大时 total 单调递增，即所有元素必须 >= 0。本题 nums[i] 取值范围 [-1000, 1000]，包含负数，while total > k 缩窗口的逻辑不成立——踢掉一个负数 total 反而变大，可能漏掉合法子数组。反例：nums=[-1,-1,1], k=0，正确答案是 1（整个数组），滑动窗口会输出 0。
正确做法是前缀和+哈希表：遍历时维护 cur（前缀和），对于每个位置，查哈希表中 cur - k 出现的次数。本质上和两数之和是同一个套路——cur - k = 之前某个前缀和，那中间那段的和就是 k。

4. 二刷

知道为什么不能用滑动窗口，然后能写出前缀和+哈希表。

滑动窗口最大值

1. 题面

239. 滑动窗口最大值

难度：困难

给你一个整数数组 nums，有一个大小为 k 的滑动窗口从数组的最左侧移动到数组的最右侧。你只可以看到在滑动窗口内的 k 个数字。滑动窗口每次只向右移动一位。

返回 滑动窗口中的最大值 。

示例 1：

输入：nums = [1,3,-1,-3,5,3,6,7], k = 3
输出：[3,3,5,5,6,7]
解释：
滑动窗口的位置                最大值
---------------               -----
[1  3  -1] -3  5  3  6  7       3
 1 [3  -1  -3] 5  3  6  7       3
 1  3 [-1  -3  5] 3  6  7       5
 1  3  -1 [-3  5  3] 6  7       5
 1  3  -1  -3 [5  3  6] 7       6
 1  3  -1  -3  5 [3  6  7]      7

示例 2：

输入：nums = [1], k = 1
输出：[1]

提示：

1 <= nums.length <= 10^5
-10^4 <= nums[i] <= 10^4
1 <= k <= nums.length

2. 解法 1 · 单调队列

# 本地要求的是连续子数组（还固定长度）的与顺序无关的属性（最大值），但是与哈希表、总和不同的是，max不能回退。
# 实际上这一题做法是单调递减队列。单调队列的思想在于维持一个“有效期”，因为max不能回退，就要存储过去合法的max，队首是目前的max
from collections import deque

def solution(nums,k):
    q = deque()
    ans = []
    # 这里我们选择存下标，一般比存值更稳定，可以避免重复值
    for i,x in enumerate(nums):
        # 构造递减队列
        while q and nums[q[-1]]<=x:
            q.pop()
        q.append(i)
        # 检查左边有效期，下标已经不在窗口内，踢出队首
        if q[0]<= i-k:
            q.popleft()
        # 如果长度达到k了，就记录答案。由于前面if的约束，必定会-1，然后+1，所以这里一定是要求的长度
        if i>= k-1:
            ans.append(nums[q[0]])
    return ans

if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    k = int(input())
    print(solution(nums,k))

3. 解法 2 · 堆

# 我们依旧需要维持有序性，单调队列确实是最好的方法，但是思路有点绕
# 一个比较直白的方法，就是做一个最大堆，堆里存值和下标，堆顶下标超过了窗口范围，就弹出，然后下标达到k之后，不断进入、弹出……
import heapq

def solution(nums,k):
    ans,pq = [],[]
    for i,val in enumerate(nums):
        heapq.heappush_max(pq,(val,i))
        while pq and pq[0][1]<= i-k:
            heapq.heappop_max(pq)
        if i>=k-1:
            ans.append(pq[0][0])
    return ans

if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    k = int(input())
    print(solution(nums,k))

4. 反思

这题一开始想到的还是滑动窗口，但是不知道怎么维护max的回退，一开始想到用栈，但是栈没办法处理退出的就是最大值，第二个大值在哪这个问题。
这题的破局关键其中之一就是存储下标。对于可能有重复值的题目，存下标是最安全稳妥的方法。
这题的标准思路是单调队列，单调队列常被用来解决”有效性窗口“的问题，比如这题，就是维持了一系列候选有效的max值，left移动就看左边的第一个值有没有过期（也就是看最大值有没有过期）
同样可以用堆来解决，两者思路差不多，都是存储候选，left移动看看候选最大值有没有过期，过期让老二上。（但是复杂度跌到onlogn了）
特别注意，这里无论是队列长度还是堆长度，都跟窗口的长度无关。所以我们判断窗口是否合法，还是要用下标来判断。

5. 二刷

被秒了。。直接用堆，但是收缩时只看堆顶不对，这个写法只会在“离开的元素刚好等于当前最大值”时弹一下，否则堆里会残留很多已经不在窗口里的旧元素。必须要加上过期机制，比如加入坐标一起入堆，然后看坐标判断过期，或者干脆跟题解一样用单调队列。

最小覆盖子串

1. 题面

76. 最小覆盖子串

难度：困难

给定两个字符串 s 和 t，长度分别是 m 和 n，返回 s 中的 最短窗口子串 ，使得该子串包含 t 中的每一个字符（ 包括重复字符 ）。如果没有这样的子串，返回空字符串 ""。

测试用例保证答案唯一。

示例 1：

输入：s = "ADOBECODEBANC", t = "ABC"
输出："BANC"
解释：最小覆盖子串 "BANC" 包含来自字符串 t 的 'A'、'B' 和 'C'。

示例 2：

输入：s = "a", t = "a"
输出："a"
解释：整个字符串 s 是最小覆盖子串。

示例 3:

输入: s = "a", t = "aa"
输出: ""
解释: t 中两个字符 'a' 均应包含在 s 的子串中，
因此没有符合条件的子字符串，返回空字符串。

提示：

m == s.length
n == t.length
1 <= m, n <= 10^5
s 和 t 由英文字母组成

进阶： 你能设计一个在 O(m + n) 时间内解决此问题的算法吗？

# 一眼滑动窗口，用t建立need，t的长度就是validation需要达到的量。validation达标的情况下left移动
def solution(s: str, t: str) -> str:
    need = {}
    window = {}
    # 记录need
    for c in t:
        need[c] = need.get(c, 0) + 1
    left = 0
    right = 0
    valid = 0
    start = 0
    min_len = float("inf")

    while right < len(s):
        c = s[right]
        right += 1
        # 如果在need中，再记录（不在need中的也不可能对valid产生影响，可以不管）
        if c in need:
            window[c] = window.get(c, 0) + 1
            if window[c] == need[c]:
                valid += 1
        # 当valid满足了，left收缩
        while valid == len(need):
            if right - left < min_len:
                # 同时记录最短长度和起点
                start = left
                min_len = right - left
            # 执行对称收缩即可
            d = s[left]
            left += 1
            if d in need:
                if window[d] == need[d]:
                    valid -= 1
                window[d] -= 1
    # 返回值进行一下inf保护
    return "" if min_len == float("inf") else s[start:start + min_len]


if __name__ == "__main__":
    s = input().strip()
    t = input().strip()
    m = len(s)
    n = len(t)
    print(solution(s,t,m,n))

2. 反思

滑动窗口果然容易码错。虽然对称的left、right操作已经记熟了，但是仍然忘记先看need再哈希。
满足条件再收缩，收缩前就已经满足的，在收缩代码里拿答案；收缩后才合法的，在收缩完成后拿答案。两种情况取决于写的while，一定要注意分辨。

3. 二刷

写错了。这次虽然写对了在need中才加入哈希的逻辑，但是收缩还是写错了。

收缩时不能一见到 d in need 就直接 valid -= 1，还要进一步看if window[d] == need[d]。因为valid只记录是否达到过合法，即使window再进元素也只会加哈希表，反之减少元素也不一定会损失合法性，可以脑内模拟
注意valid等于的时候判断位置，应该在收缩刚开始。

4. 三刷

我草，三刷暴露出了重要问题，观察以下两种写法

if c2 in need:
    window[c2] -= 1
    if window[c2] < need[c2]:
        valid -= 1

和

if c2 in need:
    if window[c2] == need[c2]:
        valid -= 1
    window[c2] -= 1

乍一看两者没什么区别，但是这里由于只要小于window数量小于need就会削减，只要数量不够，每次移出字符都在疯狂扣分，导致 valid 错乱！

虽然我们肯定是要移动的，但是我们最好在移动之前看看是不是正好有效，如果是的才减少valid，这样就不会滥减valid。顺带一提，第一种情况leetcode反例"dinitrophenylhydrazinetrinitrophenylmethylnitramine"和"trinitrophenylmethylnitramine"。

这是固定窗口用滑动窗口解的bug，上一题直接用范围判断其实都没事，因为我们收缩的时候会保证valid达标，所以不可能会出现无辜收缩乱扣valid的情况。不过为了统一，记住以后先判断 window[c2] == need[c2]，决定是否要 valid -= 1，再 window[c2] -= 1

最大子数组和

1. 题面

53. 最大子数组和

难度：中等

给你一个整数数组 nums ，请你找出一个具有最大和的连续子数组（子数组最少包含一个元素），返回其最大和。

子数组 是数组中的一个连续部分。

示例 1：

输入：nums = [-2,1,-3,4,-1,2,1,-5,4]
输出：6
解释：连续子数组 [4,-1,2,1] 的和最大，为 6 。

示例 2：

输入：nums = [1]
输出：1

示例 3：

输入：nums = [5,4,-1,7,8]
输出：23

提示：

1 <= nums.length <= 10^5
-10^4 <= nums[i] <= 10^4

进阶： 如果你已经实现复杂度为 O(n) 的解法，尝试使用更为精妙的 分治法 求解。

2. 题解

# 数组里面有负数，来新元素进来不一定增大，丢弃也不一定变小
# 连续子数组，顺序无关要素（最大和），比较符合滑动窗口。
# 但这题其实的关键其实在数是不是负数。当前位置结束的最大子数组只有两种选择：重新开始只取x，或者接在前面子数组后面，变成pre+x。这其实就是动态规划的方法
# 这种求最大子数组和的问题，不用打表，可以称为Kadane 算法
def solution(nums)->int:
    cur = nums[0]
    ans = nums[0]

    for i in range(1,len(nums)):
        # 先加上这一个位置，看看是否会增大
        # 如果加上更小，不如另开（选nums[i]）
        cur = max(nums[i],cur+nums[i])
        # 维持一个最大值
        ans = max(ans,cur)
    return ans

if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    print(solution(nums))

3. 反思

这题被叫做Kadane算法，他其实是一种动态规划的思想的优化简化，用于处理另起炉灶还是继续加入的选择哪个更好，然后维持一个全局的最优ans

4. 二刷

二刷用了标准dp写出来，不过也是想了一段时间。

5. 题解2 - 标准dp

import ast

def solution(nums:list) -> int:
    # 我们用dp[i]表示到以第i位结尾的最大和连续字数组
    n = len(nums)
    dp = [0] * n
    dp[0] = nums[0]
    for i in range(1,n):
        dp[i] = max(nums[i],dp[i-1]+nums[i])
    return max(dp)


 
if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    print(solution(nums))

合并区间

1. 题面

56. 合并区间

难度：中等

以数组 intervals 表示若干个区间的集合，其中单个区间为 intervals[i] = [starti, endi] 。请你合并所有重叠的区间，并返回 一个不重叠的区间数组，该数组需恰好覆盖输入中的所有区间 。

示例 1：

输入：intervals = [[1,3],[2,6],[8,10],[15,18]]
输出：[[1,6],[8,10],[15,18]]
解释：区间 [1,3] 和 [2,6] 重叠, 将它们合并为 [1,6].

示例 2：

输入：intervals = [[1,4],[4,5]]
输出：[[1,5]]
解释：区间 [1,4] 和 [4,5] 可被视为重叠区间。

示例 3：

输入：intervals = [[4,7],[1,4]]
输出：[[1,7]]
解释：区间 [1,4] 和 [4,7] 可被视为重叠区间。

提示：

1 <= intervals.length <= 10^4
intervals[i].length == 2
0 <= starti <= endi <= 10^4

2. 题解

# 这一题两个区间重合的条件是，new_left<=old_right且new_right>=old_left。我们可以用这个条件判断重合，如果重合，就更新左侧为min的，右侧为max的
# 用一个栈来存储，方便操作
# 但是要注意的是，要先按照左端点排序。这是最大坑点，可能传入的是以前的也能合并。左端点排完序之后new_right>=old_left就不需要了

from collections import deque

def solution(intervals:list[list[int]])->list[list[int]]:
    intervals.sort()
    ans = []
    for left,right in intervals:
        # 如果ans为空或者不用合并
        if not ans or left>ans[-1][1]:
            ans.append([left,right])
        else:
            # 否则需要合并，更新为比较大的右端点
            ans[-1][1] = max(ans[-1][1],right)
    return ans

if __name__ == "__main__":
    # 注意这里的输入，我们让每行输入两个，不定行
    intervals = []
    while True:
        try:
            interval = list(map(int,input().strip().split(',')))
            intervals.append(interval)
        except EOFError:
            break
    print(solution(intervals))

3. 反思

这题重合需要注意可能传进去之前的，传入的左端点还不一定按时间排序，需要自己排序一下。
排序算法intervals.sort(key = lambda x:x[0])可以简写成intervals.sort()。因为python的sort可以默认按照第一项排序。

4. 二刷

只有按左端点排序之后，才能on排序。这题标准解就是sort之后只看右断点，不用多想。

轮转数组

1. 题面

189. 轮转数组

难度：中等

给定一个整数数组 nums，将数组中的元素向右轮转 k 个位置，其中 k 是非负数。

示例 1:

输入: nums = [1,2,3,4,5,6,7], k = 3
输出: [5,6,7,1,2,3,4]
解释:
向右轮转 1 步: [7,1,2,3,4,5,6]
向右轮转 2 步: [6,7,1,2,3,4,5]
向右轮转 3 步: [5,6,7,1,2,3,4]

示例 2:

输入：nums = [-1,-100,3,99], k = 2
输出：[3,99,-1,-100]
解释: 
向右轮转 1 步: [99,-1,-100,3]
向右轮转 2 步: [3,99,-1,-100]

提示：

1 <= nums.length <= 10^5
-2^31 <= nums[i] <= 2^31 - 1
0 <= k <= 10^5

进阶：

尽可能想出更多的解决方案，至少有三种不同的方法可以解决这个问题。
你可以使用空间复杂度为 O(1) 的原地算法解决这个问题吗？

2. 题解 1 · 切片

# 这题直接考查python切片操作就行了
if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    k = int(input().strip())

    k = k%(len(nums))
    print(nums[-k:]+nums[:-k])

3. 题解 2 · 三次翻转

# 题目进阶要求是O(1)空间，那么我们需要做的其实是三次翻转
def reverse(left, right):
    while left < right:
        nums[left], nums[right] = nums[right], nums[left]
        left += 1
        right -= 1

if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    k = int(input().strip())
    
    n = len(nums)
    k = k % n
    reverse(0, n - 1)
    reverse(0, k - 1)
    reverse(k, n - 1)
    print(nums)

4. 题解 3 · 环状替换

每个元素直接跳到它最终该去的位置，一条链跳到底。但是当n与k不互质的情况下，一轮走不完，所以外层必须要从start=0,1,...,gcd(n,k)-1 各启动一轮。(当然，我们也不用非要算这个gcd，直接维持一个全局的count，只要所有数都交换过了，就停止)

# 环装替换的思路，是每个元素都会最终被放到(i+k) % n的位置，这样会形成若干个首尾相连的环，我们一直替换指导回到起点
def rotate(nums: list[int], k: int) -> None:
    n = len(nums)
    k %= n
    count = 0
    start = 0

    while count < n:
        current = start
        prev = nums[start]

        while True:
            nxt = (current + k) % n
            nums[nxt], prev = prev, nums[nxt]
            current = nxt
            count += 1

            if current == start:
                break

        start += 1

if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    k = int(input().strip())
    
    rotate(nums,k)
    print(nums)

5. 反思

如果不限制空间，这题cpp也能直接建立队列做。python切片的复杂度是O(k)，会创建新列表
但是本题想考察的重点其实是你能不能写出O(1)的算法，也就是真的原地。
三次翻转是比较常规的方法，后面链表题也是这么写的。
环状替换比较绕，比较硬核，到时候有空再看看吧。

6. 二刷

别忘了python不支持自定义起点终点的反转。

除自身以外数组的乘积

1. 题面

238. 除了自身以外数组的乘积

难度：中等

给你一个整数数组 nums，返回数组 answer ，其中 answer[i] 等于 nums 中除了 nums[i] 之外其余各元素的乘积。

题目数据保证数组 nums之中任意元素的全部前缀元素和后缀的乘积都在 32 位 整数范围内。

请 不要使用除法， 且在 O(n) 时间复杂度内完成此题。

示例 1:

输入: nums = [1,2,3,4]
输出: [24,12,8,6]

示例 2:

输入: nums = [-1,1,0,-3,3]
输出: [0,0,9,0,0]

提示：

2 <= nums.length <= 10^5
-30 <= nums[i] <= 30
输入保证数组 answer[i] 在 32 位 整数范围内

进阶： 你可以在 O(1) 的额外空间复杂度内完成这个题目吗？（出于对空间复杂度分析的目的，输出数组 不被视为 额外空间。）

2. 题解 1 · 前缀后缀积O(n)

# 经典前缀积问题，不允许使用除法的话，那么就前缀积+后缀积就行了
def solution(nums):
    n = len(nums)
    prefix = [1]*(n+1)
    suffix = [1]*(n+1)
    ans = [0]*n
    # 构造前缀积
    for i in range(1,n+1):
        prefix[i] = nums[i-1]*prefix[i-1]
    # 构造后缀积
    for i in range(n-1,-1,-1):
        suffix[i] = nums[i]*suffix[i+1]
    # 我们构造答案，每个位置其实是i-1的前缀积乘以i+1的后缀积
    for i in range(n):
        ans[i] = prefix[i]*suffix[i+1]
    return ans

if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    print(solution(nums))

3. 题解 2 · 空间O(1)

# 在前缀后缀的题目中，有时候并不需要使用这个数组本身，可以一遍做一边存答案，只用一个变量解决
# 本题可以用ans存前缀积，然后suffix直接算。不算答案数组可以O(1)的额外空间
def solution(nums):
    n = len(nums)
    ans = [1] * n

    # ans[i] 先保存左边乘积
    for i in range(1, n):
        ans[i] = ans[i - 1] * nums[i - 1]

    # suffix 保存右边乘积
    suffix = 1
    for i in range(n - 1, -1, -1):
        ans[i] *= suffix
        suffix *= nums[i]

    return ans


if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    print(solution(nums))

4. 反思

经典前缀后缀题，需要注意的是不常用的后缀怎么设置数组（边界问题）

缺失的第一个正数

1. 题面

41. 缺失的第一个正数

难度：困难

给你一个未排序的整数数组 nums ，请你找出其中没有出现的最小的正整数。

请你实现时间复杂度为 O(n) 并且只使用常数级别额外空间的解决方案。

示例 1：

输入：nums = [1,2,0]
输出：3
解释：范围 [1,2] 中的数字都在数组中。

示例 2：

输入：nums = [3,4,-1,1]
输出：2
解释：1 在数组中，但 2 没有。

示例 3：

输入：nums = [7,8,9,11,12]
输出：1
解释：最小的正数 1 没有出现。

提示：

1 <= nums.length <= 10^5
-2^31 <= nums[i] <= 2^31 - 1

2. 题解

# 循环一遍建立集合，然后用最小正数往下跳就行了。但是要求常数级别的额外空间，这法子不行了。
# 这题的关键在于，“直接用下标当哈希表”。因为正整数一定是从1开始到n+1。我们只要不断交换，让数回到自己所在位置，即num应该去num-1的位置。然后再扫一遍，看每个位置对不对
def solution(nums) -> int:
    n = len(nums)

    for i in range(n):
        while 1 <= nums[i] <= n and nums[nums[i] - 1] != nums[i]:
            j = nums[i] - 1
            nums[i], nums[j] = nums[j], nums[i]

    for i in range(n):
        if nums[i] != i + 1:
            return i + 1

    return n + 1

if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    print(solution(nums))

3. 反思

这题不给你用额外的空间，但是要想到下标和数值本身是有关系的，直接用下标来对应就行了。

4. 二刷

想到了用下标存对应数，但是要记住判读一下值的范围（可能超出下标了）。另外原理是，不管里面存的什么数，第一个不在范围内的正数一定在最大下标+1范围内。

矩阵置零

1. 题面

73. 矩阵置零

难度：中等

给定一个 _m_ x _n_ 的矩阵，如果一个元素为 0 ，则将其所在行和列的所有元素都设为 0 。请使用原地算法。

示例 1：

输入：matrix = [[1,1,1],[1,0,1],[1,1,1]]
输出：[[1,0,1],[0,0,0],[1,0,1]]

示例 2：

输入：matrix = [[0,1,2,0],[3,4,5,2],[1,3,1,5]]
输出：[[0,0,0,0],[0,4,5,0],[0,3,1,0]]

提示：

m == matrix.length
n == matrix[0].length
1 <= m, n <= 200
-2^31 <= matrix[i][j] <= 2^31 - 1

进阶：

一个直观的解决方案是使用 O(_m__n_) 的额外空间，但这并不是一个好的解决方案。
一个简单的改进方案是使用 O(_m_ + _n_) 的额外空间，但这仍然不是最好的解决方案。
你能想出一个仅使用常量空间的解决方案吗？

2. 题解

# 我的想法是先遍历一遍，把0的行、列分别放进两个set中
# 然后再二重循环，如果i in set_i or j in set_j，就直接变0。但是这种方法不满足进阶要求，额外空间复杂度是O(m+n)。不过先把这个做出来吧
def solution(matrix:list[list[int]])->list:
    m = len(matrix)
    n = len(matrix[0])
    set_i = set()
    set_j = set()
    for i in range(m):
        for j in range(n):
            if matrix[i][j]==0:
                set_i.add(i)
                set_j.add(j)
    
    for i in range(m):
        for j in range(n):
            if i in set_i or j in set_j:
                matrix[i][j] = 0

if __name__ == "__main__":
    matrix = []
    while True:
        try:
            line = list(map(int,input().strip().split(',')))
            matrix.append(line)
        except EOFError:
            break
    solution(matrix)
    print(matrix)

3. 题解 · 常数空间

# 现在要实现常数空间做法
# 具体的做法是，拿矩阵的第一行和第一列当标记位。依旧是不用空间的话，就要利用用自身的下标。
def solution(matrix) -> None:
    m = len(matrix)
    n = len(matrix[0])

    first_row_zero = False
    first_col_zero = False

    # 判断第一行是否原本有 0
    for j in range(n):
        if matrix[0][j] == 0:
            first_row_zero = True
            break

    # 判断第一列是否原本有 0
    for i in range(m):
        if matrix[i][0] == 0:
            first_col_zero = True
            break

    # 用第一行和第一列做标记
    for i in range(1, m):
        for j in range(1, n):
            if matrix[i][j] == 0:
                matrix[i][0] = 0
                matrix[0][j] = 0

    # 根据标记置零
    for i in range(1, m):
        for j in range(1, n):
            if matrix[i][0] == 0 or matrix[0][j] == 0:
                matrix[i][j] = 0

    # 最后处理第一行
    if first_row_zero:
        for j in range(n):
            matrix[0][j] = 0

    # 最后处理第一列
    if first_col_zero:
        for i in range(m):
            matrix[i][0] = 0


if __name__ == "__main__":
    matrix = []
    while True:
        try:
            line = list(map(int,input().strip().split(',')))
            matrix.append(line)
        except EOFError:
            break
    solution(matrix)
    print(matrix)

4. 反思

也是限制空间，这时候一定要活用原本的结构。

5. 二刷

秒了，但是要注意标记、对标记的时候，都不要用第一行或者第一列了，不然有一个0就直接先给第一行标满，然后全0了

螺旋矩阵

54. 螺旋矩阵

难度：中等

给你一个 m 行 n 列的矩阵 matrix ，请按照 顺时针螺旋顺序 ，返回矩阵中的所有元素。

示例 1：

输入：matrix = [[1,2,3],[4,5,6],[7,8,9]]
输出：[1,2,3,6,9,8,7,4,5]

示例 2：

输入：matrix = [[1,2,3,4],[5,6,7,8],[9,10,11,12]]
输出：[1,2,3,4,8,12,11,10,9,5,6,7]

提示：

m == matrix.length
n == matrix[i].length
1 <= m, n <= 10
-100 <= matrix[i][j] <= 100

1. 题解

# 螺旋路径使用经典四边界挤压
def solution(matrix):
    if not matrix or not matrix[0]:
        return []
    ans = []
    top, bottom = 0, len(matrix) - 1
    left, right = 0, len(matrix[0]) - 1
    # 这题最明晰的做法，就是一个大循环套四个小循环
    while top <= bottom and left <= right:
        # 左到右
        for j in range(left, right + 1):
            ans.append(matrix[top][j])
        top += 1
        # 上到下
        for i in range(top, bottom + 1):
            ans.append(matrix[i][right])
        right -= 1
        # 右到左，这里要判断一下top和bottom的关系，然后才能回过头走
        if top <= bottom:
            for j in range(right, left - 1, -1):
                ans.append(matrix[bottom][j])
            bottom -= 1
        # 下到上，判断left和right的关系
        if left <= right:
            for i in range(bottom, top - 1, -1):
                ans.append(matrix[i][left])
            left += 1
    return ans

if __name__ == "__main__":
    matrix = []
    while True:
        try:
            line = list(map(int,input().strip().split(',')))
            matrix.append(line)
        except EOFError:
            break
    print(solution(matrix))

2. 二刷

二刷用了变动即判断的思路，写的可能代码更多，但是思路更加清晰

3. 题解2 - 变动即判定

import ast

def solution(matrix:list[list[int]]) -> list[int]:
    if not matrix or not matrix[0]:
        return []
    # 四边界法
    m = len(matrix)
    n = len(matrix[0])
    top,left = 0, 0 
    bottom, right = m-1, n-1
    ans = []
    while True:
        for j in range(left,right+1):
            ans.append(matrix[top][j])
        top += 1
        if top > bottom:
            break

        for i in range(top,bottom+1):
            ans.append(matrix[i][right])
        right -= 1
        if left > right:
            break

        for j in range(right,left-1,-1):
            ans.append(matrix[bottom][j])
        bottom -= 1
        if top > bottom:
            break

        for i in range(bottom,top-1,-1):
            ans.append(matrix[i][left])
        left += 1
        if left > right:
            break
    return ans
    

 
if __name__ == "__main__":
    matrix = ast.literal_eval(input().strip())
    print(solution(matrix))

旋转图像

1. 题面

48. 旋转图像

难度：中等

给定一个 n × n 的二维矩阵 matrix 表示一个图像。请你将图像顺时针旋转 90 度。

你必须在原地旋转图像，这意味着你需要直接修改输入的二维矩阵。 请不要 使用另一个矩阵来旋转图像。

示例 1：

输入：matrix = [[1,2,3],[4,5,6],[7,8,9]]
输出：[[7,4,1],[8,5,2],[9,6,3]]

示例 2：

输入：matrix = [[5,1,9,11],[2,4,8,10],[13,3,6,7],[15,14,12,16]]
输出：[[15,13,2,5],[14,3,4,1],[12,6,8,9],[16,7,10,11]]

提示：

n == matrix.length == matrix[i].length
1 <= n <= 20
-1000 <= matrix[i][j] <= 1000

2. 题解

# 这一题的结论是，先沿主对角线翻转，然后再研轴翻转
def solution(matrix:list[list[int]])->None:
    # 先沿对角线翻转
    for i in range(len(matrix)):
        for j in range(i+1,len(matrix[0])):
            matrix[i][j],matrix[j][i] = matrix[j][i],matrix[i][j]
    # 再沿中轴翻转
    for line in matrix:
        line.reverse()

if __name__ == "__main__":
    matrix = []
    while True:
        try:
            line = list(map(int,input().strip().split(',')))
            matrix.append(line)
        except EOFError:
            break
    solution(matrix)
    print(matrix)

3. 二刷

秒了，这玩意也就考一遍套路

搜索二维矩阵 II

240. 搜索二维矩阵 II

难度：中等

编写一个高效的算法来搜索 _m_ x _n_ 矩阵 matrix 中的一个目标值 target 。该矩阵具有以下特性：

每行的元素从左到右升序排列。
每列的元素从上到下升序排列。

示例 1：

输入：matrix = [[1,4,7,11,15],[2,5,8,12,19],[3,6,9,16,22],[10,13,14,17,24],[18,21,23,26,30]], target = 5
输出：true

示例 2：

输入：matrix = [[1,4,7,11,15],[2,5,8,12,19],[3,6,9,16,22],[10,13,14,17,24],[18,21,23,26,30]], target = 20
输出：false

提示：

m == matrix.length
n == matrix[i].length
1 <= n, m <= 300
-10^9 <= matrix[i][j] <= 10^9
每行的所有元素从左到右升序排列
每列的所有元素从上到下升序排列
-10^9 <= target <= 10^9

1. 题解

# 基本做法是从右上角开始搜，如果大于target，肯定不在这一列，左移；如果小于target，直接往下搜索。
def solution(matrix, target) -> bool:
    m = len(matrix)
    n = len(matrix[0])
    i = 0
    j = n - 1

    while i < m and j >= 0:
        if matrix[i][j] == target:
            return True
        elif matrix[i][j] > target:
            j -= 1
        else:
            i += 1

    return False


if __name__ == "__main__":
    lines= []
    while True:
        try:
            # 一次性读入
            lines.append(input().strip())
        except EOFError:
            break
    target = int(lines[-1])
    # 注意这里的提取前面行数的方法
    matrix = [list(map(int, line.split(','))) for line in lines[:-1]]
    print(solution(matrix,target))

2. 反思

其实建议直接记住，另外注意输入的时候最后target的处理方式，即我们先拿到所有数据，然后再提取需要的量（用切片）

3. 二刷

右上角的要用i、j和m、n分开，思路倒是见一次就会了

相交链表

160. 相交链表

难度：简单

给你两个单链表的头节点 headA 和 headB ，请你找出并返回两个单链表相交的起始节点。如果两个链表不存在相交节点，返回 null 。

图示两个链表在节点 c1 开始相交：

题目数据保证整个链式结构中不存在环。

注意，函数返回结果后，链表必须 保持其原始结构 。

自定义评测：

评测系统 的输入如下（你设计的程序 不适用 此输入）：

intersectVal - 相交的起始节点的值。如果不存在相交节点，这一值为 0
listA - 第一个链表
listB - 第二个链表
skipA - 在 listA 中（从头节点开始）跳到交叉节点的节点数
skipB - 在 listB 中（从头节点开始）跳到交叉节点的节点数

评测系统将根据这些输入创建链式数据结构，并将两个头节点 headA 和 headB 传递给你的程序。如果程序能够正确返回相交节点，那么你的解决方案将被 视作正确答案 。

示例 1：

输入：intersectVal = 8, listA = [4,1,8,4,5], listB = [5,6,1,8,4,5], skipA = 2, skipB = 3
输出：Intersected at '8'
解释：相交节点的值为 8 （注意，如果两个链表相交则不能为 0）。
从各自的表头开始算起，链表 A 为 [4,1,8,4,5]，链表 B 为 [5,6,1,8,4,5]。
在 A 中，相交节点前有 2 个节点；在 B 中，相交节点前有 3 个节点。
— 请注意相交节点的值不为 1，因为在链表 A 和链表 B 之中值为 1 的节点 (A 中第二个节点和 B 中第三个节点) 是不同的节点。换句话说，它们在内存中指向两个不同的位置，而链表 A 和链表 B 中值为 8 的节点 (A 中第三个节点，B 中第四个节点) 在内存中指向相同的位置。

示例 2：

输入：intersectVal = 2, listA = [1,9,1,2,4], listB = [3,2,4], skipA = 3, skipB = 1
输出：Intersected at '2'
解释：相交节点的值为 2 （注意，如果两个链表相交则不能为 0）。
从各自的表头开始算起，链表 A 为 [1,9,1,2,4]，链表 B 为 [3,2,4]。
在 A 中，相交节点前有 3 个节点；在 B 中，相交节点前有 1 个节点。

示例 3：

输入：intersectVal = 0, listA = [2,6,4], listB = [1,5], skipA = 3, skipB = 2
输出：No intersection
解释：从各自的表头开始算起，链表 A 为 [2,6,4]，链表 B 为 [1,5]。
由于这两个链表不相交，所以 intersectVal 必须为 0，而 skipA 和 skipB 可以是任意值。
这两个链表不相交，因此返回 null 。

提示：

listA 中节点数目为 m
listB 中节点数目为 n
1 <= m, n <= 3 * 10^4
1 <= Node.val <= 10^5
0 <= skipA <= m
0 <= skipB <= n
如果 listA 和 listB 没有交点，intersectVal 为 0
如果 listA 和 listB 有交点，intersectVal == listA[skipA] == listB[skipB]

进阶： 你能否设计一个时间复杂度 O(m + n) 、仅用 O(1) 内存的解决方案？

1. 题解

# 这题解法倒是简单，作为第一道链表题，遍历完自己遍历别人就行，这样一定会和在相交点，如果不相交又一定会会和在None
# 主要是先熟悉一下ACM模式处理链表

class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 尾插法建立链表
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
    return dummy.next

# 将指针推至最后一个节点方便拼接
def get_tail(head):
    if not head:
        return None
    while head.next:
        head = head.next
    return head


def solution(headA: ListNode, headB: ListNode) -> ListNode:
    p = headA
    q = headB
    while p != q:
        p = p.next if p else headB
        q = q.next if q else headA
    return p


if __name__ == "__main__":
    # 第一行：A的独有部分
    # 第二行：B的独有部分
    # 第三行：公共尾部；如果不相交就输入空行
    partA = input().strip()
    partB = input().strip()
    common = input().strip()

    numsA = list(map(int, partA.split(','))) if partA else []
    numsB = list(map(int, partB.split(','))) if partB else []
    numsC = list(map(int, common.split(','))) if common else []

    headA = build_linked_list(numsA)
    headB = build_linked_list(numsB)
    headC = build_linked_list(numsC)

    if headC:
        tailA = get_tail(headA)
        tailB = get_tail(headB)

        if tailA:
            tailA.next = headC
        else:
            headA = headC

        if tailB:
            tailB.next = headC
        else:
            headB = headC

    ans = solution(headA, headB)
    print(ans.val if ans else 0)

2. 反思

如果是正常做思路非常简单的，但是如果要用ACM模式做，就要熟练掌握怎么写这些额外函数、怎么建链表，貌似精力都放在这上面来了。这题没让输出链表，不然还要写一个print_linked_list函数。

3. 二刷

不过是构建相交链表麻烦点，还有注意p可能为None，注意空值保护

反转链表

1. 题面

206. 反转链表

难度：简单

给你单链表的头节点 head ，请你反转链表，并返回反转后的链表。

示例 1：

输入：head = [1,2,3,4,5]
输出：[5,4,3,2,1]

示例 2：

输入：head = [1,2]
输出：[2,1]

示例 3：

输入：head = []
输出：[]

提示：

链表中节点的数目范围是 [0, 5000]
-5000 <= Node.val <= 5000

进阶： 链表可以选用迭代或递归方式完成反转。你能否用两种方法解决这道题？

2. 题解

# 三指针法在python中非常优雅]

class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 尾插法建立链表
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
    return dummy.next

# 打印链表
def print_linked_list(head):
    ans = []
    while head:
        ans.append(head.val)
        head = head.next
    print(ans)

def solution(head:ListNode)->ListNode:
    prev = None
    curr = head
    # 多重赋值
    while curr:
        curr.next, prev, curr = prev, curr, curr.next
    # 三链表反转之后，prev是头结点
    return prev

if __name__ =="__main__":
    nums = list(map(int,input().strip().split(',')))
    head = build_linked_list(nums)
    head = solution(head)
    print_linked_list(head)

3. 反思

这题多重赋值是Python最优雅的翻转链表方案，但是这一句要注意顺序问题。左边第一个目标是 curr.next，它会先把“旧 curr 的 next”改掉，然后再更新 prev 和 curr，这个顺序才是对的。

4. 二刷

秒了。注意多重赋值顺序

回文链表

1. 题面

234. 回文链表

难度：简单

给你一个单链表的头节点 head ，请你判断该链表是否为回文链表。如果是，返回 true ；否则，返回 false 。

示例 1：

输入：head = [1,2,2,1]
输出：true

示例 2：

输入：head = [1,2]
输出：false

提示：

链表中节点数目在范围[1, 10^5] 内
0 <= Node.val <= 9

进阶： 你能否用 O(n) 时间复杂度和 O(1) 空间复杂度解决此题？

2. 题解

# 本题进阶要求O(n)时间复杂度和常数空间复杂度，思路其实很简单，就是快慢指针
class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 尾插法建立链表
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
    return dummy.next


def solution(head:ListNode)->bool:
    slow = head
    fast = head
    while fast and fast.next:
        slow = slow.next
        fast = fast.next.next
    # 这是奇偶区分，如果是奇数（也就是fast不会走到None），那么slow要从后一个开始翻转
    if fast:
        slow = slow.next
    # 三指针翻转
    curr=slow
    prev=None
    while curr:
        curr.next,curr,prev=prev,curr.next,curr
    # 我们可以从头开始比较，如果翻转后链表跑完之前都和原链表相等，那么一定为回文
    while prev:
        if prev.val!=head.val:
            return False
        prev=prev.next
        head=head.next
    return True

if __name__ =="__main__":
    nums = list(map(int,input().strip().split(',')))
    head = build_linked_list(nums)
    print(solution(head))

3. 反思

本题是找中点、翻转的合并。关键点在于根据fast的位置，可以判断出链表的奇偶，从而决定从什么位置开始翻转后半部分。

4. 二刷

差点又掉坑里了，一定要fast and fast.next才行，然后，加dummy是偶数中前/奇数中间，不加dummy是偶数中后/奇数中间

环形链表

1. 题面

141. 环形链表

难度：简单

给你一个链表的头节点 head ，判断链表中是否有环。

如果链表中有某个节点，可以通过连续跟踪 next 指针再次到达，则链表中存在环。为了表示给定链表中的环，评测系统内部使用整数 pos 来表示链表尾连接到链表中的位置（索引从 0 开始）。 注意：pos 不作为参数进行传递 。仅仅是为了标识链表的实际情况。

如果链表中存在环 ，则返回 true 。否则，返回 false 。

示例 1：

输入：head = [3,2,0,-4], pos = 1
输出：true
解释：链表中有一个环，其尾部连接到第二个节点。

示例 2：

输入：head = [1,2], pos = 0
输出：true
解释：链表中有一个环，其尾部连接到第一个节点。

示例 3：

输入：head = [1], pos = -1
输出：false
解释：链表中没有环。

提示：

链表中节点的数目范围是 [0, 10^4]
-10^5 <= Node.val <= 10^5
pos 为 -1 或者链表中的一个 有效索引 。

进阶： 你能用 O(1)（即，常量）内存解决此问题吗？

2. 题解

# 本题也是经典结论，fast走两步，slow走一步，最终如果相遇则有环
class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 这里升级了一下，直接返回头指针+节点列表
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    nodes = []
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
        nodes.append(cur)
    return dummy.next, nodes

def solution(head:ListNode)->bool:
    slow,fast = head,head
    while fast and fast.next:
        fast = fast.next.next
        slow = slow.next
        if fast == slow:
            return True
    return False

if __name__ == "__main__":
    nums_line = input().strip()
    pos = int(input().strip())

    # 注意这里有个判空逻辑
    nums = list(map(int, nums_line.split(','))) if nums_line else []
    head, nodes = build_linked_list(nums)

    if pos != -1 and nodes:
        nodes[-1].next = nodes[pos]

    print(solution(head))

3. 反思

注意这题的ACM模式，在建链表的时候也建一个nodes数组，这样方便我们直接看pos的位置。

4. 二刷

二刷就先不做了，一眼可以想到快慢指针法，但是定义输入比较麻烦，一般不会出这样的题目。

5. 三刷

出现了以下的错误写法：

def solution(self,head:ListNode)->bool:
    fast,slow = head,head
    while fast != slow:
        fast = fast.next.next
        slow = slow.next
    if slow:
        return True
    else:
        return False

这要是没有环直接就炸了，一定要记得一个fast and fast.next的逻辑，非常常用。

环形链表 II

1. 题面

142. 环形链表 II

难度：中等

给定一个链表的头节点 head ，返回链表开始入环的第一个节点。 如果链表无环，则返回 null。

如果链表中有某个节点，可以通过连续跟踪 next 指针再次到达，则链表中存在环。为了表示给定链表中的环，评测系统内部使用整数 pos 来表示链表尾连接到链表中的位置（ 索引从 0 开始 ）。如果 pos 是 -1，则在该链表中没有环。 注意：pos 不作为参数进行传递 ，仅仅是为了标识链表的实际情况。

不允许修改 链表。

示例 1：

输入：head = [3,2,0,-4], pos = 1
输出：返回索引为 1 的链表节点
解释：链表中有一个环，其尾部连接到第二个节点。

示例 2：

输入：head = [1,2], pos = 0
输出：返回索引为 0 的链表节点
解释：链表中有一个环，其尾部连接到第一个节点。

示例 3：

输入：head = [1], pos = -1
输出：返回 null
解释：链表中没有环。

提示：

链表中节点的数目范围在范围 [0, 10^4] 内
-10^5 <= Node.val <= 10^5
pos 的值为 -1 或者链表中的一个有效索引

进阶： 你是否可以使用 O(1) 空间解决此题？

2. 题解

# 本题不仅要看有没有环，还要看环在哪
# 实际上跟上一题基本没有区别，就是相遇之后，还有拍一个新的小兵从起点出发，然后再和slow相遇，对应的节点就是返回的点。
class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 这里升级了一下，直接返回头指针+节点列表
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    nodes = []
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
        nodes.append(cur)
    return dummy.next, nodes

def solution(head:ListNode)->ListNode:
    slow,fast = head,head
    while fast and fast.next:
        fast = fast.next.next
        slow = slow.next
        if fast == slow:
            break
    # 派遣小兵
    start = head
    while slow !=start:
        slow = slow.next
        start = start.next
    return start

if __name__ == "__main__":
    nums_line = input().strip()
    pos = int(input().strip())

    # 注意这里有个判空逻辑
    nums = list(map(int, nums_line.split(','))) if nums_line else []
    head, nodes = build_linked_list(nums)

    if pos != -1 and nodes:
        nodes[-1].next = nodes[pos]

    print(solution(head).val)

3. 反思

没啥好说的，记结论

4. 二刷

同上题，二刷跳过

合并两个有序链表

1. 题面

21. 合并两个有序链表

难度：简单

将两个升序链表合并为一个新的升序链表并返回。新链表是通过拼接给定的两个链表的所有节点组成的。

示例 1：

输入：l1 = [1,2,4], l2 = [1,3,4]
输出：[1,1,2,3,4,4]

示例 2：

输入：l1 = [], l2 = []
输出：[]

示例 3：

输入：l1 = [], l2 = [0]
输出：[0]

提示：

两个链表的节点数目范围是 [0, 50]
-100 <= Node.val <= 100
l1 和 l2 均按 非递减顺序 排列

2. 题解

# 非常经典的合并链表题，可以从穿针引线的角度考虑，用新dummy去合并

class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 尾插法建立链表
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
    return dummy.next

# 打印链表
def print_linked_list(head):
    ans = []
    while head:
        ans.append(head.val)
        head = head.next
    print(ans)

def solution(l1:ListNode,l2:ListNode)->ListNode:
    dummy = ListNode()
    p = dummy
    while l1 and l2:
        if l1.val>=l2.val:
            p.next = l2
            l2 =l2.next
        else:
            p.next = l1
            l1 = l1.next
        p = p.next
    if l1:
        p.next = l1
    if l2:
        p.next = l2
    return dummy.next

if __name__ == "__main__":
    nums_l1 = list(map(int,input().strip().split(',')))
    nums_l2 = list(map(int,input().strip().split(',')))
    l1 = build_linked_list(nums_l1)
    l2 = build_linked_list(nums_l2)
    head = solution(l1,l2)
    print_linked_list(head)

3. 二刷

秒了

两数相加

1. 题面

2. 两数相加

难度：中等

给你两个非空的链表，表示两个非负的整数。它们每位数字都是按照逆序的方式存储的，并且每个节点只能存储一位数字。

请你将两个数相加，并以相同形式返回一个表示和的链表。

你可以假设除了数字 0 之外，这两个数都不会以 0 开头。

示例 1：

输入：l1 = [2,4,3], l2 = [5,6,4]
输出：[7,0,8]
解释：342 + 465 = 807.

示例 2：

输入：l1 = [0], l2 = [0]
输出：[0]

示例 3：

输入：l1 = [9,9,9,9,9,9,9], l2 = [9,9,9,9]
输出：[8,9,9,9,0,0,0,1]

提示：

每个链表中的节点数在范围 [1, 100] 内
0 <= Node.val <= 9
题目数据保证列表表示的数字不含前导零

2. 题解

# 这题就是竖式加法，还贴心给你逆序好了，这种板子属于必须背下来的地步

class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 尾插法建立链表
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
    return dummy.next

# 打印链表
def print_linked_list(head):
    ans = []
    while head:
        ans.append(head.val)
        head = head.next
    print(ans)

def solution(l1:ListNode,l2:ListNode)->ListNode:
    carry = 0
    dummy = ListNode()
    p = dummy
    while l1 or l2 or carry:
        a = l1.val if l1 else 0
        b = l2.val if l2 else 0
        total = a+b+carry
        carry = total//10
        p.next= ListNode(total%10)
        if l1:
            l1 = l1.next
        if l2:
            l2 = l2.next
        p = p.next
    return dummy.next

if __name__ == "__main__":
    nums_l1 = list(map(int,input().strip().split(',')))
    nums_l2 = list(map(int,input().strip().split(',')))
    l1 = build_linked_list(nums_l1)
    l2 = build_linked_list(nums_l2)
    head = solution(l1,l2)
    print_linked_list(head)

3. 反思

依旧直接背板，一定要熟练。易错点两个，一个是l1不为空才能next，另一个是carry和total都是本轮算本轮的，千万别+=

4. 二刷

二刷犯下的错误是next之前忘了判断l1 or l2是否已经为空了。其他倒是没什么可说的。

5. 拓展1 - 正序字符串

如果给的是正序两个字符串怎么办，这是一般的符合直觉的大数加法题，解法也合直觉，从末尾往前加，最后返回答案的时候进行一次翻转。注意用ord(字符)-ord('0')转数字即可。

def add_strings(a: str, b: str) -> str:
    i = len(a) - 1
    j = len(b) - 1
    carry = 0
    ans = []

    while i >= 0 or j >= 0 or carry:
        x = ord(a[i]) - ord('0') if i >= 0 else 0
        y = ord(b[j]) - ord('0') if j >= 0 else 0

        total = x + y + carry
        ans.append(str(total % 10))
        carry = total // 10

        i -= 1
        j -= 1

    return ''.join(reversed(ans))

删除链表的倒数第 N 个结点

1. 题面

19. 删除链表的倒数第 N 个结点

难度：中等

给你一个链表，删除链表的倒数第 n 个结点，并且返回链表的头结点。

示例 1：

输入：head = [1,2,3,4,5], n = 2
输出：[1,2,3,5]

示例 2：

输入：head = [1], n = 1
输出：[]

示例 3：

输入：head = [1,2], n = 1
输出：[1]

提示：

链表中结点的数目为 sz
1 <= sz <= 30
0 <= Node.val <= 100
1 <= n <= sz

进阶： 你能尝试使用一趟扫描实现吗？

2. 题解

# 双指针当尺子就行了
class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 尾插法建立链表
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
    return dummy.next

# 打印链表
def print_linked_list(head):
    ans = []
    while head:
        ans.append(head.val)
        head = head.next
    print(ans)

def solution(head:ListNode,n:int)->ListNode:
    # 有可能删除头结点，所以用dummy
    dummy = ListNode()
    dummy.next =head
    slow,fast = dummy,dummy
    for _ in range(n):
        fast = fast.next
    while fast.next:
        slow = slow.next
        fast = fast.next
    # 现在slow在待删除元素前面
    slow.next= slow.next.next
    return dummy.next

if __name__ =="__main__":
    nums_line = input().strip()
    n = int(input().strip())

    # 注意这里有个判空逻辑
    nums = list(map(int, nums_line.split(','))) if nums_line else []
    head = build_linked_list(nums)
    head = solution(head,n)
    print_linked_list(head)

3. 反思

注意点只有一个，就是删除节点要加dummy，因为头也可能被删

4. 二刷

注意点同上，不用重复写了

两两交换列表中的节点

1. 题面

24. 两两交换链表中的节点

难度：中等

给你一个链表，两两交换其中相邻的节点，并返回交换后链表的头节点。你必须在不修改节点内部的值的情况下完成本题（即，只能进行节点交换）。

示例 1：

输入：head = [1,2,3,4]
输出：[2,1,4,3]

示例 2：

输入：head = []
输出：[]

示例 3：

输入：head = [1]
输出：[1]

提示：

链表中节点的数目在范围 [0, 100] 内
0 <= Node.val <= 100

2. 题解 1 · 直接翻转

# 这题有两种解法，一种是递归，另一种是每次记住翻转前的头结点作为tail，连上curr（curr会天然跑到下一个节点）
# 先来最直观的
class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 尾插法建立链表
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
    return dummy.next

# 打印链表
def print_linked_list(head):
    ans = []
    while head:
        ans.append(head.val)
        head = head.next
    print(ans)

def solution(head:ListNode)->ListNode:
    if not head or not head.next:
        return head
    dummy = ListNode()
    dummy.next = head
    list_pre = dummy
    curr = head
    while curr and curr.next:
        tail = curr
        prev = None
        # 翻转两次
        for _ in range(2):
            curr.next,curr,prev = prev,curr.next,curr
        # 接上翻转过的链表
        tail.next = curr
        list_pre.next = prev
        list_pre = tail
    return dummy.next

if __name__ =="__main__":
    nums = list(map(int,input().strip().split(',')))
    head = build_linked_list(nums)
    head = solution(head)
    print_linked_list(head)

3. 题解 2 · 递归处理

# 递归的解法，我们需要假设solution函数返回的就是两两交换好的节点，所以我们只要排当前的两个，然后后面交给递归黑箱就行了
class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 尾插法建立链表
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
    return dummy.next

# 打印链表
def print_linked_list(head):
    ans = []
    while head:
        ans.append(head.val)
        head = head.next
    print(ans)

def solution(head:ListNode)->ListNode:
    # 同样小于两个节点的话不用找了
    if not head or not head.next:
        return head
    # 调转的时候指向黑箱递归
    new_head = head.next
    head.next = solution(new_head.next)
    new_head.next = head
    return new_head


if __name__ =="__main__":
    nums = list(map(int,input().strip().split(',')))
    head = build_linked_list(nums)
    head = solution(head)
    print_linked_list(head)

4. 反思

这题第一种解法在解决k个翻转的时候也很给力，递归的解法最容易理解代码最简洁，都需要掌握

5. 二刷

递归秒了。注意如果准备直接翻转的话要自己额外定义tail（也就是每次翻转的curr）

k个一组翻转链表

1. 题面

25. K 个一组翻转链表

难度：困难

给你链表的头节点 head ，每 k 个节点一组进行翻转，请你返回修改后的链表。

k 是一个正整数，它的值小于或等于链表的长度。如果节点总数不是 k 的整数倍，那么请将最后剩余的节点保持原有顺序。

你不能只是单纯的改变节点内部的值，而是需要实际进行节点交换。

示例 1：

输入：head = [1,2,3,4,5], k = 2
输出：[2,1,4,3,5]

示例 2：

输入：head = [1,2,3,4,5], k = 3
输出：[3,2,1,4,5]

提示：

链表中的节点数目为 n
1 <= k <= n <= 5000
0 <= Node.val <= 1000

进阶： 你可以设计一个只用 O(1) 额外内存空间的算法解决此问题吗？

2. 题解

# 我们先按照两个一组的解法改一下，直接做成k个一组。不同点在于我们可能需要先遍历一下，数数节点个数，这样才知道我们需要进行多少次k翻转
class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 尾插法建立链表
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
    return dummy.next

# 打印链表
def print_linked_list(head):
    ans = []
    while head:
        ans.append(head.val)
        head = head.next
    print(ans)

def solution(head:ListNode,k:int)->ListNode:
    dummy = ListNode()
    dummy.next = head
    ct = head
    count = 0
    while ct:
        ct = ct.next
        count += 1
    times = count//k
    # 开始times次翻转
    curr = head
    list_pre = dummy
    for _ in range(times):
        # k翻转准备工作，标记tail
        tail = curr
        prev = None
        # k翻转本题
        for _ in range(k):
            curr.next,curr,prev = prev,curr.next,curr
        # 接上节点
        list_pre.next = prev
        tail.next = curr
        # 准备下次k翻转
        list_pre = tail
    return dummy.next



if __name__ =="__main__":
    nums = list(map(int,input().strip().split(',')))
    k = int(input().strip())
    head = build_linked_list(nums)
    head = solution(head,k)
    print_linked_list(head)

3. 题解 2 · 递归

# 跟上题一样，递归思路自然是最简单。先检查够不够k，不够就返回。然后进行k个翻转，将下一个连接到黑箱就行。
class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 尾插法建立链表
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
    return dummy.next

# 打印链表
def print_linked_list(head):
    ans = []
    while head:
        ans.append(head.val)
        head = head.next
    print(ans)

def solution(head: ListNode, k: int) -> ListNode:
    cur = head
    for _ in range(k):
        if not cur:
            return head
        cur = cur.next

    prev = None
    curr = head
    for _ in range(k):
        curr.next, curr, prev = prev, curr.next, curr

    head.next = solution(curr, k)
    return prev


if __name__ =="__main__":
    nums = list(map(int,input().strip().split(',')))
    k = int(input().strip())
    head = build_linked_list(nums)
    head = solution(head,k)
    print_linked_list(head)

4. 反思

和上提一样，一个直接做，一个递归。直接做有助于思考三指针翻转后的指针都在哪，递归则是容易理解好做的思路。

5. 二刷

递归很容易想到，这次我用了一个辅助函数来统计k，和递归内走k格子看空不空一样。

随机链表的复制

1. 题面

138. 随机链表的复制

难度：中等

给你一个长度为 n 的链表，每个节点包含一个额外增加的随机指针 random ，该指针可以指向链表中的任何节点或空节点。

构造这个链表的 深拷贝 。深拷贝应该正好由 n 个全新节点组成，其中每个新节点的值都设为其对应的原节点的值。新节点的 next 指针和 random 指针也都应指向复制链表中的新节点，并使原链表和复制链表中的这些指针能够表示相同的链表状态。 复制链表中的指针都不应指向原链表中的节点 。

例如，如果原链表中有 X 和 Y 两个节点，其中 X.random --> Y 。那么在复制链表中对应的两个节点 x 和 y ，同样有 x.random --> y 。

返回复制链表的头节点。

用一个由 n 个节点组成的链表来表示输入/输出中的链表。每个节点用一个 [val, random_index] 表示：

val：一个表示 Node.val 的整数。
random_index：随机指针指向的节点索引（范围从 0 到 n-1）；如果不指向任何节点，则为 null 。

你的代码只接受原链表的头节点 head 作为传入参数。

示例 1：

输入：head = [[7,null],[13,0],[11,4],[10,2],[1,0]]
输出：[[7,null],[13,0],[11,4],[10,2],[1,0]]

示例 2：

输入：head = [[1,1],[2,1]]
输出：[[1,1],[2,1]]

示例 3：

输入：head = [[3,null],[3,0],[3,null]]
输出：[[3,null],[3,0],[3,null]]

提示：

0 <= n <= 1000
-10^4 <= Node.val <= 10^4
Node.random 为 null 或指向链表中的节点。

2. 题解

# 随机链表的复制，要求还原原链表的所有指针。其实所有数据结构的复制都是一样的，先复制节点内容，再复制关系。用哈希表做一个旧对新的存储即可。
import ast


class Node:
    def __init__(self, x: int, next: 'Node' = None, random: 'Node' = None):
        self.val = int(x)
        self.next = next
        self.random = random


def build_random_list(data):
    if not data:
        return None

    nodes = [Node(val) for val, _ in data]

    for i in range(len(nodes) - 1):
        nodes[i].next = nodes[i + 1]

    for i, (_, random_idx) in enumerate(data):
        if random_idx is not None:
            nodes[i].random = nodes[random_idx]

    return nodes[0]


def print_random_list(head):
    nodes = []
    node_to_idx = {}
    p = head
    idx = 0
    while p:
        nodes.append(p)
        node_to_idx[p] = idx
        p = p.next
        idx += 1

    ans = []
    for node in nodes:
        random_idx = node_to_idx[node.random] if node.random else None
        ans.append([node.val, random_idx])
    print(ans)


def solution(head: Node) -> Node:
    # 不用deepcopy外挂的话，记住数据结构复制就一个哈希表+两次遍历：第一次遍历专门克隆节点，借助哈希表把原始节点和克隆节点的映射存储起来；第二次专门组装节点，照着原数据结构的样子，把克隆节点的指针组装起来
    originToClone = {}
    # 第一遍遍历，克隆节点
    p = head
    while p:
        if p not in originToClone:
            originToClone[p] = Node(p.val)
        p = p.next
    # 第二次遍历，组装节点
    p = head
    while p:
        # 克隆之孩子等于孩子之克隆
        if p.next:
            originToClone[p].next = originToClone[p.next]
        if p.random:
            originToClone[p].random = originToClone[p.random]
        p = p.next
    return originToClone.get(head)


if __name__ == "__main__":
    line = input().strip()
    data = ast.literal_eval(line.replace("null", "None")) if line else []
    head = build_random_list(data)
    head = solution(head)
    print_random_list(head)

3. 反思

重点看solution部分，但是也可以看一下python的厉害。先用replace换成可以解析的字面量，然后用ast.literal_eval(...)，可以直接解析，将字符串形式的嵌套列表，转化为真列表。

4. 二刷

没有再刷了，输入输出弄的太麻烦，思路其实很简单。originToClone[p].next = originToClone[p.next]这句话理解清楚就行。

排序链表

1. 题面

148. 排序链表

难度：中等

给你链表的头结点 head ，请将其按升序排列并返回 排序后的链表 。

示例 1：

输入：head = [4,2,1,3]
输出：[1,2,3,4]

示例 2：

输入：head = [-1,5,3,4,0]
输出：[-1,0,3,4,5]

示例 3：

输入：head = []
输出：[]

提示：

链表中节点的数目在范围 [0, 5 * 10^4] 内
-10^5 <= Node.val <= 10^5

**进阶：**你可以在 O(n log n) 时间复杂度和常数级空间复杂度下，对链表进行排序吗？

2. 题解 1 · 数组复制

# 进阶要求是，在nlogn时间范围内完成，也就是快排。最简单能想到的是，建一个数组，排序数组，然后按数组重建链表
class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 尾插法建立链表 + 数组
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    nodes = []
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
        nodes.append(cur.val)
    return dummy.next, nodes

# 打印链表
def print_linked_list(head):
    ans = []
    while head:
        ans.append(head.val)
        head = head.next
    print(ans)


if __name__ =="__main__":
    nums = list(map(int,input().strip().split(',')))
    head, nodes = build_linked_list(nums)
    nodes.sort()
    head ,nodes = build_linked_list(nodes)
    print_linked_list(head)

3. 题解 2 · 归并排序

# 但是，这一题可以更简化到Onlogn+logn额外栈空间，也是力扣真的想考的方法，归并排序。
class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 尾插法建立链表
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
    return dummy.next

# 打印链表
def print_linked_list(head):
    ans = []
    while head:
        ans.append(head.val)
        head = head.next
    print(ans)

def solution(head: ListNode) -> ListNode:
    if not head or not head.next:
        return head

    # 快慢指针找中点，并断开链表
    slow, fast = head, head.next
    while fast and fast.next:
        slow = slow.next
        fast = fast.next.next

    mid = slow.next
    slow.next = None

    left = solution(head)
    right = solution(mid)

    # 合并两个有序链表
    dummy = ListNode()
    p = dummy
    while left and right:
        if left.val < right.val:
            p.next = left
            left = left.next
        else:
            p.next = right
            right = right.next
        p = p.next

    p.next = left if left else right
    return dummy.next


if __name__ =="__main__":
    nums = list(map(int,input().strip().split(',')))
    head = build_linked_list(nums)
    head = solution(head)
    print_linked_list(head)

4. 反思

这一题想看的是解法二，解法一纯钻空子。注意这里有三步，首先设置递归出口，然后快慢指针寻找中点（注意这里的fast设置在head.next的起点，就可以自然让slow停在mid前面，不用借助dummy），最后递归排序两边。后面是标准的排序两个有序链表的过程。
然后就是力扣里面函数本身带self，记得递归的时候self.func

5. 二刷

想到用分治了，不断进行下去直到两边都有序。但是问题是忘记了最关键的部分，也就是mid = slow.next和slow.next = None。为什么要先断开后面的链表？否则左侧会一直走到右侧，就不是想要的合并两边有序链表了。不用担心会被切碎碎，因为后面合并的步骤会组装起来。
虽然跟这题关系不大，但是合并时p.next = left if left else right可以体现python的简洁美。

6. 拓展

这一题，就是经典的归并排序链表版。我们下面可以给出数组版本的归并排序：

def solution(nums: list[int]) -> list[int]:
    if len(nums) <= 1:
        return nums

    mid = len(nums) // 2
    left = solution(nums[:mid])
    right = solution(nums[mid:])

    return merge(left, right)


def merge(left: list[int], right: list[int]) -> list[int]:
    i, j = 0, 0
    ans = []

    while i < len(left) and j < len(right):
        if left[i] <= right[j]:
            ans.append(left[i])
            i += 1
        else:
            ans.append(right[j])
            j += 1

    ans.extend(left[i:])
    ans.extend(right[j:])
    return ans

一般我们喜欢把merge函数拎出去，这样看起来更清楚。本题的链表归并排序，也可以写成这样：

class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next


def merge(headA: ListNode, headB: ListNode) -> ListNode:
    dummy = ListNode()
    p = dummy

    while headA and headB:
        if headA.val <= headB.val:
            p.next = headA
            headA = headA.next
        else:
            p.next = headB
            headB = headB.next
        p = p.next

    p.next = headA if headA else headB
    return dummy.next


def solution(head: ListNode) -> ListNode:
    if not head or not head.next:
        return head

    dummy = ListNode()
    dummy.next = head
    slow, fast = dummy, dummy

    # 找中点，断开成两半
    while fast and fast.next:
        fast = fast.next.next
        slow = slow.next

    mid = slow.next
    slow.next = None

    left = solution(head)
    right = solution(mid)

    return merge(left, right)

7. 题解3

竟然有人面试被问到了链表的快速排序，那就也在这里做一下。一般快排做法是选枢纽，断三段，最后递归排序左右两段，然后拼接。在链表中，这个pivot一般就取头结点（数组中是randomint）。（不用 tail 也能 append，但是每次需要遍历到末尾。为了方便append，我们改动一下尾插法，让每次返回的一个元组，包含head和tail节点）。

class ListNode:
    def __init__(self, val = 0 ,next = None):
        self.val = val
        self.next = next

def _append(head,tail,node):
    node.next = None
    if not head:
        return node,node
    tail.next = node
    return head,node

def _concat(left,mid,right):
    dummy = ListNode(0)
    curr = dummy
    for h in (left,mid,right):
        if h:
            curr.next = h
            while curr.next:
                curr = curr.next
    return dummy.next

def sortList(head:ListNode):
    if not head or not head.next:
        return head
    pivot = head
    less = eq = greater = None
    less_tail = eq_tail = greater_tail = None

    curr = head
    while curr:
        nxt = curr.next
        if curr.val<pivot.val:
            less,less_tail = _append(less,less_tail,curr)
        elif curr.val > pivot.val:
            greater, greater_tail = _append(greater,greater_tail,curr)
        else:
            eq,eq_tail = _append(eq,eq_tail,curr)
        curr = nxt
    
    left = sortList(less)
    right = sortList(greater)

    return _concat(left,eq,right)

合并 K 个升序链表

1. 题面

23. 合并 K 个升序链表

难度：困难

给你一个链表数组，每个链表都已经按升序排列。

请你将所有链表合并到一个升序链表中，返回合并后的链表。

示例 1：

输入：lists = [[1,4,5],[1,3,4],[2,6]]
输出：[1,1,2,3,4,4,5,6]
解释：链表数组如下：
[
  1->4->5,
  1->3->4,
  2->6
]
将它们合并到一个有序链表中得到。
1->1->2->3->4->4->5->6

示例 2：

输入：lists = []
输出：[]

示例 3：

输入：lists = [[]]
输出：[]

提示：

k == lists.length
0 <= k <= 10^4
0 <= lists[i].length <= 500
-10^4 <= lists[i][j] <= 10^4
lists[i] 按升序排列
lists[i].length 的总和不超过 10^4

2. 题解 1 · 堆排序

# 合并k个升序链表，我们可以用堆来做。将值和节点对入堆，然后每次拿出最小的让p指向。
# 还需要放一个idx，这是因为堆比完第一个相同自动比第二个。这是万万不行的，需要在二位弄一个idx保护。
import ast
import heapq
class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 这里升级了一下，直接返回头指针
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
    return dummy.next

# 打印链表
def print_linked_list(head):
    ans = []
    while head:
        ans.append(head.val)
        head = head.next
    print(ans)


def solution(lists: list[ListNode]) -> ListNode:
    heap = []
    dummy = ListNode()
    p = dummy

    # 建堆
    for i, node in enumerate(lists):
        if node:
            heapq.heappush(heap, (node.val, i, node))

    # 弹堆，每次弹之后将弹出的节点下一个节点入堆
    while heap:
        _, i, node = heapq.heappop(heap)
        p.next = node
        p = p.next

        if node.next:
            heapq.heappush(heap, (node.next.val, i, node.next))

    return dummy.next


if __name__ == "__main__":
    # 输入二维数组
    line = input().strip()
    data = ast.literal_eval(line)
    headlist = []
    for nums in data:
        headlist.append(build_linked_list(nums))
    print_linked_list(solution(headlist))

3. 题解 2 · 分治

# 合并k个升序链表，我们可以用堆来做。将值和节点对入堆，然后每次拿出最小的让p指向。
# 还需要放一个idx，这是因为堆比完第一个相同自动比第二个。这是万万不行的，需要在二位弄一个idx保护。
import ast
import heapq
class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 这里升级了一下，直接返回头指针
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
    return dummy.next

# 打印链表
def print_linked_list(head):
    ans = []
    while head:
        ans.append(head.val)
        head = head.next
    print(ans)


def merge2Lists(l1,l2):
    # 穿针引线
    dummy = ListNode(-1)
    p = dummy
    p1, p2 =l1, l2
    while p1 and p2:
        if p1.val<=p2.val:
            p.next = p1
            p1 = p1.next
        else:
            p.next = p2
            p2 = p2.next
        p = p.next

    # 看看有没有合并完毕
    p.next = p1 if p1 else p2
    return dummy.next

# 辅助函数，让List[start,end)也合并成有序链表
def mergeLists(lists,start,end):
    # 就一个表
    if start == end:
        return lists[start]
    if start > end:
        return None
    # 折半合并
    mid = (start + end) //2
    # 合并左右半边
    # 这里left包含一下mid
    left = mergeLists(lists,start,mid)
    right = mergeLists(lists,mid+1,end)
    return merge2Lists(left,right)



def mergeKLists(lists:list[ListNode]) -> ListNode:
    # 不借助优先队列，可以采用分治思想
    # 从中间切开将两边变得有序，然后再合并
    if len(lists) == 0:
        return None
    left = 0
    right = len(lists)-1
    return mergeLists(lists,left,right)


if __name__ == "__main__":
    # 输入二维数组
    line = input().strip()
    data = ast.literal_eval(line)
    headlist = []
    for nums in data:
        headlist.append(build_linked_list(nums))
    print_linked_list(mergeKLists(headlist))

4. 反思

第一种方案是用堆自动排序，体现了堆可以存很多种不同的结果；第二种则是分治算法的体现，理解稍微复杂，实际上就是分成两边做让递归数尽可能矮。本质上也是先分两边不断递归排完left、right，然后进行两个有序链表合并的归并。

5. 二刷

理解了归并排序之后，这次也能轻松写出归并算法了，但是递归出口还是写错了。要注意两个：

递归出口不用写2，可以交给后面统一分治；
递归出口返回的一定要是函数期望返回的类型，这是底线。

本题比上述题解更简洁的做法如下：

import ast

class ListNode:
    def __init__(self, val = 0, next = None):
        self.val = val
        self.next = next

# 从列表建立链表
def build_list(nums:list):
    dummy = ListNode(0)
    p = dummy
    for num in nums:
        p.next = ListNode(num)
        p = p.next
    return dummy.next

# 打印链表
def print_list(head:ListNode) -> None:
    ans = []
    while head:
        ans.append(head.val)
        head = head.next
    print(ans)

# 辅助函数，合并两个有序链表
def merge(l1:ListNode,l2:ListNode) -> ListNode:
    dummy = ListNode()
    p = dummy
    while l1 and l2:
        if l1.val <= l2.val:
            p.next = l1
            l1 = l1.next
        else:
            p.next = l2
            l2 = l2.next
        p = p.next
    p.next = l1 if l1 else l2
    return dummy.next


def solution(lists:list[ListNode]) -> ListNode:
    n = len(lists)
    if n == 1:
        return lists[0]
    if n == 0:
        return None
    mid = n//2
    left = solution(lists[:mid])
    right = solution(lists[mid:])
    return merge(left,right)
        

if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    lists = []
    for num in nums:
        lists.append(build_list(num))
    print_list(solution(lists))

LRU缓存

1. 题面

146. LRU 缓存

难度：中等

请你设计并实现一个满足 LRU (最近最少使用) 缓存约束的数据结构。

实现 LRUCache 类：

LRUCache(int capacity) 以 正整数 作为容量 capacity 初始化 LRU 缓存
int get(int key) 如果关键字 key 存在于缓存中，则返回关键字的值，否则返回 -1 。
void put(int key, int value) 如果关键字 key 已经存在，则变更其数据值 value ；如果不存在，则向缓存中插入该组 key-value 。如果插入操作导致关键字数量超过 capacity ，则应该逐出最久未使用的关键字。

函数 get 和 put 必须以 O(1) 的平均时间复杂度运行。

示例：

输入
["LRUCache", "put", "put", "get", "put", "get", "put", "get", "get", "get"]
[[2], [1, 1], [2, 2], [1], [3, 3], [2], [4, 4], [1], [3], [4]]
输出
[null, null, null, 1, null, -1, null, -1, 3, 4]

解释
LRUCache lRUCache = new LRUCache(2);
lRUCache.put(1, 1); // 缓存是 {1=1}
lRUCache.put(2, 2); // 缓存是 {1=1, 2=2}
lRUCache.get(1);    // 返回 1
lRUCache.put(3, 3); // 该操作会使得关键字 2 作废，缓存是 {1=1, 3=3}
lRUCache.get(2);    // 返回 -1 (未找到)
lRUCache.put(4, 4); // 该操作会使得关键字 1 作废，缓存是 {4=4, 3=3}
lRUCache.get(1);    // 返回 -1 (未找到)
lRUCache.get(3);    // 返回 3
lRUCache.get(4);    // 返回 4

提示：

1 <= capacity <= 3000
0 <= key <= 10000
0 <= value <= 10^5
最多调用 2 * 10^5 次 get 和 put

2. 题解

# 这题非常非常典型，实现方法是双链表+哈希表。哈希表负责快查，双向链表维持最近使用顺序。双向链表的顺序是，头部为最新使用，尾部为最久没使用。如果get就将元素移动到头部，put直接放在头部，容量超出了，就删除尾部。
# 现在，请背板
import ast


class Node:
    # 初始化双链表节点
    def __init__(self, key=0, val=0):
        self.key = key
        self.val = val
        self.prev = None
        self.next = None


class LRUCache:
    # 在此基础上初始化容量、cache哈希表、头尾节点
    def __init__(self, capacity: int):
        self.capacity = capacity
        self.cache = {}

        self.dummy_head = Node()
        self.dummy_tail = Node()
        self.dummy_head.next = self.dummy_tail
        self.dummy_tail.prev = self.dummy_head

    def remove(self, node):
        # 双链表删除
        node.prev.next = node.next
        node.next.prev = node.prev

    # 加入最前面
    def push_front(self, node):
        node.next = self.dummy_head.next
        node.next.prev = node
        self.dummy_head.next = node
        node.prev = self.dummy_head

    # 访问后移动到前面
    def move_to_front(self, node):
        self.remove(node)
        self.push_front(node)

    def pop_tail(self):
        node = self.dummy_tail.prev
        self.remove(node)
        return node

    def get(self, key: int) -> int:
        # 有返回值没有返回-1
        if key not in self.cache:
            return -1
        node = self.cache[key]
        self.move_to_front(node)
        return node.val

    def put(self, key: int, value: int) -> None:
        # 如果有，更新值
        if key in self.cache:
            node = self.cache[key]
            node.val = value
            self.move_to_front(node)
            return
        # 没有的话新建
        node = Node(key, value)
        self.cache[key] = node
        self.push_front(node)

        if len(self.cache) > self.capacity:
            removed = self.pop_tail()
            del self.cache[removed.key]


if __name__ == "__main__":
    ops = ast.literal_eval(input().strip().replace("null", "None"))
    args = ast.literal_eval(input().strip().replace("null", "None"))

    ans = []
    lru = None

    for op, arg in zip(ops, args):
        if op == "LRUCache":
            lru = LRUCache(arg[0])
            ans.append(None)
        elif op == "put":
            lru.put(arg[0], arg[1])
            ans.append(None)
        elif op == "get":
            ans.append(lru.get(arg[0]))

    print(str(ans).replace("None", "null"))

3. 反思

这题代码看似复杂，实际上就是打一个双链表板子。

4. 二刷

最近听到面试的时候经常会被问LRU的升级版，比如支持并发的LRU，支持TTL的LRU，很恶心。接下来给一个带TTL和并发锁的最简单升级版：

import time
import threading


class Node:
    def __init__(self, key=0, val=0, expire_at=float("inf")):
        self.key = key
        self.val = val
        self.expire_at = expire_at
        self.prev = None
        self.next = None


class LRUCacheTTL:
    def __init__(self, capacity: int):
        self.capacity = capacity
        self.cache = {}
        self.lock = threading.RLock()

        self.head = Node()
        self.tail = Node()
        self.head.next = self.tail
        self.tail.prev = self.head

    def _remove(self, node):
        node.prev.next = node.next
        node.next.prev = node.prev

    def _add_to_head(self, node):
        node.next = self.head.next
        node.prev = self.head
        self.head.next.prev = node
        self.head.next = node

    def _move_to_head(self, node):
        self._remove(node)
        self._add_to_head(node)

    def _pop_tail(self):
        node = self.tail.prev
        self._remove(node)
        return node

    def _expired(self, node):
        return node.expire_at < time.time()

    def get(self, key):
        with self.lock:
            node = self.cache.get(key)
            if not node:
                return -1
            if self._expired(node):
                self._remove(node)
                del self.cache[key]
                return -1
            self._move_to_head(node)
            return node.val

    def put(self, key, value, ttl=None):
        with self.lock:
            expire_at = float("inf") if ttl is None else time.time() + ttl

            if key in self.cache:
                node = self.cache[key]
                node.val = value
                node.expire_at = expire_at
                self._move_to_head(node)
                return

            node = Node(key, value, expire_at)
            self.cache[key] = node
            self._add_to_head(node)

            if len(self.cache) > self.capacity:
                removed = self._pop_tail()
                del self.cache[removed.key]

二叉树的中序遍历

1. 题面

94. 二叉树的中序遍历

难度：简单

给定一个二叉树的根节点 root ，返回 它的中序遍历 。

示例 1：

输入：root = [1,null,2,3]
输出：[1,3,2]

示例 2：

输入：root = []
输出：[]

示例 3：

输入：root = [1]
输出：[1]

提示：

树中节点数目在范围 [0, 100] 内
-100 <= Node.val <= 100

进阶: 递归算法很简单，你可以通过迭代算法完成吗？

# 中序遍历的递归很简单，关键是要建立树
import ast
from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root

# 打印树
def print_tree(root:TreeNode):
    # 也就是层序遍历
    ans = []
    if not root:
        print([])
        return
    q = deque([root])
    while q:
        node = q.popleft()
        ans.append(node.val)
        if node.left:
            q.append(node.left)
        if node.right:
            q.append(node.right)
    print(ans)


def solution(root:TreeNode)->list:
    ans = []
    def inorder(node):
        if not node:
            return None
        inorder(node.left)
        ans.append(node.val)
        inorder(node.right)
    inorder(root)
    return ans

if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    root = build_tree(data)
    print(solution(root))

2. 反思

中序遍历不难，主要是ACM模式读取和建树。ast读取列表，replace把null换成None。
板子的易错点：层序建树要时刻用i监督是否超过data长度，打印层序的时候别忘了先判空再入队，然后就是空树的各种边界保护。

3. 二刷

秒了。树的二刷只写核心代码，不过确实也发现自己写不好建树了。其实就是注意用i标识数组有没有走完，遇到None的时候不管（我们的数组里有None，但是不能挂）

二叉树的最大深度

1. 题面

104. 二叉树的最大深度

难度：简单

给定一个二叉树 root ，返回其最大深度。

二叉树的 最大深度 是指从根节点到最远叶子节点的最长路径上的节点数。

示例 1：

输入：root = [3,9,20,null,null,15,7]
输出：3

示例 2：

输入：root = [1,null,2]
输出：2

提示：

树中节点的数量在 [0, 10^4] 区间内。
-100 <= Node.val <= 100

2. 题解

# 两种方法，要么直接带着深度参数dfs，要么nonlocal一个depth不传参数，这样记得递归完成后回退-1
import ast
from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root


def solution(root:TreeNode)->int:
    max_depth = 0
    def dfs(node,depth):
        nonlocal max_depth
        if not node:
            return
        max_depth = max(max_depth,depth)
        dfs(node.left,depth+1)
        dfs(node.right,depth+1)
    dfs(root,1)
    return max_depth


if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    root = build_tree(data)
    print(solution(root))

3. 二刷

秒了

4. 题解2

最简单的方案其实是让dfs直接返回深度

class TreeNode:
    def __init__(self, val = 0, left = None, right = None):
        self.val = val
        self.left = left
        self.right = right

def solution(root:TreeNode):
    def dfs(node):
        if not node:
            return 0
        return 1+ max(dfs(node.left),dfs(node.right))
    return dfs(root)

翻转二叉树

1. 题面

226. 翻转二叉树

难度：简单

给你一棵二叉树的根节点 root ，翻转这棵二叉树，并返回其根节点。

示例 1：

输入：root = [4,2,7,1,3,6,9]
输出：[4,7,2,9,6,3,1]

示例 2：

输入：root = [2,1,3]
输出：[2,3,1]

示例 3：

输入：root = []
输出：[]

提示：

树中节点数目范围在 [0, 100] 内
-100 <= Node.val <= 100

2. 题解

# 其实可以建树的时候就先右后左。不过我们默认模版是不动的。于是我们可以dfs一下，然后有左右孩子的换一下
import ast
from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root

# 打印树
def print_tree(root:TreeNode):
    # 也就是层序遍历
    ans = []
    if not root:
        print([])
        return
    q = deque([root])
    while q:
        node = q.popleft()
        ans.append(node.val)
        if node.left:
            q.append(node.left)
        if node.right:
            q.append(node.right)
    print(ans)


def solution(root:TreeNode)->TreeNode:
    def dfs(node:TreeNode):
        if not node:
            return None
        node.left,node.right = node.right,node.left
        dfs(node.left)
        dfs(node.right)
    dfs(root)
    return root

if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    root = build_tree(data)
    solution(root)
    print_tree(root)

3. 反思

有时候会担心翻转之后dfs会不会乱了，或者需要调整成先right后left。其实不用，dfs只是为了遍历，即使左右换了，还是可以遍历，只不过遍历顺序变了。

4. 二刷

秒了

5. 解法2

学完了树形dp之后，这题更自然会让我想到从下往上组装，因此可以解法如下：

class TreeNode:
    def __init__(self, val = 0, left = None, right = None):
        self.val = val
        self.left = left
        self.right = right

def solution(root:TreeNode):
    def dfs(node):
        if not node:
            return
        left = dfs(node.left)
        right = dfs(node.right)
        node.left = right
        node.right = left
        return node
    return dfs(root)

对称二叉树

1. 题面

101. 对称二叉树

难度：简单

给你一个二叉树的根节点 root ，检查它是否轴对称。

示例 1：

输入：root = [1,2,2,3,4,4,3]
输出：true

示例 2：

输入：root = [1,2,2,null,3,null,3]
输出：false

提示：

树中节点数目在范围 [1, 1000] 内
-100 <= Node.val <= 100

进阶： 你可以运用递归和迭代两种方法解决这个问题吗？

2. 题解

# 因为树是递归结构，所以大多数题可以递归解。这题的解法，就是左右孩子，一个往左一个往右，一个往右一个往左，两种情况同时递归，取个and。
import ast
from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root

# 打印树
def print_tree(root:TreeNode):
    # 也就是层序遍历
    ans = []
    if not root:
        print([])
        return
    q = deque([root])
    while q:
        node = q.popleft()
        ans.append(node.val)
        if node.left:
            q.append(node.left)
        if node.right:
            q.append(node.right)
    print(ans)


def solution(root:TreeNode)->bool:
    if not root:
        return True
    # 递归用check函数，看两边
    def check(left, right):
        if not left and not right:
            return True
        if not left or not right:
            return False
        if left.val != right.val:
            return False
        return check(left.left, right.right) and check(left.right, right.left)
    return check(root.left, root.right)

   

if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    root = build_tree(data)
    print(solution(root))

3. 反思

第一次写懵逼，第二次写想看左侧左根右和右侧右根左是否一样，样例虽然能过，但是忽略了其实一个顺序是确定不了树的。

4. 二刷

被秒了。想到了是分别走，但是没想到用递归，递归的核心代码非常简洁，看清判断的条件，用and链接左左右右、左右右左即可。

二叉树的直径

1. 题面

543. 二叉树的直径

难度：简单

给你一棵二叉树的根节点，返回该树的直径。

二叉树的直径是指树中任意两个节点之间最长路径的长度。这条路径可能经过也可能不经过根节点 root 。

两节点之间路径的长度由它们之间边数表示。

示例 1：

输入：root = [1,2,3,4,5]
输出：3
解释：3 ，取路径 [4,2,1,3] 或 [5,2,1,3] 的长度。

示例 2：

输入：root = [1,2]
输出：1

提示：

树中节点数目在范围 [1, 10^4] 内
-100 <= Node.val <= 100

2. 题解

# 这一题递归对每个节点算左右字数深度，然后维持一个全局最大量和左右深度和对比。
import ast
from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root

# 打印树
def print_tree(root:TreeNode):
    # 也就是层序遍历
    ans = []
    if not root:
        print([])
        return
    q = deque([root])
    while q:
        node = q.popleft()
        ans.append(node.val)
        if node.left:
            q.append(node.left)
        if node.right:
            q.append(node.right)
    print(ans)


def solution(root: TreeNode) -> int:
    ans = 0

    def dfs(node: TreeNode) -> int:
        nonlocal ans
        if not node:
            return 0

        left_depth = dfs(node.left)
        right_depth = dfs(node.right)

        ans = max(ans, left_depth + right_depth)

        # 递归完返回的时候依次取比较深的一边+1
        return max(left_depth, right_depth) + 1

    dfs(root)
    return ans


if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    root = build_tree(data)
    print(solution(root))

3. 反思

这题有一个dfs直接计算最大深度，可以仔细看一下写法。
中间比较更新一个nonlocal量是常用的递归更新全局量。

4. 二刷

被秒了。其实就是求最大深度的代码，然后中间记录更新一下直径。

二叉树的层序遍历

1. 题面

102. 二叉树的层序遍历

难度：中等

给你二叉树的根节点 root ，返回其节点值的 层序遍历 。（即逐层地，从左到右访问所有节点）。

示例 1：

输入：root = [3,9,20,null,null,15,7]
输出：[[3],[9,20],[15,7]]

示例 2：

输入：root = [1]
输出：[[1]]

示例 3：

输入：root = []
输出：[]

提示：

树中节点数目在范围 [0, 2000] 内
-1000 <= Node.val <= 1000

2. 题解 1 · 队列法

# 层序遍历非常基础，有很多种写法，我们先实现最基础的队列法
import ast
from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root

# 打印树
def print_tree(root:TreeNode):
    # 也就是层序遍历
    ans = []
    if not root:
        print([])
        return
    q = deque([root])
    while q:
        node = q.popleft()
        ans.append(node.val)
        if node.left:
            q.append(node.left)
        if node.right:
            q.append(node.right)
    print(ans)


def solution(root: TreeNode) -> int:
    ans = []
    if not root:
        return None
    q = deque([root])
    while q:
        sz = len(q)
        level = []
        for _ in range(sz):
            curr = q.popleft()
            level.append(curr.val)
            if curr.left:
                q.append(curr.left)
            if curr.right:
                q.append(curr.right)
        # 本层遍历结束
        ans.append(level)
    return ans

if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    root = build_tree(data)
    print(solution(root))

3. 题解 2 · dfs+depth

# 层序遍历的第二种方法，记录深度的dfs
import ast
from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root

# 打印树
def print_tree(root:TreeNode):
    # 也就是层序遍历
    ans = []
    if not root:
        print([])
        return
    q = deque([root])
    while q:
        node = q.popleft()
        ans.append(node.val)
        if node.left:
            q.append(node.left)
        if node.right:
            q.append(node.right)
    print(ans)


def solution(root: TreeNode) -> list[list[int]]:
    ans = []
    def dfs(node, depth):
        if not node:
            return
        # ans记录层数，如果depth与其相等，说明为新层（depth从0）
        if depth == len(ans):
            ans.append([])
        ans[depth].append(node.val)
        dfs(node.left, depth + 1)
        dfs(node.right, depth + 1)

    dfs(root, 0)
    return ans


if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    root = build_tree(data)
    print(solution(root))

4. 题解 3 · IDDFS

# 想兼顾 DFS 省空间 和 BFS 按层扩展特性的时候，可以用IDDFS（迭代加深搜索）。思路是每次加深能搜的最深深度，然后循环DFS。
# 常用在状态搜索、博弈搜索等情况
import ast
from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root

# 打印树
def print_tree(root:TreeNode):
    # 也就是层序遍历
    ans = []
    if not root:
        print([])
        return
    q = deque([root])
    while q:
        node = q.popleft()
        ans.append(node.val)
        if node.left:
            q.append(node.left)
        if node.right:
            q.append(node.right)
    print(ans)


def solution(root: TreeNode) -> list[list[int]]:
    if not root:
        return []

    ans = []
    # 带有目标层数限制的dfs，每次取一次level
    def collect(node, depth, target, level) -> None:
        if not node:
            return
        if depth == target:
            level.append(node.val)
            return
        collect(node.left, depth + 1, target, level)
        collect(node.right, depth + 1, target, level)

    target = 0
    while True:
        level = []
        collect(root, 0, target, level)
        # 循环到没东西的时候停止
        if not level:
            break
        ans.append(level)
        target += 1

    return ans



if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    root = build_tree(data)
    print(solution(root))

5. 反思

这题我记得面试考过一次，不用队列BFS，所以就总结一下所有广搜的方法。

6. 二刷

队列法随便秒。dfs+depth的方法有点忘了，再看看。核心在于用depth == len(ans)来判断新层。

将有序数组转换为二叉搜索树

1. 题面

108. 将有序数组转换为二叉搜索树

难度：简单

给你一个整数数组 nums ，其中元素已经按升序排列，请你将其转换为一棵平衡二叉搜索树。

示例 1：

输入：nums = [-10,-3,0,5,9]
输出：[0,-3,9,-10,null,5]
解释：[0,-10,5,null,-3,null,9] 也将被视为正确答案：

示例 2：

输入：nums = [1,3]
输出：[3,1]
解释：[1,null,3] 和 [3,1] 都是高度平衡二叉搜索树。

提示：

1 <= nums.length <= 10^4
-10^4 <= nums[i] <= 10^4
nums 按 严格递增 顺序排列

2. 题解

# 这题不需要自己去构造ACL树，因为已经给了有序数组，用分治一半一半递归构造，天然就是平衡的
from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root

# 升级打印树，我们加入一个弹出None的同时也将None加入答案。然后，把尾巴多余的None弹出，得到结果。
def print_tree(root: TreeNode):
    if not root:
        print([])
        return

    ans = []
    q = deque([root])

    while q:
        node = q.popleft()
        if node is None:
            ans.append(None)
            continue
        ans.append(node.val)
        # 现在允许加入None
        q.append(node.left)
        q.append(node.right)

    while ans and ans[-1] is None:
        ans.pop()

    print(str(ans).replace("None", "null"))


# 我们给solution的定义是，返回平衡二叉树的根
def solution(nums:list)->TreeNode:
    if not nums:
        return None
    mid = len(nums)//2
    val = nums[mid]
    root = TreeNode(val)
    root.left = solution(nums[:mid])
    root.right = solution(nums[mid+1:])
    return root


if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    print_tree(solution(nums))

3. 反思

一开始以为要写ACL树，吓死我了。这一题主要注意两点，一个是两半递归的时候，切片的位置要避开root，然后mid从长度或者从长度-1开始切都是对的，正好得到的就是示例两种答案（偏左和偏右）。
另一点是这题需要打印空，升级了一下print，具体写法是不在入队前检查None，在加ans时检查None。

4. 二刷

果然一刷没亲自写出来的题印象就不深，又没写出来。思路其实很简单，就是不断拉出来重点当root就行了。

验证二叉搜索树

1. 题面

98. 验证二叉搜索树

难度：中等

给你一个二叉树的根节点 root ，判断其是否是一个有效的二叉搜索树。

有效二叉搜索树定义如下：

节点的左子树只包含 严格小于 当前节点的数。
节点的右子树只包含 严格大于 当前节点的数。
所有左子树和右子树自身必须也是二叉搜索树。

示例 1：

输入：root = [2,1,3]
输出：true

示例 2：

输入：root = [5,1,4,null,null,3,6]
输出：false
解释：根节点的值是 5 ，但是右子节点的值是 4 。

提示：

树中节点数目范围在[1, 10^4] 内
-2^31 <= Node.val <= 2^31 - 1

2. 题解

# 最标准的递归是上下界解法，因为BST要求的约束不仅在能看到的层，但看局部约束不行来递归是不行的。
import ast
from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root

# 打印树
def print_tree(root:TreeNode):
    # 也就是层序遍历
    ans = []
    if not root:
        print([])
        return
    q = deque([root])
    while q:
        node = q.popleft()
        ans.append(node.val)
        if node.left:
            q.append(node.left)
        if node.right:
            q.append(node.right)
    print(ans)


def solution(root:TreeNode)->bool:
    def dfs(node,low,high):
        if not node:
            return True
        if not (low<node.val<high):
            return False
        # 更新约束
        return dfs(node.left,low,node.val) and dfs(node.right,node.val,high)
    return dfs(root,float('-inf'),float('inf'))

if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    root = build_tree(data)
    print(solution(root))

3. 反思

这题易错点是容易只考虑当前父子直接递归，BST的约束是跨越整个树的，这样会漏掉跨层约束。
真正的做法是一直维持上下界，往左走要更新上界（因为左边都要小），往右走更新上界，遍历一遍全部判断。

4. 二刷

算是弄出来了，但是记得判空永远在最前面，因为要访问val。

二叉搜索树中第 K 小的元素

1. 题面

230. 二叉搜索树中第 K 小的元素

难度：中等

给定一个二叉搜索树的根节点 root ，和一个整数 k ，请你设计一个算法查找其中第 k 小的元素（k 从 1 开始计数）。

示例 1：

输入：root = [3,1,4,null,2], k = 1
输出：1

示例 2：

输入：root = [5,3,6,2,4,null,null,1], k = 3
输出：3

提示：

树中的节点数为 n 。
1 <= k <= n <= 10^4
0 <= Node.val <= 10^4

进阶： 如果二叉搜索树经常被修改（插入/删除操作）并且你需要频繁地查找第 k 小的值，你将如何优化算法？

2. 题解 1

# 还记得链表第k小的元素么，这里是二叉搜索树，中序就是有序排列。可以中序出数组，直接访问，这是最容易想到的。

import ast
from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root

# 打印树
def print_tree(root:TreeNode):
    # 也就是层序遍历
    ans = []
    if not root:
        print([])
        return
    q = deque([root])
    while q:
        node = q.popleft()
        ans.append(node.val)
        if node.left:
            q.append(node.left)
        if node.right:
            q.append(node.right)
    print(ans)


def solution(root:TreeNode,k:int)->int:
    ans = []
    def dfs(node):
        if not node:
            return None
        dfs(node.left)
        ans.append(node.val)
        dfs(node.right)
    dfs(root)
    return ans[k-1]

if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    k = int(input().strip())
    root = build_tree(data)
    print(solution(root,k))

3. 题解 2 · 进阶

# 进阶操作：如果二叉搜索树经常被修改（插入/删除操作）并且你需要频繁地查找第 k 小的值，你将如何优化算法？
# 这个要求我们就不能打出表了，因为二叉树时刻变动，重复打表很麻烦。
# 这题的标准做法是添加一个属性

import ast
from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root

# 打印树
def print_tree(root:TreeNode):
    # 也就是层序遍历
    ans = []
    if not root:
        print([])
        return
    q = deque([root])
    while q:
        node = q.popleft()
        ans.append(node.val)
        if node.left:
            q.append(node.left)
        if node.right:
            q.append(node.right)
    print(ans)


def solution(root: TreeNode, k: int) -> int:
    # 给节点动态加属性
    # 递归方式，给每个节点加一个维持子树大小属性
    def build_size(node: TreeNode) -> int:
        if not node:
            return 0
        left_size = build_size(node.left)
        right_size = build_size(node.right)
        node.size = left_size + right_size + 1
        return node.size

    # 有了子树大小这个属性，就可以一直看左边的size来遍历，如果左边找k-1
    # 注意切换到右边寻找的时候，要给左侧全部剪掉（因为左侧都比右侧小），去找k-left_size-1
    def kth(node: TreeNode, k: int) -> int:
        left_size = node.left.size if node.left else 0

        if k == left_size + 1:
            return node.val
        if k <= left_size:
            return kth(node.left, k)
        return kth(node.right, k - left_size - 1)

    build_size(root)
    return kth(root, k)


if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    k = int(input().strip())
    root = build_tree(data)
    print(solution(root,k))

4. 反思

进阶方法运用了python动态绑定属性的方法，很巧妙。

5. 二刷

这第二种方法也太哈人了，代码不长，但是逻辑好绕啊。我们先要走一遍，给每个节点多维持一个子树大小属性。注意，这里的size的含义，是以当前node为根的子树的size，当然要+1包含自身。然后，我们去找左边size为k-1的，如果左边不够k-1了，直接去右边找k-1-left_size，这就是核心代码。

二叉树的右视图

1. 题面

199. 二叉树的右视图

难度：中等

给定一个二叉树的 根节点 root，想象自己站在它的右侧，按照从顶部到底部的顺序，返回从右侧所能看到的节点值。

示例 1：

**输入：**root = [1,2,3,null,5,null,4]

输出： [1,3,4]

解释：

示例 2：

**输入：**root = [1,2,3,4,null,null,null,5]

输出：[1,3,4,5]

解释：

示例 3：

输入： root = [1,null,3]

输出： [1,3]

示例 4：

**输入：**root = []

输出： []

提示:

二叉树的节点个数的范围是 [0,100]
-100 <= Node.val <= 100

2. 题解

# 最容易想到的就是层序遍历，然后每次让找到当前层的最右侧
import ast
from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root

# 打印树
def print_tree(root:TreeNode):
    # 也就是层序遍历
    ans = []
    if not root:
        print([])
        return
    q = deque([root])
    while q:
        node = q.popleft()
        ans.append(node.val)
        if node.left:
            q.append(node.left)
        if node.right:
            q.append(node.right)
    print(ans)


def solution(root:TreeNode)->list:
    ans = []
    if not root:
        return []
    q = deque([root])
    while q:
        sz = len(q)
        ans.append(q[-1].val)
        for _ in range(sz):
            curr = q.popleft()
            if curr.left:
                q.append(curr.left)
            if curr.right:
                q.append(curr.right)
    return ans

if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    root = build_tree(data)
    print(solution(root))

3. 二刷

层序遍历看q[-1]即可

二叉树展开为链表

1. 题面

114. 二叉树展开为链表

难度：中等

给你二叉树的根结点 root ，请你将它展开为一个单链表：

展开后的单链表应该同样使用 TreeNode ，其中 right 子指针指向链表中下一个结点，而左子指针始终为 null 。
展开后的单链表应该与二叉树 先序遍历 顺序相同。

示例 1：

输入：root = [1,2,5,3,4,null,6]
输出：[1,null,2,null,3,null,4,null,5,null,6]

示例 2：

输入：root = []
输出：[]

示例 3：

输入：root = [0]
输出：[0]

提示：

树中结点数在范围 [0, 2000] 内
-100 <= Node.val <= 100

进阶： 你可以使用原地算法（O(1) 额外空间）展开这棵树吗？

2. 题解

# 先来一般解法，直接按结构新建链表
import ast
from collections import deque

class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root

# 打印加强
def print_tree(root:TreeNode):
    # 也就是层序遍历
    ans = []
    if not root:
        print([])
        return
    q = deque([root])
    while q:
        node = q.popleft()
        if not node:
            ans.append(None)
            continue
        ans.append(node.val)
        q.append(node.left)
        q.append(node.right)
        
    while ans and ans[-1] is None:
        ans.pop()

    print(str(ans).replace("None", "null"))


def solution(root:TreeNode)->TreeNode:
    if not root:
        return None
    dummy = TreeNode()
    dummy.right = root
    p = dummy
    def dfs(node):
        nonlocal p
        if not node:
            return None
        # 先序穿针
        p.right = TreeNode(node.val)
        p = p.right
        dfs(node.left)
        dfs(node.right)
    dfs(root)
    return dummy.right
    


if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    root = build_tree(data)
    print_tree(solution(root))

3. 题解 · 进阶

# 进阶要求是O(1)就地展开，做法就是将每个节点的左子树都接到右边。
# 具体来说，如果节点有左子树，先找左子树最右节点，然后把原右子树接到这个最右节点后面，最后左子树整体移动到右边，左边清空。可以脑内模拟一下这个过程。
import ast
from collections import deque

class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root

# 打印加强
def print_tree(root:TreeNode):
    # 也就是层序遍历
    ans = []
    if not root:
        print([])
        return
    q = deque([root])
    while q:
        node = q.popleft()
        if not node:
            ans.append(None)
            continue
        ans.append(node.val)
        q.append(node.left)
        q.append(node.right)
        
    while ans and ans[-1] is None:
        ans.pop()

    print(str(ans).replace("None", "null"))


def solution(root: TreeNode) -> TreeNode:
    p = root
    while p:
        if p.left:
            # 找到左子树最右边的节点
            pre = p.left
            while pre.right:
                pre = pre.right

            # 原来的右子树接到左子树最右节点后面
            pre.right = p.right

            # 左子树挪到右边
            p.right = p.left
            p.left = None
        # 然后一直沿着right走
        p = p.right

    return root

    


if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    root = build_tree(data)
    print_tree(solution(root))

4. 反思

第二种原地结果比较难想，多看看板子。

5. 二刷

被秒杀，重新看板子，说实话非常绕。。

6. 题解2

本题实际上还有一种非常通俗容易解决的方案，我们会发现展开后的顺序实际上就是先序遍历的顺序，那么我们可以反着来（右左根），逆着先序将每个节点接到上一个的前面，最终就可以完成。不过这种解法也是空间O(h)就是了。

def solution(root:TreeNode)->ListNode:
    prev = None
    def dfs(node):
        nonlocal prev
        if not node:
            return
        dfs(node.right)
        dfs(node.left)
        node.right = prev
        node.left = None
        prev = node
    dfs(root)
    return root

从前序与中序遍历序列构造二叉树

1. 题面

105. 从前序与中序遍历序列构造二叉树

难度：中等

给定两个整数数组 preorder 和 inorder ，其中 preorder 是二叉树的 先序遍历 ， inorder 是同一棵树的 中序遍历 ，请构造二叉树并返回其根节点。

示例 1:

输入: preorder = [3,9,20,15,7], inorder = [9,3,15,20,7]
输出: [3,9,20,null,null,15,7]

示例 2:

输入: preorder = [-1], inorder = [-1]
输出: [-1]

提示:

1 <= preorder.length <= 3000
inorder.length == preorder.length
-3000 <= preorder[i], inorder[i] <= 3000
preorder 和 inorder 均 无重复 元素
inorder 均出现在 preorder
preorder 保证为二叉树的前序遍历序列
inorder 保证为二叉树的中序遍历序列

2. 题解

# 从前序和中序构建二叉树，用手来做比较简单，写代码容易绕进去。
# 方法是将preorder作为根的列表，切分成left和right，然后递归下去，传进去新的两半数组和根。

from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root

# 打印升级
def print_tree(root:TreeNode):
    # 也就是层序遍历
    ans = []
    if not root:
        print([])
        return
    q = deque([root])
    while q:
        node = q.popleft()
        if not node:
            ans.append(None)
            continue
        ans.append(node.val)
        q.append(node.left)
        q.append(node.right)

    while ans[-1] == None:
        ans.pop()

    result = str(ans).replace("None","null")

    print(result)


def solution(preorder:list,inorder:list) -> TreeNode:
    if not preorder or not inorder:
        return None
    # 1. 定位根节点
    root_val = preorder[0]
    root = TreeNode(root_val)
    # 2. 定位分界线
    mid_idx = inorder.index(root_val)
    # 3. 切片挂子树
    # 注意计算一下左右子树的长度
    root.left = solution(
        preorder[1:1+mid_idx],
        inorder[:mid_idx]
    )
    root.right = solution(
        preorder[1+mid_idx:],
        inorder[mid_idx+1:]
    )
    return root

if __name__ == "__main__":
    preorder = list(map(int,input().strip().split(',')))
    inorder = list(map(int,input().strip().split(',')))
    print_tree(solution(preorder,inorder))

3. 反思

这题的难点在切片的位置判断，需要多练习。

4. 二刷

大体想到了解决方式，就是preorder的下标处理还是有点问题。中左右切分的时候，左的长度已经用idx给出，其实可以直接在示例数组上自己切一下看看。

路径总和 III

1. 题面

437. 路径总和 III

难度：中等

给定一个二叉树的根节点 root ，和一个整数 targetSum ，求该二叉树里节点值之和等于 targetSum 的路径的数目。

路径不需要从根节点开始，也不需要在叶子节点结束，但是路径方向必须是向下的（只能从父节点到子节点）。

示例 1：

输入：root = [10,5,-3,3,2,null,11,3,-2,null,1], targetSum = 8
输出：3
解释：和等于 8 的路径有 3 条，如图所示。

示例 2：

输入：root = [5,4,8,11,null,13,4,7,2,null,null,5,1], targetSum = 22
输出：3

提示:

二叉树的节点个数的范围是 [0,1000]
-10^9 <= Node.val <= 10^9
-1000 <= targetSum <= 1000

2. 题解

# 直接朴素递归，一句话，每个节点都试一遍
# 直接朴素递归，一句话，每个节点都试一遍

import ast

from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root


def solution(root: TreeNode, targetSum: int) -> int:
    # 统计从当前节点出发的合法路径数
    def count_from(node: TreeNode, target: int) -> int:
        if not node:
            return 0

        # 只包含节点自己
        count = 1 if node.val == target else 0
        # 当前节点 + 左边继续往下
        count += count_from(node.left, target - node.val)
        # 当前节点 + 右边继续往下
        count += count_from(node.right, target - node.val)
        return count

    if not root:
        return 0

    # solution是统计整棵树的，等于当前根出发的+左右子树的
    return (
        count_from(root, targetSum)
        + solution(root.left, targetSum)
        + solution(root.right, targetSum)
    )



if __name__ == "__main__":
    data = input().strip().replace("null","None")
    targetSum = int(input().strip())
    nums = ast.literal_eval(data)
    root = build_tree(nums)
    print(solution(root,targetSum))

3. 反思

这题好难，得用两个递归。首先是找从这个节点开始，递归找有没有路径。然后递归每个节点加上当前和左右的路径和。能自己写出这题的递归已经对树的递归非常熟练了。

4. 反思

被秒了，对于这种，起点可以是根也可以不是的，大部分需要用到递归式子运算。比如这题的返回count_from(root, targetSum)+ solution(root.left, targetSum)+ solution(root.right, targetSum)，这里count_from仅表示以xx为起点的有多少路径符合条件，而solution本身是整个树有多少符合的（即count_all），所以这是两层递归在一起。

二叉树的最近公共祖先

1. 题面

236. 二叉树的最近公共祖先

难度：中等

给定一个二叉树, 找到该树中两个指定节点的最近公共祖先。

百度百科中最近公共祖先的定义为：“对于有根树 T 的两个节点 p、q，最近公共祖先表示为一个节点 x，满足 x 是 p、q 的祖先且 x 的深度尽可能大（ 一个节点也可以是它自己的祖先 ）。”

示例 1：

输入：root = [3,5,1,6,2,0,8,null,null,7,4], p = 5, q = 1
输出：3
解释：节点 5 和节点 1 的最近公共祖先是节点 3 。

示例 2：

输入：root = [3,5,1,6,2,0,8,null,null,7,4], p = 5, q = 4
输出：5
解释：节点 5 和节点 4 的最近公共祖先是节点 5 。因为根据定义最近公共祖先节点可以为节点本身。

示例 3：

输入：root = [1,2], p = 1, q = 2
输出：1

提示：

树中节点数目在范围 [2, 10^5] 内。
-10^9 <= Node.val <= 10^9
所有 Node.val 互不相同 。
p != q
p 和 q 均存在于给定的二叉树中。

2. 题解 · parent属性

# 我们给节点添加parent属性，然后让标记的p、q同时往上，找到空之后再从头开始。按照相交链表的结论，最后一定会在交点（共同祖先）相遇，如果没有共同祖先，也会在None相遇。
import ast

from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root


def solution(root: TreeNode, p: int, q: int) -> TreeNode:
    # 指针思维
    node_p = None
    node_q = None
    def build_parent(node: TreeNode, parent: TreeNode):
        nonlocal node_p, node_q
        if not node:
            return
        node.parent = parent
        # 顺便找到p、q
        if node.val == p:
            node_p = node
        if node.val == q:
            node_q = node
        build_parent(node.left, node)
        build_parent(node.right, node)
    build_parent(root, None)
    a, b = node_p, node_q
    while a != b:
        a = a.parent if a else node_q
        b = b.parent if b else node_p
    return a

    
if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    p = int(input().strip())
    q = int(input().strip())
    root = build_tree(data)
    ans = solution(root, p, q)
    print(ans.val)

3. 题解 2 · 递归

# 如果用树的思维来做，就要先想到从递归写。这题的做法是经典的LCA算法，请熟练掌握这个。
import ast

from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root

# 我们用solution(root,p,q)表示以root为根的这颗子树中，p、q的最近公共祖先
def solution(root: TreeNode, p: TreeNode, q: TreeNode) -> TreeNode:
    # 找到目标节点或者找到空了先往上交
    if not root or root == p or root == q:
        return root
    # 递归左右子树
    left = solution(root.left, p, q)
    right = solution(root.right, p, q)
    # 如果左右都返回了非空值，也就是都找到了，那root就是第一次汇合的地方
    if left and right:
        return root
    # 如果只有一边非空，则将自己上交，继续往上找祖先
    return left if left else right


    
if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    p = int(input().strip())
    q = int(input().strip())
    root = build_tree(data)
    ans = solution(root, p, q)
    print(ans.val)

4. 反思

这题第二种LCA算法是最优雅的解法，请记住板子。

5. 二刷

还是没想到递归方法，但是LCA算法的确看起来优雅。几个要点，solution表示子树中p、q的最近公共祖先，而出口是找到p、q或者为空，上交left和right两个信息，只有left和right都非空（也就是左右两边找到了），由于是从底向上的，所以就是第一个汇合的地方。如果只有一遍是空的，那应该将非空返回上去继续找。（由于还要满足祖先深度尽可能大，所以找到root继续上交）

二叉树中的最大路径和

1. 题面

124. 二叉树中的最大路径和

难度：困难

二叉树中的路径被定义为一条节点序列，序列中每对相邻节点之间都存在一条边。同一个节点在一条路径序列中 至多出现一次 。该路径 至少包含一个 节点，且不一定经过根节点。

路径和 是路径中各节点值的总和。

给你一个二叉树的根节点 root ，返回其 最大路径和 。

示例 1：

输入：root = [1,2,3]
输出：6
解释：最优路径是 2 -> 1 -> 3 ，路径和为 2 + 1 + 3 = 6

示例 2：

输入：root = [-10,9,20,null,null,15,7]
输出：42
解释：最优路径是 15 -> 20 -> 7 ，路径和为 15 + 20 + 7 = 42

提示：

树中节点数目范围是 [1, 3 * 10^4]
-1000 <= Node.val <= 1000

2. 题解

# 这题根二叉树直径的题有点像，不确定起点，不确定是否经过根。
import ast

from collections import deque
class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.val = val
        self.left = left
        self.right = right

# 从列表创建树
def build_tree(data:list):
    # 空返回
    if not data or data[0] is None:
        return None
    
    root = TreeNode(data[0])
    q = deque([root])
    # 除去根，从1开始
    i = 1

    # 正常的列表其实是层序遍历顺序给出，所有用层序来建树即可，维持一个i随时监控有没有超过长度。
    while q and i<len(data):
        node = q.popleft()

        if i <len(data) and data[i] is not None:
            node.left = TreeNode(data[i])
            q.append(node.left)
        i += 1

        if i<len(data) and data[i] is not None:
            node.right = TreeNode(data[i])
            q.append(node.right)
        i += 1
    return root


def solution(root: TreeNode) -> int:
    ans = float("-inf")
    # dfs记录当前节点往下走的一条最大贡献路径
    # ans记录当前节点作为拐点时的最大路径和
    def dfs(node: TreeNode) -> int:
        nonlocal ans
        if not node:
            return 0

        # 依旧变形递归，值可能有负数，跟0做一下max
        left_gain = max(dfs(node.left), 0)
        right_gain = max(dfs(node.right), 0)

        # 最大路径和可能正好在当前节点这里左右连起来
        ans = max(ans, node.val + left_gain + right_gain)
        return node.val + max(left_gain, right_gain)

    dfs(root)
    return ans

  
if __name__ == "__main__":
    data = ast.literal_eval(input().strip().replace("null", "None"))
    root = build_tree(data)
    print(solution(root))

3. 反思

我草，好难，暂时不看，回头理解背板

4. 二刷

本题结合二叉树直径一起看！

5. 拓展

本题和二叉树直径题，都是“答案都可能在某个节点这里，把左边一条链 + 当前节点 + 右边一条链拼起来”的题目，每个节点都尝试作为“拐点”结算一次答案。

left = dfs(node.left)
right = dfs(node.right)

ans = max(ans, 某种 left + right 的组合)
return 某种只能选一边的值

return必须写成单链状态来返回父节点，因为父节点只能接左边或右边的一条。而更新答案的时候，两边都加。并排记忆如下：

二叉树直径

def dfs(node):
    if not node:
        return 0
    left = dfs(node.left)
    right = dfs(node.right)
    ans = max(ans, left + right)
    return max(left, right) + 1

二叉树最大路径和

def dfs(node):
    if not node:
        return 0
    left = max(dfs(node.left), 0)
    right = max(dfs(node.right), 0)
    ans = max(ans, node.val + left + right)
    return node.val + max(left, right)

岛屿数量

1. 题面

200. 岛屿数量

难度：中等

给你一个由 '1'（陆地）和 '0'（水）组成的的二维网格，请你计算网格中岛屿的数量。

岛屿总是被水包围，并且每座岛屿只能由水平方向和/或竖直方向上相邻的陆地连接形成。

此外，你可以假设该网格的四条边均被水包围。

示例 1：

输入：grid = [
  ['1','1','1','1','0'],
  ['1','1','0','1','0'],
  ['1','1','0','0','0'],
  ['0','0','0','0','0']
]
输出：1

示例 2：

输入：grid = [
  ['1','1','0','0','0'],
  ['1','1','0','0','0'],
  ['0','0','1','0','0'],
  ['0','0','0','1','1']
]
输出：3

提示：

m == grid.length
n == grid[i].length
1 <= m, n <= 300
grid[i][j] 的值为 '0' 或 '1'

2. 题解

# 虽然是图论的第一题，但是和建图没关系，可以直接用输入的矩阵当图本身。
# dfs本身可以用来找连通图的个数，只要用外面循环调用dfs就行。这题思路很简单。
import ast


def solution(grid: list[list[str]]) -> int:
    if not grid:
        return 0

    m, n = len(grid), len(grid[0])
    ans = 0

    def dfs(i: int, j: int) -> None:
        # 走到水里或越界
        if i < 0 or i >= m or j < 0 or j >= n or grid[i][j] != "1":
            return

        # dfs各种走四个方向
        grid[i][j] = "0"
        dfs(i - 1, j)
        dfs(i + 1, j)
        dfs(i, j - 1)
        dfs(i, j + 1)

    # 找到一块陆地，就dfs把附近的路都水淹掉（标记为0）
    for i in range(m):
        for j in range(n):
            if grid[i][j] == "1":
                ans += 1
                dfs(i, j)

    return ans


if __name__ == "__main__":
    grid = ast.literal_eval(input().strip())
    print(solution(grid))

3. 反思

dfs在图里的经典用法

4. 二刷

二刷中，我把dfs写成了这样：

def dfs(grid,i,j):
    if grid[i][j] == '1':
        grid[i][j] = '0'
    elif grid[i][j] == '0':
        return
    if i-1>=0:
        dfs(grid,i-1,j)
    if i+1<len(grid):
        dfs(grid,i+1,j)
    if j+1<len(grid[0]):
        dfs(grid,i,j+1)
    if j-1>=0:
        dfs(grid,i,j-1)

AI说，这不是稳妥的写法，大多数人写dfs的时候，会首先判断是否合法，然后再走四个方向，就是按照第一次的题解一样，在入口判断是否有越界或者等于'1'。

腐烂的橘子

1. 题面

994. 腐烂的橘子

难度：1433

在给定的 m x n 网格 grid 中，每个单元格可以有以下三个值之一：

值 0 代表空单元格；
值 1 代表新鲜橘子；
值 2 代表腐烂的橘子。

每分钟，腐烂的橘子 周围 4 个方向上相邻 的新鲜橘子都会腐烂。

返回 直到单元格中没有新鲜橘子为止所必须经过的最小分钟数。如果不可能，返回 -1 。

示例 1：

输入：grid = [[2,1,1],[1,1,0],[0,1,1]]
输出：4

示例 2：

输入：grid = [[2,1,1],[0,1,1],[1,0,1]]
输出：-1
解释：左下角的橘子（第 2 行， 第 0 列）永远不会腐烂，因为腐烂只会发生在 4 个方向上。

示例 3：

输入：grid = [[0,2]]
输出：0
解释：因为 0 分钟时已经没有新鲜橘子了，所以答案就是 0 。

提示：

m == grid.length
n == grid[i].length
1 <= m, n <= 10
grid[i][j] 仅为 0、1 或 2

2. 题解

# 用手画出来这个过程倒是很简单，二重遍历+更新time编，就是有点担心会不会太慢了
import ast
from collections import deque

def solution(grid: list[list[int]]) -> int:
    m, n = len(grid), len(grid[0])
    q = deque()
    fresh = 0

    # 先把所有腐烂橘子入队，同时统计新鲜橘子数量
    for i in range(m):
        for j in range(n):
            if grid[i][j] == 2:
                q.append((i, j))
            elif grid[i][j] == 1:
                fresh += 1

    minutes = 0
    # 预定义四个方向
    directions = [(-1, 0), (1, 0), (0, -1), (0, 1)]

    while q and fresh > 0:
        for _ in range(len(q)):
            x, y = q.popleft()
            for dx, dy in directions:
                nx, ny = x + dx, y + dy
                # python判断坐标合法的方法
                if 0 <= nx < m and 0 <= ny < n and grid[nx][ny] == 1:
                    grid[nx][ny] = 2
                    fresh -= 1
                    q.append((nx, ny))
        minutes += 1

    return minutes if fresh == 0 else -1


    
if __name__ == "__main__":
    grid = ast.literal_eval(input().strip())
    print(solution(grid))

3. 反思

这种题看起来思路简单，但是比较考验你的写法和边界条件，建议平时多敲练习。

4. 二刷

想到的方法solution解决每轮感染，返回是否有修改的flag。如果没修改且不存在新鲜橘子就结束了，这种方式修改需要先遍历单独标记，然后再统一腐烂。

其实题解的方法还是比较好的，这是一种多源头bfs的解法，很直观且容易理解（因为橘子每次最多感染一层），对比之前的岛屿问题，则是多源dfs。

课程表

1. 题面

207. 课程表

难度：中等

你这个学期必须选修 numCourses 门课程，记为 0 到 numCourses - 1 。

在选修某些课程之前需要一些先修课程。先修课程按数组 prerequisites 给出，其中 prerequisites[i] = [ai, bi] ，表示如果要学习课程 ai 则必须先学习课程 bi 。

例如，先修课程对 [0, 1] 表示：想要学习课程 0 ，你需要先完成课程 1 。

请你判断是否可能完成所有课程的学习？如果可以，返回 true ；否则，返回 false 。

示例 1：

输入：numCourses = 2, prerequisites = [[1,0]]
输出：true
解释：总共有 2 门课程。学习课程 1 之前，你需要完成课程 0 。这是可能的。

示例 2：

输入：numCourses = 2, prerequisites = [[1,0],[0,1]]
输出：false
解释：总共有 2 门课程。学习课程 1 之前，你需要先完成课程 0 ；并且学习课程 0 之前，你还应先完成课程 1 。这是不可能的。

提示：

1 <= numCourses <= 2000
0 <= prerequisites.length <= 5000
prerequisites[i].length == 2
0 <= ai, bi < numCourses
prerequisites[i] 中的所有课程对 互不相同

2. 题解

# 这一题是经典的有向图判环，我们用队列实现拓扑排序
import ast
from collections import deque

def solution(numCourses: int, prerequisites: list[list[int]]) -> bool:
    # 简历邻接表
    graph = [[] for _ in range(numCourses)]
    indegree = [0] * numCourses

    # 建图：b -> a，表示学a之前要先学b
    for a, b in prerequisites:
        graph[b].append(a)
        # 维持一个入度，给后面拓扑排序用
        indegree[a] += 1

    # 开始拓扑排序，先将入度为0加入，然后一层一层剥
    q = deque()
    for i in range(numCourses):
        if indegree[i] == 0:
            q.append(i)

    count = 0
    while q:
        course = q.popleft()
        count += 1

        # 如果去掉孩子的入度全减1，如果变成入度0就入队
        for nxt in graph[course]:
            indegree[nxt] -= 1
            if indegree[nxt] == 0:
                q.append(nxt)
    # 如果所有数都出去了，说明无环
    return count == numCourses

if __name__ == "__main__":
    numCourses = int(input().strip())
    prerequisites = ast.literal_eval(input().strip())
    print(solution(numCourses,prerequisites))

3. 反思

拓扑排序给有向图判环是经典算法。

4. 二刷

有点忘了建图的语句了，邻接表建图法可以多复习一下。

实现 Trie (前缀树)

1. 题面

208. 实现 Trie (前缀树)

难度：中等

Trie （发音类似 "try"）或者说 前缀树 是一种树形数据结构，用于高效地存储和检索字符串数据集中的键。这一数据结构有相当多的应用情景，例如自动补全和拼写检查。

请你实现 Trie 类：

Trie() 初始化前缀树对象。
void insert(String word) 向前缀树中插入字符串 word 。
boolean search(String word) 如果字符串 word 在前缀树中，返回 true（即，在检索之前已经插入）；否则，返回 false 。
boolean startsWith(String prefix) 如果之前已经插入的字符串 word 的前缀之一为 prefix ，返回 true ；否则，返回 false 。

示例：

输入
["Trie", "insert", "search", "search", "startsWith", "insert", "search"]
[[], ["apple"], ["apple"], ["app"], ["app"], ["app"], ["app"]]
输出
[null, null, true, false, true, null, true]

解释
Trie trie = new Trie();
trie.insert("apple");
trie.search("apple");   // 返回 True
trie.search("app");     // 返回 False
trie.startsWith("app"); // 返回 True
trie.insert("app");
trie.search("app");     // 返回 True

提示：

1 <= word.length, prefix.length <= 2000
word 和 prefix 仅由小写英文字母组成
insert、search 和 startsWith 调用次数总计不超过 3 * 10^4 次

2. 题解

# Trie树是一种空间换时间极致的结构
import ast


class Trie:
    # 内部类：定义 Trie 树的每一个最小单元（节点）
    class TrieNode:
        def __init__(self):
            # 因为题目说只有小写英文字母，所以固定开 26 个分叉的数组即可。
            # 下标 0 代表 'a'，下标 25 代表 'z'
            self.children = [None] * 26
            # 核心灵魂：标记从根节点一路顺着树枝走到这里，是不是构成了一个完整的单词
            self.is_end = False

    def __init__(self):
        self.root = self.TrieNode()

    def insert(self, word: str) -> None:
        # 指针 p 从树根出发，准备顺着树干往下爬
        p = self.root
        for char in word:
            # 计算当前字母应该进 26 个分叉里的哪一个通道
            idx = ord(char) - ord('a')
            # 如果通往这个字母的“通道（树枝）”还不存在，就现搭一根树枝（新建节点）
            if not p.children[idx]:
                p.children[idx] = self.TrieNode()
            # 顺着这条刚搭好、或者早就有的树枝，大步往下走一层！
            p = p.children[idx]
        
        # 单词全部走完了（此时 p 停在这个单词的最后一个字母上）
        # 插上一面旗子：宣告这里是一个合法单词的终点！
        p.is_end = True

    def search(self, word: str) -> bool:
        p = self.root
        for char in word:
            idx = ord(char) - ord('a')
            # 如果走着走着发现没路了（通道是 None），说明字典里压根没存过这串字母，果断返回 False
            if not p.children[idx]:
                return False
            p = p.children[idx]
            
        # 走到底了，路是通的。但它到底是用我的这串字母结尾的单词，还是只是一部分前缀？
        # 全靠我们当时插下的那面旗帜 `is_end` 说了算！
        return p.is_end

    def startsWith(self, prefix: str) -> bool:
        p = self.root
        for char in prefix:
            idx = ord(char) - ord('a')
            # 同样，走不通说明连前缀都没有
            if not p.children[idx]:
                return False
            p = p.children[idx]
            
        # 前缀和 search 唯一的区别：只要路能通，不管走到最后有没有插红旗，前缀都是存在的！
        return True


if __name__ == "__main__":
    ops = ast.literal_eval(input().strip().replace("null", "None"))
    args = ast.literal_eval(input().strip().replace("null", "None"))

    ans = []
    trie = None

    for op, arg in zip(ops, args):
        if op == "Trie":
            trie = Trie()
            ans.append(None)
        elif op == "insert":
            trie.insert(arg[0])
            ans.append(None)
        elif op == "search":
            ans.append(trie.search(arg[0]))
        elif op == "startsWith":
            ans.append(trie.startsWith(arg[0]))

    print(str(ans).replace("None", "null").replace("True", "true").replace("False", "false"))

3. 反思

记住思路了背板很简单

4. 二刷

差不多能秒，还是多看板子，写的很优雅。

全排列

1. 题面

46. 全排列

难度：中等

给定一个不含重复数字的数组 nums ，返回其 所有可能的全排列 。你可以 按任意顺序 返回答案。

示例 1：

输入：nums = [1,2,3]
输出：[[1,2,3],[1,3,2],[2,1,3],[2,3,1],[3,1,2],[3,2,1]]

示例 2：

输入：nums = [0,1]
输出：[[0,1],[1,0]]

示例 3：

输入：nums = [1]
输出：[[1]]

提示：

1 <= nums.length <= 6
-10 <= nums[i] <= 10
nums 中的所有整数 互不相同

2. 题解

# 最朴素的想法就是建立一个寻找第j位置的函数，然后一个同样大小的seen数组维持是否被用过，每次遍历找一个，直到长度达到要求结束。
import ast

def solution(nums: list) -> list[list[int]]:
    ans = []
    path = []
    seen = [False] * len(nums)

    def dfs():
        if len(path) == len(nums):
            ans.append(path[:])
            return

        for i in range(len(nums)):
            if seen[i]:
                continue
            # 递归开始的时候，标记seen，加入path
            seen[i] = True
            path.append(nums[i])
            # 递归
            dfs()
            # 递归结束的时候，弹出path，更新seen
            path.pop()
            seen[i] = False

    dfs()
    return ans


if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    print(solution(nums))

3. 反思

用python写的话，一般都是把递归写成函数中的函数，而不是用全局量。这一题的思路不难，主要是递归设计容易弄错。

4. 二刷

首先是dfs的选择，适用于选择一条答案走到底再回头。另外，二刷选择了set，当然这一题数值不重复是没问题的，但是最好记录“下标是否使用过”，这样有重复元素也没关系。也就是说，我们用seen = [False] * n

子集

1. 题面

78. 子集

难度：中等

给你一个整数数组 nums ，数组中的元素 互不相同 。返回该数组所有可能的子集（幂集）。

解集不能包含重复的子集。你可以按 任意顺序 返回解集。

示例 1：

输入：nums = [1,2,3]
输出：[[],[1],[2],[1,2],[3],[1,3],[2,3],[1,2,3]]

示例 2：

输入：nums = [0]
输出：[[],[0]]

提示：

1 <= nums.length <= 10
-10 <= nums[i] <= 10
nums 中的所有元素 互不相同

2. 题解

# 元素不能重复天然想到set，依旧递归，每个元素都可以选择在或不在子集，因此遍历一遍判断每个元素就可以构成解集
import ast

def solution(nums: list) -> list[list[int]]:
    ans = []
    path = []

    def dfs(i: int):
        if i == len(nums):
            ans.append(path[:])
            return

        # 不选 nums[i]
        dfs(i + 1)

        # 选 nums[i]
        path.append(nums[i])
        dfs(i + 1)
        path.pop()

    dfs(0)
    return ans

        
if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    print(solution(nums))

3. 反思

同样是比较标准的递归，属于是不能回头查的递归，所以维持一个深度i（这里就是num的长度），递归过程中达到深度存下所有叶子答案

4. 二刷

这一题也可以像上一题一样遍历添加，然后回溯，只要给dfs维持一个start就可以保证不重复添加。这种方法可以保证顺序比较符合人类直觉：

import ast
def solution(nums):
    ans = []
    path = []

    def dfs(start):
        # 先收集当前子集
        ans.append(path[:])   
        for i in range(start, len(nums)):
            path.append(nums[i])
            dfs(i + 1)
            path.pop()

    dfs(0)
    return ans


if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    print(solution(nums))

电话号码的字母组合

1. 题面

17. 电话号码的字母组合

难度：中等

给定一个仅包含数字 2-9 的字符串，返回所有它能表示的字母组合。答案可以按 任意顺序 返回。

给出数字到字母的映射如下（与电话按键相同）。注意 1 不对应任何字母。

示例 1：

输入：digits = "23"
输出：["ad","ae","af","bd","be","bf","cd","ce","cf"]

示例 2：

输入：digits = "2"
输出：["a","b","c"]

提示：

1 <= digits.length <= 4
digits[i] 是范围 ['2', '9'] 的一个数字。

2. 题解

# 用哈希表存储每个数字字符对应的字符串，当我们输入连续数字的时候，实际上在求它们对应字符串组成列表的笛卡尔积。

def solution(digits: str) -> list[str]:
    if not digits:
        return []

    mp = {
        "2": "abc", "3": "def", "4": "ghi", "5": "jkl",
        "6": "mno", "7": "pqrs", "8": "tuv", "9": "wxyz"
    }

    ans = []
    path = []

    def dfs(i: int):
        if i == len(digits):
            ans.append("".join(path))
            return

        for ch in mp[digits[i]]:
            path.append(ch)
            dfs(i + 1)
            path.pop()

    dfs(0)
    return ans

if __name__ == "__main__":
    digits = input().strip()
    print(solution(digits))

3. 反思

又是一个很好的递归，这题的情形是求笛卡尔积，跟上一题一样，是固定位数的递归，不过上一题是选或不选，这一题是选什么，所以多了一个循环来看选什么，递归写在循环里。

4. 二刷

写错了一个关键的点，就是这题同样属于逐位判断，dfs维持一个位置（换句话说不能回头选）。

组合总和

1. 题面

39. 组合总和

难度：中等

给你一个 无重复元素 的整数数组 candidates 和一个目标整数 target ，找出 candidates 中可以使数字和为目标数 target 的所有 不同组合 ，并以列表形式返回。你可以按 任意顺序 返回这些组合。

candidates 中的 同一个 数字可以 无限制重复被选取 。如果至少一个数字的被选数量不同，则两种组合是不同的。

对于给定的输入，保证和为 target 的不同组合数少于 150 个。

示例 1：

输入：candidates = [2,3,6,7], target = 7
输出：[[2,2,3],[7]]
解释：
2 和 3 可以形成一组候选，2 + 2 + 3 = 7 。注意 2 可以使用多次。
7 也是一个候选， 7 = 7 。
仅有这两种组合。

示例 2：

输入: candidates = [2,3,5], target = 8
输出: [[2,2,2,2],[2,3,3],[3,5]]

示例 3：

输入: candidates = [2], target = 1
输出: []

提示：

1 <= candidates.length <= 30
2 <= candidates[i] <= 40
candidates 的所有元素 互不相同
1 <= target <= 40

2. 题解

# 其实所有组合也就是每一位选或者不选，但是这题是允许重复选，然后就是可以根据target稍微剪枝一下，如果和已经大于target了，那这条路肯定就不通了

import ast

def solution(candidates: list, target: int) -> list[list[int]]:
    ans = []
    path = []

    def dfs(i: int, target: int):
        if target == 0:
            ans.append(path[:])
            return
        if i == len(candidates) or target < 0:
            return

        # 不选当前数
        dfs(i + 1, target)

        # 选当前数，还可以继续选它
        path.append(candidates[i])
        dfs(i, target - candidates[i])
        path.pop()

    dfs(0, target)
    return ans


if __name__ == "__main__":
    candidates = ast.literal_eval(input().strip())
    target = int(input().strip())
    print(solution(candidates,target))

3. 反思

本题是可以重复选的，其实也是只要分为选和不选，但是选的时候不用移动i就行了。然后同时用i和target监视。

4. 二刷

第一遍错误按照所有组合算总和，223、232、322都算进去了。但是，实际上可以维持一个循环开始搜索的位置start就可以保证不回头选，这也说明了维持位置i和维持start开始遍历是某些情况等效的：

i 版本：显式地写“选 / 不选当前下标”
start 版本：用 for 一次性枚举“从当前下标开始能选谁”

其实后一种情况可以适配的情况还更多，包括组合、子集、组合总和I/II、固定长度组合都可以用。

import ast
def solution(condidates:list,target:int)->list[list[int]]:
    ans = []
    path = []
    def dfs(start,total):
        if total > target:
            return 
        if target == total:
           ans.append(path[:])
           return 
        for i in range(start,len(condidates)):
            path.append(condidates[i])
            # 可重复选，所以递归进去还是i
            dfs(i,total+condidates[i]) 
            path.pop()
    dfs(0, 0)
    return ans

if __name__ == "__main__":
    condidates = ast.literal_eval(input().strip())
    target = int(input().strip())
    print(solution(condidates,target))

括号生成

1. 题面

22. 括号生成

难度：中等

数字 n 代表生成括号的对数，请你设计一个函数，用于能够生成所有可能的并且 有效的 括号组合。

示例 1：

输入：n = 3
输出：["((()))","(()())","(())()","()(())","()()()"]

示例 2：

输入：n = 1
输出：["()"]

提示：

1 <= n <= 8

2. 题解

# 标准回溯思路其实很简单：
# 如果左括号还没用满，就可以放 '('
# 如果右括号数量小于左括号数量，就可以放 ')'


def solution(n: int):
    ans = []
    path = []

    # dfs直接维持left和right
    def dfs(left: int, right: int):
        # 递归出口
        if left == n and right == n:
            ans.append("".join(path))
            return
        # 左括号没满
        if left < n:
            path.append("(")
            dfs(left + 1, right)
            path.pop()
        # 左括号比较多的时候可以放右括号
        if right < left:
            path.append(")")
            dfs(left, right + 1)
            path.pop()

    dfs(0, 0)
    return ans


if __name__ == "__main__":
    n = int(input().strip())
    print(solution(n))

3. 反思

难点在dfs的边界条件，还有这里传入的量也不一样，每一题dfs可以灵活传入不同的量，也可以直接按每题都dfs空，把需要维护的量写外面nonlocal。

4. 二刷

SKIP了，括号好烦好烦，等会做专题一并解决。

单词搜索

1. 题面

79. 单词搜索

难度：中等

给定一个 m x n 二维字符网格 board 和一个字符串单词 word 。如果 word 存在于网格中，返回 true ；否则，返回 false 。

单词必须按照字母顺序，通过相邻的单元格内的字母构成，其中“相邻”单元格是那些水平相邻或垂直相邻的单元格。同一个单元格内的字母不允许被重复使用。

示例 1：

输入：board = [['A','B','C','E'],['S','F','C','S'],['A','D','E','E']], word = "ABCCED"
输出：true

示例 2：

输入：board = [['A','B','C','E'],['S','F','C','S'],['A','D','E','E']], word = "SEE"
输出：true

示例 3：

输入：board = [['A','B','C','E'],['S','F','C','S'],['A','D','E','E']], word = "ABCB"
输出：false

提示：

m == board.length
n = board[i].length
1 <= m, n <= 6
1 <= word.length <= 15
board 和 word 仅由大小写英文字母组成

进阶： 你可以使用搜索剪枝的技术来优化解决方案，使其在 board 更大的情况下可以更快解决问题？

2. 题解

# 一眼二维网络多起点深搜，思路不难难的是边界，来试试看。

import ast

def solution(board: list[list[str]], word: str) -> bool:
    m, n = len(board), len(board[0])
    # dfs(i,j,k)表示当前在ij，要匹配word[k]开始的后缀
    def dfs(i: int, j: int, k: int) -> bool:
        # 特别注意dfs的返回
        # 越界返回
        if i < 0 or i >= m or j < 0 or j >= n:
            return False
        # 非需要字母返回
        if board[i][j] != word[k]:
            return False
        # 长度达标返回True
        if k == len(word) - 1:
            return True

        # 标记，防止重复使用
        ch = board[i][j]
        board[i][j] = "#"

        found = (
            dfs(i - 1, j, k + 1)
            or dfs(i + 1, j, k + 1)
            or dfs(i, j - 1, k + 1)
            or dfs(i, j + 1, k + 1)
        )

        board[i][j] = ch
        return found

    # 多起点dfs
    # 本题不需要path，匹配完成就是满足的
    for i in range(m):
        for j in range(n):
            if dfs(i, j, 0):
                return True

    return False


if __name__ == "__main__":
    board = ast.literal_eval(input().strip())
    word = input().strip()

3. 反思

多源dfs，注意图dfs的时候要标记自身（或者用visted的），递归完再恢复。有越界和非字母两种返回情形。

分割回文串

1. 题面

131. 分割回文串

难度：中等

给你一个字符串 s，请你将 s 分割成一些子串，使每个子串都是 回文串 。返回 s 所有可能的分割方案。

示例 1：

输入：s = "aab"
输出：[["a","a","b"],["aa","b"]]

示例 2：

输入：s = "a"
输出：[["a"]]

提示：

1 <= s.length <= 16
s 仅由小写英文字母组成

2. 题解

# 分割回文串的个数不定，回文串判断是反转和原本一样。
# 这题关键的视角是站在某个起点start，决定下一刀要切在哪

def solution(s: str) -> list[list[str]]:
    ans = []
    path = []

    # 辅助函数，判断是不是回文串
    def is_palindrome(sub: str) -> bool:
        return sub == sub[::-1]

    def dfs(start: int):
        if start == len(s):
            # 切到了终点
            ans.append(path[:])
            return

        for end in range(start, len(s)):
            # 一个一个往后切，加入路径
            sub = s[start:end + 1]
            if not is_palindrome(sub):
                continue

            path.append(sub)
            dfs(end + 1)
            path.pop()

    dfs(0)
    return ans

if __name__ == "__main__":
    s = input().strip()
    print(solution(s))

N皇后

1. 题面

51. N 皇后

难度：困难

按照国际象棋的规则，皇后可以攻击与之处在同一行或同一列或同一斜线上的棋子。

n 皇后问题 研究的是如何将 n 个皇后放置在 n×n 的棋盘上，并且使皇后彼此之间不能相互攻击。

给你一个整数 n ，返回所有不同的 n 皇后问题 的解决方案。

每一种解法包含一个不同的 n 皇后问题 的棋子放置方案，该方案中 'Q' 和 '.' 分别代表了皇后和空位。

示例 1：

输入：n = 4
输出：[[".Q..","...Q","Q...","..Q."],["..Q.","Q...","...Q",".Q.."]]
解释：如上图所示，4 皇后问题存在两个不同的解法。

示例 2：

输入：n = 1
输出：[["Q"]]

提示：

1 <= n <= 9

2. 题解

# 久闻大名
# 直接背板子）
def solution(n: int) -> list[list[str]]:
    ans = []
    board = [["."] * n for _ in range(n)]

    col = [False] * n
    diag1 = [False] * (2 * n)   # 主对角线：row - col + n
    diag2 = [False] * (2 * n)   # 副对角线：row + col

    def dfs(row: int):
        if row == n:
            ans.append(["".join(r) for r in board])
            return

        for c in range(n):
            d1 = row - c + n
            d2 = row + c

            if col[c] or diag1[d1] or diag2[d2]:
                continue

            board[row][c] = "Q"
            col[c] = True
            diag1[d1] = True
            diag2[d2] = True

            dfs(row + 1)

            board[row][c] = "."
            col[c] = False
            diag1[d1] = False
            diag2[d2] = False

    dfs(0)
    return ans

if __name__ == "__main__":
    n = int(input().strip())
    print(solution(n))

搜索插入位置

1. 题面

35. 搜索插入位置

难度：简单

给定一个排序数组和一个目标值，在数组中找到目标值，并返回其索引。如果目标值不存在于数组中，返回它将会被按顺序插入的位置。

请必须使用时间复杂度为 O(log n) 的算法。

示例 1:

输入: nums = [1,3,5,6], target = 5
输出: 2

示例 2:

输入: nums = [1,3,5,6], target = 2
输出: 1

示例 3:

输入: nums = [1,3,5,6], target = 7
输出: 4

提示:

1 <= nums.length <= 10^4
-10^4 <= nums[i] <= 10^4
nums 为 无重复元素 的升序排列数组
-10^4 <= target <= 10^4

2. 题解 · 左闭右闭

# 经典二分查找，搜索目标是第一个小于目标值的值，小于Target为条件，TTTFFF，第一个F就是要插入的位置
import ast

def search(nums:list[int],target:int)->int:
    left = 0
    right = len(nums) - 1
    while left<right:
        mid = (left + right) // 2
        if nums[mid]<target:
            left = mid + 1
        else:
            right = mid
    if nums[-1]<target:
        return len(nums)
    return left

if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    target = int(input().strip())
    print(search(nums,target))

3. 题解 · 左闭右开

# 左闭右开版
import ast

def search(nums:list[int],target:int)->int:
    left = 0
    right = len(nums)
    while left < right:
        mid = (left + right) // 2
        if nums[mid]<target:
            left = mid + 1
        else:
            right = mid
    return left

if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    target = int(input().strip())
    print(search(nums,target))

4. 反思

本题主要是要注意，在左闭右闭过程中，二分搜索中全T的情况，这样要判断末尾，left不会停到数组外。但是如果是左闭右开就无所谓。

搜索二维矩阵

1. 题面

74. 搜索二维矩阵

难度：中等

给你一个满足下述两条属性的 m x n 整数矩阵：

每行中的整数从左到右按非严格递增顺序排列。
每行的第一个整数大于前一行的最后一个整数。

给你一个整数 target ，如果 target 在矩阵中，返回 true ；否则，返回 false 。

示例 1：

输入：matrix = [[1,3,5,7],[10,11,16,20],[23,30,34,60]], target = 3
输出：true

示例 2：

输入：matrix = [[1,3,5,7],[10,11,16,20],[23,30,34,60]], target = 13
输出：false

提示：

m == matrix.length
n == matrix[i].length
1 <= m, n <= 100
-10^4 <= matrix[i][j], target <= 10^4

2. 题解

# 这题算是直接找两侧有序的退化版，直接展开然后二分就行
# 小于Target是T，TTTFFF，第一个F就（可能是）要求的值，在找值问题时候还要判断一下

import ast

def search(nums:list[int],target:int)->bool:
    left = 0
    right = len(nums)
    while left < right:
        mid = (left + right) // 2
        if nums[mid]<target:
            left = mid + 1
        elif nums[mid]> target:
            right = mid
        elif nums[mid] == target:
            return True
    return False

if __name__ == "__main__":
    matrix = ast.literal_eval(input().strip())
    target = int(input().strip())
    flat = [x for row in matrix for x in row]
    print(search(flat,target))

在排序数组中查找元素的第一个和最后一个位置

1. 题面

34. 在排序数组中查找元素的第一个和最后一个位置

难度：中等

给你一个按照非递减顺序排列的整数数组 nums，和一个目标值 target。请你找出给定目标值在数组中的开始位置和结束位置。

如果数组中不存在目标值 target，返回 [-1, -1]。

你必须设计并实现时间复杂度为 O(log n) 的算法解决此问题。

示例 1：

输入：nums = [5,7,7,8,8,10], target = 8
输出：[3,4]

示例 2：

输入：nums = [5,7,7,8,8,10], target = 6
输出：[-1,-1]

示例 3：

输入：nums = [], target = 0
输出：[-1,-1]

提示：

0 <= nums.length <= 10^5
-10^9 <= nums[i] <= 10^9
nums 是一个非递减数组
-10^9 <= target <= 10^9

2. 题解

# 标准二分查找找左右边界
# 小于target是TTTFFF，小于等于target是TTTTFF，分别找第一个左边界和右边界

import ast

def left_bound(nums:list,target:int):
    left = 0
    right = len(nums)
    while left < right:
        mid = (left + right) // 2
        if nums[mid] < target:
            left = mid + 1
        else:
            right = mid
    # left可能出界
    if left == len(nums) or nums[left] != target:
        return -1
    return left


def right_bound(nums:list,target:int):
    left = 0
    right = len(nums)
    while left < right:
        mid = (left + right) // 2
        if nums[mid] <= target:
            left = mid + 1
        else:
            right = mid
    # left可能出界
    if left == 0 or nums[left-1] != target:
        return -1
    return left-1

if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    target = int(input().strip())
    left = left_bound(nums,target)
    right = right_bound(nums,target)
    print([left,right])

3. 反思

采取了统一的TTFFF方法，注意左闭右开left最后可能出界，然后右边界的时候可能left-1越界，细看边界保护就好。

4. 二刷

统一采用left落在第一个T的二分查找，即左闭右开，然后特殊判断是否满足题目要求即可。

搜索旋转排序数组

1. 题面

33. 搜索旋转排序数组

难度：中等

整数数组 nums 按升序排列，数组中的值 互不相同 。

在传递给函数之前，nums 在预先未知的某个下标 k（0 <= k < nums.length）上进行了 向左旋转 ，使数组变为 [nums[k], nums[k+1], ..., nums[n-1], nums[0], nums[1], ..., nums[k-1]]（下标 从 0 开始 计数）。例如， [0,1,2,4,5,6,7] 下标 3 上向左旋转后可能变为 [4,5,6,7,0,1,2] 。

给你 旋转后 的数组 nums 和一个整数 target ，如果 nums 中存在这个目标值 target ，则返回它的下标，否则返回 -1 。

你必须设计一个时间复杂度为 O(log n) 的算法解决此问题。

示例 1：

输入：nums = [4,5,6,7,0,1,2], target = 0
输出：4

示例 2：

输入：nums = [4,5,6,7,0,1,2], target = 3
输出：-1

示例 3：

输入：nums = [1], target = 0
输出：-1

提示：

1 <= nums.length <= 5000
-10^4 <= nums[i] <= 10^4
nums 中的每个值都 独一无二
题目数据保证 nums 在预先未知的某个下标上进行了旋转
-10^4 <= target <= 10^4

2. 题解

# 未知下标，我们可以利用二叉搜索的判断趋势的功能，先找到到底是在哪递增变递减的。
# 我们按nums最后的数来创建bool数组，可以知道前面k分界前面的数都是大于last的，后面的都是小于等于，所以nums[mid]>nums[-1]就可以构成 TTTFFF，第一个F就是原数组开头

import ast

def search_range(nums: list[int], left: int, right: int, target: int) -> int:
    # 在 [left, right) 内二分查找 target
    while left < right:
        mid = (left + right) // 2
        if nums[mid] < target:
            left = mid + 1
        elif nums[mid] > target:
            right = mid
        else:
            return mid
    return -1


def findK(nums: list[int]) -> int:
    # 找最小值下标，也就是旋转点
    left = 0
    right = len(nums)
    last = nums[-1]

    while left < right:
        mid = (left + right) // 2
        if nums[mid] > last:
            left = mid + 1
        else:
            right = mid

    return left


def solution(nums: list[int], target: int) -> int:
    if not nums:
        return -1

    k = findK(nums)
    n = len(nums)

    # 看看在哪半边，查询哪半边
    if nums[k] <= target <= nums[n - 1]:
        return search_range(nums, k, n, target)
    else:
        return search_range(nums, 0, k, target)


if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    target = int(input().strip())
    # 先找到切分位置
    print(solution(nums,target))

3. 反思

这里findK对于找pivot的方法比较巧妙，可以仔细看看。

4. 二刷

二刷写错了找pivot的方式，属于错误判断了FFFTTT和FFFTFF，用趋势来判断不行，必须用数组最后一位来判断，小于等于它的为右半边的T，大于它的为左半边的F。

但是，这一题更好的解法是直接一次二分，因为二分之后总有一半是有序的，先看target在不在这个有序区间内，在就进入这半边，不在就去另一边。

def solution(nums, target):
    left, right = 0, len(nums)

    while left < right:
        mid = (left + right) // 2

        if nums[mid] == target:
            return mid

        # 左半部分有序
        if nums[left] <= nums[mid]:
            if nums[left] <= target < nums[mid]:
                right = mid
            else:
                left = mid + 1
        # 右半部分有序
        else:
            if nums[mid] < target <= nums[right - 1]:
                left = mid + 1
            else:
                right = mid

    return -1

寻找旋转排序数组中的最小值

1. 题面

153. 寻找旋转排序数组中的最小值

难度：中等

已知一个长度为 n 的数组，预先按照升序排列，经由 1 到 n 次旋转后，得到输入数组。例如，原数组 nums = [0,1,2,4,5,6,7] 在变化后可能得到：

若旋转 4 次，则可以得到 [4,5,6,7,0,1,2]
若旋转 7 次，则可以得到 [0,1,2,4,5,6,7]

注意，数组 [a[0], a[1], a[2], ..., a[n-1]] 旋转一次 的结果为数组 [a[n-1], a[0], a[1], a[2], ..., a[n-2]] 。

给你一个元素值 互不相同 的数组 nums ，它原来是一个升序排列的数组，并按上述情形进行了多次旋转。请你找出并返回数组中的 最小元素 。

你必须设计一个时间复杂度为 O(log n) 的算法解决此问题。

示例 1：

输入：nums = [3,4,5,1,2]
输出：1
解释：原数组为 [1,2,3,4,5] ，旋转 3 次得到输入数组。

示例 2：

输入：nums = [4,5,6,7,0,1,2]
输出：0
解释：原数组为 [0,1,2,4,5,6,7] ，旋转 4 次得到输入数组。

示例 3：

输入：nums = [11,13,15,17]
输出：11
解释：原数组为 [11,13,15,17] ，旋转 4 次得到输入数组。

提示：

n == nums.length
1 <= n <= 5000
-5000 <= nums[i] <= 5000
nums 中的所有整数 互不相同
nums 原来是一个升序排序的数组，并进行了 1 至 n 次旋转

2. 题解

# 等于给上一题降低难度了

import ast

def findPivot(nums:list):
    left = 0
    right = len(nums)
    last = nums[-1]
    while left<right:
        mid = (left + right) // 2
        if nums[mid] > last:
            left = mid + 1
        else:
            right = mid
    return nums[left]

if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    print(findPivot(nums))

寻找两个正序数组的中位数

1. 题面

4. 寻找两个正序数组的中位数

难度：困难

给定两个大小分别为 m 和 n 的正序（从小到大）数组 nums1 和 nums2。请你找出并返回这两个正序数组的 中位数 。

算法的时间复杂度应该为 O(log (m+n)) 。

示例 1：

输入：nums1 = [1,3], nums2 = [2]
输出：2.00000
解释：合并数组 = [1,2,3] ，中位数 2

示例 2：

输入：nums1 = [1,2], nums2 = [3,4]
输出：2.50000
解释：合并数组 = [1,2,3,4] ，中位数 (2 + 3) / 2 = 2.5

提示：

nums1.length == m
nums2.length == n
0 <= m <= 1000
0 <= n <= 1000
1 <= m + n <= 2000
-10^6 <= nums1[i], nums2[i] <= 10^6

2. 题解

# 这题要求复杂度O(log (m+n))那就不能用合并做了。需要用二分。
# 二分切分较短数组，找到一个切点，使得左半部分总长度等于右半部分，并且左边最大值 <= 右边最小值。

def solution(nums1: list[int], nums2: list[int]) -> float:
    # 保证在更短的数组上二分
    if len(nums1) > len(nums2):
        nums1, nums2 = nums2, nums1

    m, n = len(nums1), len(nums2)
    total_left = (m + n + 1) // 2

    left, right = 0, m

    while left <= right:
        i = (left + right) // 2
        j = total_left - i

        nums1_left_max = float("-inf") if i == 0 else nums1[i - 1]
        nums1_right_min = float("inf") if i == m else nums1[i]

        nums2_left_max = float("-inf") if j == 0 else nums2[j - 1]
        nums2_right_min = float("inf") if j == n else nums2[j]

        if nums1_left_max <= nums2_right_min and nums2_left_max <= nums1_right_min:
            if (m + n) % 2 == 1:
                return float(max(nums1_left_max, nums2_left_max))
            return (
                max(nums1_left_max, nums2_left_max)
                + min(nums1_right_min, nums2_right_min)
            ) / 2.0

        elif nums1_left_max > nums2_right_min:
            right = i - 1
        else:
            left = i + 1



if __name__ == "__main__":
    nums1 = list(map(int,input().strip().split(',')))
    nums2 = list(map(int,input().strip().split(',')))
    print(solution(nums1,nums2))

3. 反思

直接O(m+n)很简单，二分太复杂了好恶心，暂时先不看。

有效的括号

1. 题面

20. 有效的括号

难度：简单

给定一个只包括 '('，')'，'{'，'}'，'['，']' 的字符串 s ，判断字符串是否有效。

有效字符串需满足：

左括号必须用相同类型的右括号闭合。
左括号必须以正确的顺序闭合。
每个右括号都有一个对应的相同类型的左括号。

示例 1：

**输入：**s = "()"

**输出：**true

示例 2：

**输入：**s = "()[]{}"

**输出：**true

示例 3：

**输入：**s = "(]"

**输出：**false

示例 4：

**输入：**s = "([])"

**输出：**true

示例 5：

**输入：**s = "([)]"

**输出：**false

提示：

1 <= s.length <= 10^4
s 仅由括号 '()[]{}' 组成

2. 题解

# 经典判断有效性
# 用一个栈，不断入，遇到对应左括号弹出，最后看栈空不空就行

def solution(s: str) -> bool:
    stack = []
    mp = {
        ')': '(',
        ']': '[',
        '}': '{'
    }

    for ch in s:
        if ch in mp:
            if not stack or stack[-1] != mp[ch]:
                return False
            stack.pop()
        else:
            stack.append(ch)

    return len(stack) == 0

if __name__ == "__main__":
    s = input().strip()
    print(solution(s))

最小栈

1. 题面

155. 最小栈

难度：中等

设计一个支持 push ，pop ，top 操作，并能在常数时间内检索到最小元素的栈。

实现 MinStack 类:

MinStack() 初始化堆栈对象。
void push(int val) 将元素val推入堆栈。
void pop() 删除堆栈顶部的元素。
int top() 获取堆栈顶部的元素。
int getMin() 获取堆栈中的最小元素。

示例 1:

输入：
["MinStack","push","push","push","getMin","pop","top","getMin"]
[[],[-2],[0],[-3],[],[],[],[]]

输出：
[null,null,null,null,-3,null,0,-2]

解释：
MinStack minStack = new MinStack();
minStack.push(-2);
minStack.push(0);
minStack.push(-3);
minStack.getMin();   --> 返回 -3.
minStack.pop();
minStack.top();      --> 返回 0.
minStack.getMin();   --> 返回 -2.

提示：

-2^31 <= val <= 2^31 - 1
pop、top 和 getMin 操作总是在 非空栈 上调用
push, pop, top, and getMin最多被调用 3 * 10^4 次

2. 题解

# 单调栈是两个栈实现的

import ast

class MinStack:
    def __init__(self):
        self.stack = []
        self.min_stack = []

    def push(self, val: int) -> None:
        self.stack.append(val)
        if not self.min_stack:
            self.min_stack.append(val)
        # 比较小才会加入栈
        else:
            self.min_stack.append(min(val, self.min_stack[-1]))

    def pop(self) -> None:
        self.stack.pop()
        self.min_stack.pop()

    def top(self) -> int:
        return self.stack[-1]

    def getMin(self) -> int:
        return self.min_stack[-1]


if __name__ == "__main__":
    ops = ast.literal_eval(input().strip().replace("null", "None"))
    args = ast.literal_eval(input().strip().replace("null", "None"))

    ans = []
    obj = None

    for op, arg in zip(ops, args):
        if op == "MinStack":
            obj = MinStack()
            ans.append(None)
        elif op == "push":
            obj.push(arg[0])
            ans.append(None)
        elif op == "pop":
            obj.pop()
            ans.append(None)
        elif op == "top":
            ans.append(obj.top())
        elif op == "getMin":
            ans.append(obj.getMin())

    print(str(ans).replace("None", "null"))

字符串编码

1. 题面

394. 字符串解码

难度：中等

给定一个经过编码的字符串，返回它解码后的字符串。

编码规则为: k[encoded_string]，表示其中方括号内部的 encoded_string 正好重复 k 次。注意 k 保证为正整数。

你可以认为输入字符串总是有效的；输入字符串中没有额外的空格，且输入的方括号总是符合格式要求的。

此外，你可以认为原始数据不包含数字，所有的数字只表示重复的次数 k ，例如不会出现像 3a 或 2[4] 的输入。

测试用例保证输出的长度不会超过 10^5。

示例 1：

输入：s = "3[a]2[bc]"
输出："aaabcbc"

示例 2：

输入：s = "3[a2[c]]"
输出："accaccacc"

示例 3：

输入：s = "2[abc]3[cd]ef"
输出："abcabccdcdcdef"

示例 4：

输入：s = "abc3[cd]xyz"
输出："abccdcdcdxyz"

提示：

1 <= s.length <= 30
s 由小写英文字母、数字和方括号 '[]' 组成
s 保证是一个有效的输入。
s 中所有整数的取值范围为 [1, 300]

2. 题解

# 思路确实比较难想，先背板

from collections import deque

def decodeString(s: str) -> str:
    # 重新尝试自己写出来代码
    # 缓冲目前字符
    curr_buffer=[]
    stack=[]
    # 记录倍率数字，注意可能不止一位数
    mul=0
    for ch in s:
        # 检查是否为左括号，如果是，要把上一轮的buffer和数字全部入栈，并清理状态
        if ch=='[':
            curr_name="".join(curr_buffer)               
            stack.append((curr_name,mul))
            curr_buffer=[]
            mul=0
        # 碰到右括号，可以开始处理之前冻结（还无法处理的）字符串了，乘以其倍率添加到curr
        elif ch == ']':
            curr_name="".join(curr_buffer)
            # 过去的倍率千万不能覆盖现在的mul
            last_str,old_mul=stack.pop()
            curr_buffer=[last_str+curr_name*old_mul]
        # 如果是数字，则判断之前有没有出现过数字，如果有则要加位数
        # 注意这里的数字存的是下一次curr的倍率而不是last的倍率
        elif ch.isdigit():
            mul=mul*10+int(ch)
        else:
            curr_buffer.append(ch)
    return "".join(curr_buffer)

if __name__ == "__main__":
    s = input().strip()
    print(decodeString(s))

每日温度

1. 题面

739. 每日温度

难度：中等

给定一个整数数组 temperatures ，表示每天的温度，返回一个数组 answer ，其中 answer[i] 是指对于第 i 天，下一个更高温度出现在几天后。如果气温在这之后都不会升高，请在该位置用 0 来代替。

示例 1:

输入: temperatures = [73,74,75,71,69,72,76,73]
输出: [1,1,4,2,1,1,0,0]

示例 2:

输入: temperatures = [30,40,50,60]
输出: [1,1,1,0]

示例 3:

输入: temperatures = [30,60,90]
输出: [1,1,0]

提示：

1 <= temperatures.length <= 10^5
30 <= temperatures[i] <= 100

2. 题解

# 找右边第一个比自己大的元素，将相对几天填入（也就是坐标差），这是经典单调栈，存下标

import ast
from collections import deque

def solution(temperatures:list)->list:
    q = deque()
    n = len(temperatures)
    ans = [0] * n
    for i,val in enumerate(temperatures):
        while q and temperatures[q[-1]]< val:
            idx = q.pop()
            ans[idx] = i - idx
        q.append(i)
    return ans

if __name__ == "__main__":
    temperatures = ast.literal_eval(input().strip())
    print(solution(temperatures))

柱状图中最大的矩形

1. 题面

84. 柱状图中最大的矩形

难度：困难

给定 n 个非负整数，用来表示柱状图中各个柱子的高度。每个柱子彼此相邻，且宽度为 1 。

求在该柱状图中，能够勾勒出来的矩形的最大面积。

示例 1:

输入：heights = [2,1,5,6,2,3]
输出：10
解释：最大的矩形为图中红色区域，面积为 10

示例 2：

输入： heights = [2,4]
输出： 4

提示：

1 <= heights.length <=10^5
0 <= heights[i] <= 10^4

2. 题解

# 我们可以构造一个单调递增栈，因为是找左侧第一个比curr小的，找到这个下标之后就可以用curr_idx - left_idx + 1当做宽度，用left_height当做高度，得出这里的矩阵面积
# 维持一个全局量max_S
# 为了保证全部弹出（因为弹出才结算），还有防止找不到左侧第一个比curr小的，需要两侧+0

import ast
from collections import deque

def solution(heights: list) -> int:
    heights = [0] + heights + [0]
    stack = []
    ans = 0

    for i, h in enumerate(heights):
        while stack and heights[stack[-1]] > h:
            idx = stack.pop()
            height = heights[idx]
            # 注意这里被弹出的柱子，还要看左边第一个比它小的，在到达那里之前还可以向左延伸
            width = i - stack[-1] - 1
            ans = max(ans, height * width)
        stack.append(i)

    return ans



if __name__ == "__main__":
    heights = ast.literal_eval(input().strip())
    print(solution(heights))

3. 反思

一定要注意还可以向左延伸。单调递增栈 -> 找左侧第一个比curr小的；单调递减栈 -> 找右侧第一个比弹出大的

数组中的第K个最大元素

1. 题面

215. 数组中的第K个最大元素

难度：中等

给定整数数组 nums 和整数 k，请返回数组中第 **k** 个最大的元素。

请注意，你需要找的是数组排序后的第 k 个最大的元素，而不是第 k 个不同的元素。

你必须设计并实现时间复杂度为 O(n) 的算法解决此问题。

示例 1:

输入: [3,2,1,5,6,4], k = 2
输出: 5

示例 2:

输入: [3,2,3,1,2,4,5,5,6], k = 4
输出: 4

提示：

1 <= k <= nums.length <= 10^5
-10^4 <= nums[i] <= 10^4

2. 题解

# 这题在hot100中被归到了堆，但是堆是Onlogk的，而且k是动态的，严格的解法不能用堆。
# 这题的正确做法是quickselect，即快速选择算法

import ast
import random


def solution(nums: list[int], k: int) -> int:
    target = len(nums) - k  # 第k大 -> 升序下标 target

    def quick_select(left: int, right: int) -> int:
        pivot_idx = random.randint(left, right)
        pivot = nums[pivot_idx]

        # 先把 pivot 放到末尾
        nums[pivot_idx], nums[right] = nums[right], nums[pivot_idx]

        store = left
        for i in range(left, right):
            if nums[i] < pivot:
                nums[store], nums[i] = nums[i], nums[store]
                store += 1

        # pivot 放回最终位置
        nums[store], nums[right] = nums[right], nums[store]

        if store == target:
            return nums[store]
        elif store < target:
            return quick_select(store + 1, right)
        else:
            return quick_select(left, store - 1)

    return quick_select(0, len(nums) - 1)


if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    k = int(input().strip())
    print(solution(nums, k))

3. 反思

快速选择算法，没听说过！还得细看。

前 K 个高频元素

1. 题面

347. 前 K 个高频元素

难度：中等

给你一个整数数组 nums 和一个整数 k ，请你返回其中出现频率前 k 高的元素。你可以按 任意顺序 返回答案。

示例 1：

**输入：**nums = [1,1,1,2,2,3], k = 2

输出： [1,2]

示例 2：

**输入：**nums = [1], k = 1

输出：[1]

示例 3：

**输入：**nums = [1,2,1,2,1,2,3,1,3,2], k = 2

输出： [1,2]

提示：

1 <= nums.length <= 10^5
-10^4 <= nums[i] <= 10^4
k 的取值范围是 [1, 数组中不相同的元素的个数]
题目数据保证答案唯一，换句话说，数组中前 k 个高频元素的集合是唯一的

进阶： 你所设计算法的时间复杂度必须优于 O(n log n) ，其中 n 是数组大小。

2. 题解

# 一眼堆，我们先转换成哈希表，然后存 value-key 到堆中，维持大小k

import heapq
import ast
from collections import Counter

def solution(nums:list,k:int):
    cnt = Counter(nums)
    heap = []

    for num, freq in cnt.items():
        heapq.heappush(heap, (freq, num))
        if len(heap) > k:
            heapq.heappop(heap)

    ans = [num for freq, num in heap]
    return ans

if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    k = int(input().strip())
    print(solution(nums,k))

数据流的中位数

1. 题面

295. 数据流的中位数

难度：困难

中位数 是有序整数列表中的中间值。如果列表的大小是偶数，则没有中间值，中位数是两个中间值的平均值。

例如 arr = [2,3,4] 的中位数是 3 。
例如 arr = [2,3] 的中位数是 (2 + 3) / 2 = 2.5 。

实现 MedianFinder 类:

MedianFinder() 初始化 MedianFinder 对象。
void addNum(int num) 将数据流中的整数 num 添加到数据结构中。
double findMedian() 返回到目前为止所有元素的中位数。与实际答案相差 10^-5 以内的答案将被接受。

示例 1：

输入
["MedianFinder", "addNum", "addNum", "findMedian", "addNum", "findMedian"]
[[], [1], [2], [], [3], []]
输出
[null, null, null, 1.5, null, 2.0]

解释
MedianFinder medianFinder = new MedianFinder();
medianFinder.addNum(1);    // arr = [1]
medianFinder.addNum(2);    // arr = [1, 2]
medianFinder.findMedian(); // 返回 1.5 ((1 + 2) / 2)
medianFinder.addNum(3);    // arr[1, 2, 3]
medianFinder.findMedian(); // return 2.0

提示:

-10^5 <= num <= 10^5
在调用 findMedian 之前，数据结构中至少有一个元素
最多 5 * 10^4 次调用 addNum 和 findMedian

2. 题解

# 这题的实现方法是维持两个堆，一个大根一个小根，先放进小根，然后保证small的最大小于large的最小，不然就拿出来扔最大里面。

import heapq
import ast

class MedianFinder:
    def __init__(self):
        # small: 大根堆（用相反数模拟），存较小的一半
        self.small = []
        # large: 小根堆，存较大的一半
        self.large = []

    def addNum(self, num: int) -> None:
        # 先放进 small
        heapq.heappush(self.small, -num)

        # 保证 small 里的最大值 <= large 里的最小值
        heapq.heappush(self.large, -heapq.heappop(self.small))

        # 保证 small 的元素个数 >= large，这样才能保证中位数放在small这边
        if len(self.large) > len(self.small):
            heapq.heappush(self.small, -heapq.heappop(self.large))

    def findMedian(self) -> float:
        # 如果small长，那就奇数
        if len(self.small) > len(self.large):
            return float(-self.small[0])
        # 否则是偶数
        return (-self.small[0] + self.large[0]) / 2.0

        

if __name__ == "__main__":
    ops = ast.literal_eval(input().strip())
    vals = ast.literal_eval(input().strip())
    ans = []
    for op,val in zip(ops,vals):
        if op == 'MedianFinder':
            m = MedianFinder()
            ans.append("null")
        if op == "addNum":
            m.addNum(val[0])
            ans.append("null")
        if op == "findMedian":
            ans.append(m.findMedian())
    print(ans)

买卖股票的最佳时机

1. 题面

121. 买卖股票的最佳时机

难度：简单

给定一个数组 prices ，它的第 i 个元素 prices[i] 表示一支给定股票第 i 天的价格。

你只能选择 某一天 买入这只股票，并选择在 未来的某一个不同的日子 卖出该股票。设计一个算法来计算你所能获取的最大利润。

返回你可以从这笔交易中获取的最大利润。如果你不能获取任何利润，返回 0 。

示例 1：

输入：[7,1,5,3,6,4]
输出：5
解释：在第 2 天（股票价格 = 1）的时候买入，在第 5 天（股票价格 = 6）的时候卖出，最大利润 = 6-1 = 5 。
     注意利润不能是 7-1 = 6, 因为卖出价格需要大于买入价格；同时，你不能在买入前卖出股票。

示例 2：

输入：prices = [7,6,4,3,1]
输出：0
解释：在这种情况下, 没有交易完成, 所以最大利润为 0。

提示：

1 <= prices.length <= 10^5
0 <= prices[i] <= 10^4

2. 题解

# 本质上是找高度差最大的两个元素，我们遍历的时候维持两个量 - 目前见过的最低价格，今天卖出可以得到的利润

import ast


def solution(prices: list[int]) -> int:
    min_price = float("inf")
    ans = 0

    for price in prices:
        min_price = min(min_price, price)
        # 今天卖出的利润和过去卖出的利润比较
        ans = max(ans, price - min_price)

    return ans


if __name__ == "__main__":
    prices = ast.literal_eval(input().strip())
    print(solution(prices))

跳跃游戏

1. 题面

55. 跳跃游戏

难度：中等

给你一个非负整数数组 nums ，你最初位于数组的 第一个下标 。数组中的每个元素代表你在该位置可以跳跃的最大长度。

判断你是否能够到达最后一个下标，如果可以，返回 true ；否则，返回 false 。

示例 1：

输入：nums = [2,3,1,1,4]
输出：true
解释：可以先跳 1 步，从下标 0 到达下标 1, 然后再从下标 1 跳 3 步到达最后一个下标。

示例 2：

输入：nums = [3,2,1,0,4]
输出：false
解释：无论怎样，总会到达下标为 3 的位置。但该下标的最大跳跃长度是 0 ， 所以永远不可能到达最后一个下标。

提示：

1 <= nums.length <= 10^4
0 <= nums[i] <= 10^5

2. 题解

# 做法是维持当前能到达的最远距离max(当前最远可达位置, i + nums[i])

import ast


def solution(nums: list[int]) -> bool:
    farthest = 0

    for i, step in enumerate(nums):
        if i > farthest:
            return False
        farthest = max(farthest, i + step)

    return True


if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    print(solution(nums))

跳跃游戏 II

1. 题面

45. 跳跃游戏 II

难度：中等

给定一个长度为 n 的 0 索引 整数数组 nums。初始位置在下标 0。

每个元素 nums[i] 表示从索引 i 向后跳转的最大长度。换句话说，如果你在索引 i 处，你可以跳转到任意 (i + j) 处：

0 <= j <= nums[i] 且
i + j < n

返回到达 n - 1 的最小跳跃次数。测试用例保证可以到达 n - 1。

示例 1:

输入: nums = [2,3,1,1,4]
输出: 2
解释: 跳到最后一个位置的最小跳跃数是 2。
     从下标为 0 跳到下标为 1 的位置，跳 1 步，然后跳 3 步到达数组的最后一个位置。

示例 2:

输入: nums = [2,3,0,1,4]
输出: 2

提示:

1 <= nums.length <= 10^4
0 <= nums[i] <= 1000
题目保证可以到达 n - 1

2. 题解

# 还是维持一个目前能跳到的最远距离遍历，为了记录步数再多维持一个steps。当i达到最远时steps+1

import ast


def solution(nums: list[int]) -> int:
    steps = 0
    end = 0
    farthest = 0

    # 最后一个位置不用再跳了，所以遍历到 n-2 即可
    # 跳到最后一个位置这件事，是在前一个“边界结算”里就已经计数了，不需要等真的站上最后一个格子再加一次。
    for i in range(len(nums) - 1):
        farthest = max(farthest, i + nums[i])

        # 走到当前这一步的边界，必须进行下一跳
        if i == end:
            steps += 1
            end = farthest

    return steps


if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    print(solution(nums))

划分字母区间

1. 题面

763. 划分字母区间

难度：1443

给你一个字符串 s 。我们要把这个字符串划分为尽可能多的片段，同一字母最多出现在一个片段中。例如，字符串 "ababcc" 能够被分为 ["abab", "cc"]，但类似 ["aba", "bcc"] 或 ["ab", "ab", "cc"] 的划分是非法的。

注意，划分结果需要满足：将所有划分结果按顺序连接，得到的字符串仍然是 s 。

返回一个表示每个字符串片段的长度的列表。

示例 1：

输入：s = "ababcbacadefegdehijhklij"
输出：[9,7,8]
解释：
划分结果为 "ababcbaca"、"defegde"、"hijhklij" 。
每个字母最多出现在一个片段中。
像 "ababcbacadefegde", "hijhklij" 这样的划分是错误的，因为划分的片段数较少。

示例 2：

输入：s = "eccbbbbdec"
输出：[10]

提示：

1 <= s.length <= 500
s 仅由小写英文字母组成

2. 题解

# 第一次肯定弄不出来的贪心+1，我们看看题解思路吧

def solution(s: str) -> list[int]:
    last = {}
    # 记录每个字母最晚出现在哪
    for i, ch in enumerate(s):
        last[ch] = i

    ans = []
    start = 0
    end = 0

    # 贪心：当前分段的右边界 = 这一段里所有字符最后出现位置的最大值。
    for i, ch in enumerate(s):
        end = max(end, last[ch])

        if i == end:
            ans.append(end - start + 1)
            start = i + 1

    return ans

if __name__ == "__main__":
    s = input().strip()
    print(solution(s))

爬楼梯

1. 题面

70. 爬楼梯

难度：简单

假设你正在爬楼梯。需要 n 阶你才能到达楼顶。

每次你可以爬 1 或 2 个台阶。你有多少种不同的方法可以爬到楼顶呢？

示例 1：

输入：n = 2
输出：2
解释：有两种方法可以爬到楼顶。
1. 1 阶 + 1 阶
2. 2 阶

示例 2：

输入：n = 3
输出：3
解释：有三种方法可以爬到楼顶。
1. 1 阶 + 1 阶 + 1 阶
2. 1 阶 + 2 阶
3. 2 阶 + 1 阶

提示：

1 <= n <= 45

2. 题解

# 基础动规

def solution(n:int)->int:
    dp = [0]*(n+1)
    dp[0] = 1
    dp[1] = 1
    # 转移 dp[i] = dp[i-1] + dp[i-2]
    for i in range(2,n+1):
        dp[i] = dp[i-1] + dp[i-2]
    return dp[n]

if __name__ == "__main__":
    n = int(input().strip())
    print(solution(n))

杨辉三角

1. 题面

118. 杨辉三角

难度：简单

给定一个非负整数 _numRows，_生成「杨辉三角」的前 numRows 行。

在 「杨辉三角」 中，每个数是它左上方和右上方的数的和。

示例 1:

输入: numRows = 5
输出: [[1],[1,1],[1,2,1],[1,3,3,1],[1,4,6,4,1]]

示例 2:

输入: numRows = 1
输出: [[1]]

提示:

1 <= numRows <= 30

2. 题解

# array[i][j] = array[i-1][j-1] + array[i-1][j]，转移方程

def solution(n:int):
    # 左侧添加一个0保护
    array = [[0] * (n + 1) for _ in range(n)]
    array[0][1] = 1

    for i in range(1, n):
        for j in range(1, n + 1):
            array[i][j] = array[i - 1][j - 1] + array[i - 1][j]

    ans = []
    # 每行只取有效部分，利用行下标
    for i in range(n):
        ans.append(array[i][1:i + 2])

    return ans


if __name__ == "__main__":
    n = int(input().strip())
    print(solution(n))

打家劫舍

1. 题面

198. 打家劫舍

难度：中等

你是一个专业的小偷，计划偷窃沿街的房屋。每间房内都藏有一定的现金，影响你偷窃的唯一制约因素就是相邻的房屋装有相互连通的防盗系统， 如果两间相邻的房屋在同一晚上被小偷闯入，系统会自动报警 。

给定一个代表每个房屋存放金额的非负整数数组，计算你 不触动警报装置的情况下 ，一夜之内能够偷窃到的最高金额。

示例 1：

输入：[1,2,3,1]
输出：4
解释：偷窃 1 号房屋 (金额 = 1) ，然后偷窃 3 号房屋 (金额 = 3)。
     偷窃到的最高金额 = 1 + 3 = 4 。

示例 2：

输入：[2,7,9,3,1]
输出：12
解释：偷窃 1 号房屋 (金额 = 2), 偷窃 3 号房屋 (金额 = 9)，接着偷窃 5 号房屋 (金额 = 1)。
     偷窃到的最高金额 = 2 + 9 + 1 = 12 。

提示：

1 <= nums.length <= 100
0 <= nums[i] <= 400

2. 题解

# 定义dp[i]为到i位置可以抢劫的最大金额，他就等于max(dp[i-1],dp[i-2]+nums[i])，意思是要么不偷，维持dp[i-1]的方案；要么偷，从前面选不会报警的最大金额方案

def solution(nums:list):
    n = len(nums)
    if not nums:
        return 0
    if n == 1:
        return nums[0]
    dp = [0]*(n+1)
    dp[0] = nums[0]
    dp[1] = max(nums[0], nums[1])
    for i in range(2,n):
        dp[i] = max(dp[i-2]+nums[i],dp[i-1])
    return dp[n-1]

if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    print(solution(nums))

3. 反思

注意这里dp[i]的含义，我们不需要遍历前面最大的dp，只要看dp[i-2]就行

完全平方数

1. 题面

279. 完全平方数

难度：中等

给你一个整数 n ，返回 和为 n 的完全平方数的最少数量 。

完全平方数 是一个整数，其值等于另一个整数的平方；换句话说，其值等于一个整数自乘的积。例如，1、4、9 和 16 都是完全平方数，而 3 和 11 不是。

示例 1：

输入：n = 12
输出：3 
解释：12 = 4 + 4 + 4

示例 2：

输入：n = 13
输出：2
解释：13 = 4 + 9

提示：

1 <= n <= 10^4

2. 题解

# 我们令dp[i]为凑出数字i所需的最小完全平方数个数，则转移为min(dp[i],dp[i-j*j]+1)，也就是说这是一道选或不选的dp

def solution(n: int) -> int:
    dp = [float("inf")] * (n + 1)
    dp[0] = 0

    for i in range(1, n + 1):
        j = 1
        while j * j <= i:
            dp[i] = min(dp[i], dp[i - j * j] + 1)
            j += 1

    return dp[n]

if __name__ == "__main__":
    n = int(input().strip())
    print(solution(n))

3. 反思

这题好像默认一定能选出来，否则的话输出dp[n]还需要加一个无穷保护。

零钱兑换

1. 题面

322. 零钱兑换

难度：中等

给你一个整数数组 coins ，表示不同面额的硬币；以及一个整数 amount ，表示总金额。

计算并返回可以凑成总金额所需的 最少的硬币个数 。如果没有任何一种硬币组合能组成总金额，返回 -1 。

你可以认为每种硬币的数量是无限的。

示例 1：

输入：coins = [1, 2, 5], amount = 11
输出：3 
解释：11 = 5 + 5 + 1

示例 2：

输入：coins = [2], amount = 3
输出：-1

示例 3：

输入：coins = [1], amount = 0
输出：0

提示：

1 <= coins.length <= 12
1 <= coins[i] <= 2^31 - 1
0 <= amount <= 10^4

2. 题解

# 依旧选还是不选，然后最小问题，和上一题很相似，属于完全背包问题

def solution(coins:list,amount:int)->int:
    # dp[i]为金额i需要的最少coin数，转移方程为min(dp[i],dp[i-c]+1)
    dp = [float('inf')] * (amount+1)
    dp[0] = 0
    for i in range(amount+1):
        # 硬币无限，可以重复遍历
        for coin in coins:
            if coin<=i:
                dp[i] = min(dp[i],dp[i-coin]+1)
    return dp[amount] if dp[amount]!=float('inf') else -1

if __name__ == "__main__":
    coins = list(map(int,input().strip().split(',')))
    amount = int(input().strip())
    print(solution(coins,amount))

3. 反思

同样是完全背包问题，易错点是忘了让dp[0] = 0了。

单词拆分

1. 题面

139. 单词拆分

难度：中等

给你一个字符串 s 和一个字符串列表 wordDict 作为字典。如果可以利用字典中出现的一个或多个单词拼接出 s 则返回 true。

注意： 不要求字典中出现的单词全部都使用，并且字典中的单词可以重复使用。

示例 1：

输入: s = "leetcode", wordDict = ["leet", "code"]
输出: true
解释: 返回 true 因为 "leetcode" 可以由 "leet" 和 "code" 拼接成。

示例 2：

输入: s = "applepenapple", wordDict = ["apple", "pen"]
输出: true
解释: 返回 true 因为 "applepenapple" 可以由 "apple" "pen" "apple" 拼接成。
     注意，你可以重复使用字典中的单词。

示例 3：

输入: s = "catsandog", wordDict = ["cats", "dog", "sand", "and", "cat"]
输出: false

提示：

1 <= s.length <= 300
1 <= wordDict.length <= 1000
1 <= wordDict[i].length <= 20
s 和 wordDict[i] 仅由小写英文字母组成
wordDict 中的所有字符串 互不相同

2. 题解

# 依旧是无限资源凑目标，其实还是完全背包，注意设置dp为i个字母的时候可否凑成即可

import ast

def solution(s:str,wordDict:list[str])->bool:
    n = len(s)
    dp = [False] * (n+1)
    # 0个字母的时候，一定可以凑成
    dp[0] = True
    for i in range(1, n+1):
        for word in wordDict:
            if i>=len(word) and s[i-len(word):i] == word:
                # 完美背包要有防止覆盖的手段
                dp[i] = dp[i] or dp[i-len(word)]
                # 优化：如果有一种能凑出来了，就不用看了
                if dp[i]:
                    break

    return dp[n]

if __name__ == "__main__":
    s = input().strip()
    wordDict = ast.literal_eval(input().strip())
    print(solution(s,wordDict))

3. 反思

注意完全背包防止覆盖，最大最小问题往往会有min、max里面加上本身，T or F问题则是or一下本身。

最长递增子序列

1. 题面

300. 最长递增子序列

难度：中等

给你一个整数数组 nums ，找到其中最长严格递增子序列的长度。

子序列 是由数组派生而来的序列，删除（或不删除）数组中的元素而不改变其余元素的顺序。例如，[3,6,2,7] 是数组 [0,3,1,6,2,2,7] 的子序列。

示例 1：

输入：nums = [10,9,2,5,3,7,101,18]
输出：4
解释：最长递增子序列是 [2,3,7,101]，因此长度为 4 。

示例 2：

输入：nums = [0,1,0,3,2,3]
输出：4

示例 3：

输入：nums = [7,7,7,7,7,7,7]
输出：1

提示：

1 <= nums.length <= 2500
-10^4 <= nums[i] <= 10^4

进阶：

你能将算法的时间复杂度降低到 O(n log(n)) 吗?

2. 题解

# 最长递增子序列也是经典的dp，我们定义dp[i]为到第i位的最长递增子序列，则从前面找所有dp，如果满足该位置的数字比目前为止小，就和dp[i]本身比一下大小，保留最大的

def solution(nums:list)->int:
    n = len(nums)
    dp = [1] * n
    for i in range(1,n):
        for j in range(0,i):
            if nums[j]<nums[i]:
                dp[i] = max(dp[i],dp[j]+1)
    return max(dp)

if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    print(solution(nums))

3. 反思

本题的dp有点变化，首先是全部要初始化成1，因为至少也有本身数字这一个序列，所以也不需要初始化一个边界兜底。然后就是，最后要求的不是到最后一位的最长递增子序列，所以应该在dp里面找最大值。

乘积最大子数组

1. 题面

152. 乘积最大子数组

难度：中等

给你一个整数数组 nums ，请你找出数组中乘积最大的非空连续子数组（该子数组中至少包含一个数字），并返回该子数组所对应的乘积。

测试用例的答案是一个 32-位 整数。

请注意 ，一个只包含一个元素的数组的乘积是这个元素的值。

示例 1:

输入: nums = [2,3,-2,4]
输出: 6
解释: 子数组 [2,3] 有最大乘积 6。

示例 2:

输入: nums = [-2,0,-1]
输出: 0
解释: 结果不能为 2, 因为 [-2,-1] 不是子数组。

提示:

1 <= nums.length <= 2 * 10^4
-10 <= nums[i] <= 10
nums 的任何子数组的乘积都保证是一个 32-位 整数

2. 题解

# 必须要连续，那只要看上一位就行了。
# 但是本题有个跟加法不同的毒点，就是两个负数可能会翻转最小为最大，所以要用两个状态记录，一个max_prod一个min_prod。然后用max(x,max_prod*x,min_prod*x)来选择ans，并更新最大最小值

def solution(nums: list) -> int:
    max_prod = nums[0]
    min_prod = nums[0]
    ans = nums[0]

    for i in range(1, len(nums)):
        x = nums[i]

        candidates = (x, max_prod * x, min_prod * x)
        max_prod = max(candidates)
        min_prod = min(candidates)

        ans = max(ans, max_prod)

    return ans


if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    print(solution(nums))

3. 反思

本题考虑负数的翻转，需要额外维护变量，比较恶心

分割等和子集

1. 题面

416. 分割等和子集

难度：中等

给你一个 只包含正整数 的非空数组 nums 。请你判断是否可以将这个数组分割成两个子集，使得两个子集的元素和相等。

示例 1：

输入：nums = [1,5,11,5]
输出：true
解释：数组可以分割成 [1, 5, 5] 和 [11] 。

示例 2：

输入：nums = [1,2,3,5]
输出：false
解释：数组不能分割成两个元素和相等的子集。

提示：

1 <= nums.length <= 200
1 <= nums[i] <= 100

2. 题解 1 · 递归（时间超限）

# 转化一下，是否有子数组和为total的一半，每个数字选或者不选

def solution(nums:list)->bool:
    total = sum(nums)
    if total % 2 != 0:
        return False
    target = total // 2
    n = len(nums)
    # 递归函数判断能不能达到target
    def dfs(i,target)->bool:
        if target == 0:
            return True
        if i >= n or target<0:
            return False
        # 开始递归
        return dfs(i+1,target-nums[i]) or dfs(i+1,target)
    
    return dfs(0,target)

if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    print(solution(nums))

3. 题解 2 · 0/1背包

# 选或不选问题，其实可以用标准的0/1背包问题解决

def solution(nums: list) -> bool:
    total = sum(nums)
    if total % 2 != 0:
        return False

    target = total // 2
    dp = [False] * (target + 1)
    dp[0] = True

    # 0/1 背包：每个数只能用一次，所以要倒序遍历
    # dp[i]代表能否凑出i
    for num in nums:
        # 假设拿到了num，我们看看以前的选择能不能凑出来，如果能凑出j-num，那肯定就能凑出j
        # 与完全背包相对的，这里是倒序遍历。目的是为了保证num只用一次（只看没更新过的dp）
        # 而且注意范围，因为要看j-num要保护边界
        for j in range(target, num - 1, -1):
            dp[j] = dp[j] or dp[j - num]

    return dp[target]


if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    print(solution(nums))

4. 反思

这是一道0/1背包，注意和完全背包区分来学

最长有效括号

1. 题面

32. 最长有效括号

难度：困难

给你一个只包含 '(' 和 ')' 的字符串，找出最长有效（格式正确且连续）括号子串的长度。

左右括号匹配，即每个左括号都有对应的右括号将其闭合的字符串是格式正确的，比如 "(()())"。

示例 1：

输入：s = "(()"
输出：2
解释：最长有效括号子串是 "()"

示例 2：

输入：s = ")()())"
输出：4
解释：最长有效括号子串是 "()()"

示例 3：

输入：s = ""
输出：0

提示：

0 <= s.length <= 3 * 10^4
s[i] 为 '(' 或 ')'

2. 题解

# 我们让dp[i]为以 i 结尾的最长有效括号长度

def solution(s: str) -> int:
    n = len(s)
    dp = [0] * n
    ans = 0

    # dp[i] 表示：以 s[i] 结尾的最长有效括号长度
    for i in range(1, n):
        if s[i] == ')':
            # 情况1：...()
            if s[i - 1] == '(':
                dp[i] = (dp[i - 2] if i >= 2 else 0) + 2

            # 情况2：...))
            else:
                # 去找和当前这个 ')' 匹配的 '('
                j = i - dp[i - 1] - 1
                if j >= 0 and s[j] == '(':
                    dp[i] = dp[i - 1] + 2
                    # 把前面可能连着的有效括号也接上
                    if j - 1 >= 0:
                        dp[i] += dp[j - 1]

            ans = max(ans, dp[i])

    return ans

if __name__ == "__main__":
    s = input().strip()
    print(solution(s))

3. 反思

这题算是dp的大boss了。。

不同路径

1. 题面

62. 不同路径

难度：中等

一个机器人位于一个 m x n 网格的左上角（起始点在下图中标记为 “Start” ）。

机器人每次只能向下或者向右移动一步。机器人试图达到网格的右下角（在下图中标记为 “Finish” ）。

问总共有多少条不同的路径？

示例 1：

输入：m = 3, n = 7
输出：28

示例 2：

输入：m = 3, n = 2
输出：3
解释：
从左上角开始，总共有 3 条路径可以到达右下角。
1. 向右 -> 向下 -> 向下
2. 向下 -> 向下 -> 向右
3. 向下 -> 向右 -> 向下

示例 3：

输入：m = 7, n = 3
输出：28

示例 4：

输入：m = 3, n = 3
输出：6

提示：

1 <= m, n <= 100
题目数据保证答案小于等于 2 * 10^9

2. 题解

# 多维dp，因为只能向下或向右，我们先把第一行、第一列初始化
# dp[i][j]为到达(i,j)共有多少不同的路径

def solution(m:int,n:int)->int:
    dp = [[0]*n for row in range(m)]
    # 初始化边界
    for j in range(n):
        dp[0][j] = 1
    for i in range(m):
        dp[i][0] = 1

    # 更新dp
    for i in range(1,m):
        for j in range(1,n):
            dp[i][j] = dp[i-1][j] + dp[i][j-1]
    
    return dp[m-1][n-1]

if __name__ == "__main__":
    m = int(input().strip())
    n = int(input().strip())
    print(solution(m,n))

3. 反思

标准的多维dp

最小路径和

1. 题面

64. 最小路径和

难度：中等

给定一个包含非负整数的 _m_ x _n_ 网格 grid ，请找出一条从左上角到右下角的路径，使得路径上的数字总和为最小。

说明： 每次只能向下或者向右移动一步。

示例 1：

输入：grid = [[1,3,1],[1,5,1],[4,2,1]]
输出：7
解释：因为路径 1→3→1→1→1 的总和最小。

示例 2：

输入：grid = [[1,2,3],[4,5,6]]
输出：12

提示：

m == grid.length
n == grid[i].length
1 <= m, n <= 200
0 <= grid[i][j] <= 200

2. 题解

# 还是多维dp，同样需要初始化边界，用dp[i][j]表示到(i,j)最小的路径

import ast

def solution(grid:list[list[int]])->int:
    m = len(grid)
    n = len(grid[0])
    dp = [[0]*n for row in range(m)]
    # 初始化边界
    dp[0][0] = grid[0][0]
    for j in range(1,n):
        dp[0][j] = dp[0][j-1] + grid[0][j]
    for i in range(1,m):
        dp[i][0] = dp[i-1][0] + grid[i][0]
    
    # 开始dp
    for i in range(1,m):
        for j in range(1,n):
            dp[i][j] = min(dp[i-1][j],dp[i][j-1]) + grid[i][j]
    
    return dp[m-1][n-1]


if __name__ == "__main__":
    grid = ast.literal_eval(input().strip())
    print(solution(grid))

3. 反思

没啥说的，还是二维dp

最长回文子串

1. 题面

5. 最长回文子串

难度：中等

给你一个字符串 s，找到 s 中最长的回文子串。

示例 1：

输入：s = "babad"
输出："bab"
解释："aba" 同样是符合题意的答案。

示例 2：

输入：s = "cbbd"
输出："bb"

提示：

1 <= s.length <= 1000
s 仅由数字和英文字母组成

2. 题解 1 · 二维dp

# 最直接的做法是二重循环拿所有子串，用辅助函数判断是否是回文，然后维持一个最大长度，性能比较差
# 一个起点一个终点，可用二维动态规划。dp[i][j]表示s[i:j+1]是否是回文

def solution(s: str) -> str:
    n = len(s)
    dp = [[False] * n for _ in range(n)]

    start = 0
    max_len = 1

    # 单个字符一定是回文
    for i in range(n):
        dp[i][i] = True

    # 按子串长度递增枚举
    for length in range(2, n + 1):
        # 一定长度的i、j区间移动更新dp
        for i in range(n - length + 1):
            j = i + length - 1

            if s[i] != s[j]:
                dp[i][j] = False
            else:
                # 长度为 2 或 3 时，只要两端相等就是回文
                if length <= 3:
                    dp[i][j] = True
                else:
                    dp[i][j] = dp[i + 1][j - 1]

            if dp[i][j] and length > max_len:
                start = i
                max_len = length

    return s[start:start + max_len]

if __name__ == "__main__":
    s = input().strip()
    print(solution(s))

3. 题解 2 · 中心拓展

# 中心拓展法是不需要额外空间的解法，依据就是回文串一定有一个中心，从中心往两边扩

def solution(s: str) -> str:
    if not s:
        return ""

    start = 0
    end = 0

    def expand(left: int, right: int) -> tuple[int, int]:
        while left >= 0 and right < len(s) and s[left] == s[right]:
            left -= 1
            right += 1
        return left + 1, right - 1

    for i in range(len(s)):
        # 以一个字符为中心，处理奇数长度回文
        l1, r1 = expand(i, i)
        # 以两个字符中间为中心，处理偶数长度回文
        l2, r2 = expand(i, i + 1)

        if r1 - l1 > end - start:
            start, end = l1, r1
        if r2 - l2 > end - start:
            start, end = l2, r2

    return s[start:end + 1]


if __name__ == "__main__":
    s = input().strip()
    print(solution(s))

最长公共子序列

1. 题面

1143. 最长公共子序列

难度：中等

给定两个字符串 text1 和 text2，返回这两个字符串的最长 公共子序列 的长度。如果不存在 公共子序列 ，返回 0 。

一个字符串的 子序列 是指这样一个新的字符串：它是由原字符串在不改变字符的相对顺序的情况下删除某些字符（也可以不删除任何字符）后组成的新字符串。

例如，"ace" 是 "abcde" 的子序列，但 "aec" 不是 "abcde" 的子序列。

两个字符串的 公共子序列 是这两个字符串所共同拥有的子序列。

示例 1：

输入：text1 = "abcde", text2 = "ace" 
输出：3  
解释：最长公共子序列是 "ace" ，它的长度为 3 。

示例 2：

输入：text1 = "abc", text2 = "abc"
输出：3
解释：最长公共子序列是 "abc" ，它的长度为 3 。

示例 3：

输入：text1 = "abc", text2 = "def"
输出：0
解释：两个字符串没有公共子序列，返回 0 。

提示：

1 <= text1.length, text2.length <= 1000
text1 和 text2 仅由小写英文字符组成。

2. 题解

# 好难但是经典，dp[i][j] 表示 text1 前 i 个字符 和 text2 前 j 个字符 的最长公共子序列长度。

def solution(text1: str, text2: str) -> int:
    m, n = len(text1),len(text2)
    dp = [[0] * (n+1) for _ in range(m+1)]
    for i in range(1,m+1):
        for j in range(1,n+1):
            # Case1、字母相同，直接加到公共子序列
            if text1[i-1] == text2[j-1]:
                dp[i][j] = dp[i-1][j-1] + 1
            else:
                # 如果不相等，看看谁前进一格能让dp更大，要么扔掉 text1 这个字符，看 dp[i-1][j]；要么扔掉 text2 这个字符，看 dp[i][j-1]
                dp[i][j] = max(dp[i-1][j],dp[i][j-1])
    return dp[m][n]

if __name__ == "__main__":
    text1 = input().strip()
    text2 = input().strip()
    print(solution(text1,text2))

编辑距离

1. 题面

72. 编辑距离

难度：中等

给你两个单词 word1 和 word2， 请返回将 word1 转换成 word2 所使用的最少操作数 。

你可以对一个单词进行如下三种操作：

插入一个字符
删除一个字符
替换一个字符

示例 1：

输入：word1 = "horse", word2 = "ros"
输出：3
解释：
horse -> rorse (将 'h' 替换为 'r')
rorse -> rose (删除 'r')
rose -> ros (删除 'e')

示例 2：

输入：word1 = "intention", word2 = "execution"
输出：5
解释：
intention -> inention (删除 't')
inention -> enention (将 'i' 替换为 'e')
enention -> exention (将 'n' 替换为 'x')
exention -> exection (将 'n' 替换为 'c')
exection -> execution (插入 'u')

提示：

0 <= word1.length, word2.length <= 500
word1 和 word2 由小写英文字母组成

2. 题解

# 又是需要自行转化为dp的问题，我们要活用dp让目前只要看当前i、j位，然后遍历完成。

def solution(word1: str, word2: str) -> int:
    m, n = len(word1), len(word2)
    # dp[i][j] 代表 word1 中前 i 个字符，变换到 word2 中前 j 个字符，最短需要操作的次数
    dp = [[0] * (n+1) for _ in range(m+1)]
    # 基础情况
    for i in range(1,m+1):
        dp[i][0] = i
    for j in range(1,n+1):
        dp[0][j] = j

    for i in range(1,m+1):
        for j in range(1,n+1):
            # 当前位相等，不用加编辑距离
            if word1[i - 1] == word2[j - 1]:
                dp[i][j] = dp[i-1][j-1]
            else:
                # 下面三种情况，分别代表插入、删除、替换，取最小的操作数
                dp[i][j] = min(
                    dp[i-1][j] + 1,
                    dp[i][j-1] + 1,
                    dp[i-1][j-1] + 1
                )
    return dp[m][n]

if __name__ =="__main__":
    word1 = input().strip()
    word2 = input().strip()
    print(solution(word1,word2))

3. 反思

上面两题都是把两个字符串当做二维DP，天然就是“第一个串处理到 i，第二个串处理到 j”，算是比较经典

只出现一次的数字

1. 题面

136. 只出现一次的数字

难度：简单

给你一个非空整数数组 nums ，除了某个元素只出现一次以外，其余每个元素均出现两次。找出那个只出现了一次的元素。

你必须设计并实现线性时间复杂度的算法来解决此问题，且该算法只使用常量额外空间。

示例 1 ：

输入： nums = [2,2,1]

输出： 1

示例 2 ：

输入： nums = [4,1,2,1,2]

输出： 4

示例 3 ：

输入： nums = [1]

输出： 1

提示：

1 <= nums.length <= 3 * 10^4
-3 * 10^4 <= nums[i] <= 3 * 10^4
除了某个元素只出现一次以外，其余每个元素均出现两次。

2. 题解

# 如果我没记错的话，应该这题是使用位结论。自己异或自己是0，然后0异或所以东西都是不变的。所有两次的数字都湮灭了

def solution(nums:list)->int:
    result = 0
    for num in nums:
        result ^= num
    return result

if __name__ == "__main__":
    nums = list(map(int,input().strip().split(',')))
    print(solution(nums))

多数元素

1. 题面

169. 多数元素

难度：简单

给定一个大小为 n 的数组 nums ，返回其中的多数元素。多数元素是指在数组中出现次数大于 ⌊ n/2 ⌋ 的元素。

你可以假设数组是非空的，并且给定的数组总是存在多数元素。

示例 1：

输入：nums = [3,2,3]
输出：3

示例 2：

输入：nums = [2,2,1,1,1,2,2]
输出：2

提示：

n == nums.length
1 <= n <= 5 * 10^4
-10^9 <= nums[i] <= 10^9
输入保证数组中一定有一个多数元素。

进阶： 尝试设计时间复杂度为 O(n)、空间复杂度为 O(1) 的算法解决此问题。

2. 题解

# 其实这题用python的Counter计数再查找就是打败100%了，但是貌似希望我们使用的是摩尔投票法来求多数元素

import ast


def solution(nums: list[int]) -> int:
    candidate = None
    count = 0

    for num in nums:
        if count == 0:
            candidate = num
            count = 1
        elif num == candidate:
            count += 1
        else:
            count -= 1

    return candidate


if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    print(solution(nums))

3. 反思

这题的幽默之处在于你用Counter硬记数反而时间还更快了。。这就是底层优化的力量么

颜色分类

1. 题面

75. 颜色分类

难度：中等

给定一个包含红色、白色和蓝色、共 n 个元素的数组 nums ，原地对它们进行排序，使得相同颜色的元素相邻，并按照红色、白色、蓝色顺序排列。

我们使用整数 0、 1 和 2 分别表示红色、白色和蓝色。

必须在不使用库内置的 sort 函数的情况下解决这个问题。

示例 1：

输入：nums = [2,0,2,1,1,0]
输出：[0,0,1,1,2,2]

示例 2：

输入：nums = [2,0,1]
输出：[0,1,2]

提示：

n == nums.length
1 <= n <= 300
nums[i] 为 0、1 或 2

进阶：

你能想出一个仅使用常数空间的一趟扫描算法吗？

2. 题解

# 这题本质上，就是直接排序呗，不过不让用sort，那就插入排序也行，或者其他排序。
# 但是这一题其实没必要真的排序，只需要分区，这是经典的三指针/荷兰国旗问题。
import ast


def solution(nums: list[int]) -> list[int]:
    low = 0
    mid = 0
    high = len(nums) - 1

    # mid扫描未知区域，为0和low区换，为2和high区换
    while mid <= high:
        if nums[mid] == 0:
            nums[low], nums[mid] = nums[mid], nums[low]
            low += 1
            mid += 1
        elif nums[mid] == 1:
            mid += 1
        else:  # nums[mid] == 2
            nums[mid], nums[high] = nums[high], nums[mid]
            high -= 1

    return nums


if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    print(solution(nums))

下一个排列

1. 题面

31. 下一个排列

难度：中等

整数数组的一个排列就是将其所有成员以序列或线性顺序排列。

例如，arr = [1,2,3] ，以下这些都可以视作 arr 的排列：[1,2,3]、[1,3,2]、[3,1,2]、[2,3,1] 。

整数数组的 下一个排列 是指其整数的下一个字典序更大的排列。更正式地，如果数组的所有排列根据其字典顺序从小到大排列在一个容器中，那么数组的 下一个排列 就是在这个有序容器中排在它后面的那个排列。如果不存在下一个更大的排列，那么这个数组必须重排为字典序最小的排列（即，其元素按升序排列）。

例如，arr = [1,2,3] 的下一个排列是 [1,3,2] 。
类似地，arr = [2,3,1] 的下一个排列是 [3,1,2] 。
而 arr = [3,2,1] 的下一个排列是 [1,2,3] ，因为 [3,2,1] 不存在一个字典序更大的排列。

给你一个整数数组 nums ，找出 nums 的下一个排列。

必须原地修改，只允许使用额外常数空间。

示例 1：

输入：nums = [1,2,3]
输出：[1,3,2]

示例 2：

输入：nums = [3,2,1]
输出：[1,2,3]

示例 3：

输入：nums = [1,1,5]
输出：[1,5,1]

提示：

1 <= nums.length <= 100
0 <= nums[i] <= 100

2. 题解

# 这一题是找刚好能让排列变大一点的下一个序列
import ast


def solution(nums: list[int]) -> list[int]:
    n = len(nums)

    # 1. 从右往左找第一个下降的位置 i
    i = n - 2
    while i >= 0 and nums[i] >= nums[i + 1]:
        i -= 1

    # 2. 如果找到了，从右往左找第一个比 nums[i] 大的数 j，交换
    if i >= 0:
        j = n - 1
        while nums[j] <= nums[i]:
            j -= 1
        nums[i], nums[j] = nums[j], nums[i]

    # 3. 把 i+1 后面的部分反转，变成最小升序
    left, right = i + 1, n - 1
    while left < right:
        nums[left], nums[right] = nums[right], nums[left]
        left += 1
        right -= 1

    return nums


if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    print(solution(nums))

3. 反思

通常叫下一个排列算法，还是直接看板子理解意思即可。

寻找重复数

1. 题面

287. 寻找重复数

难度：中等

给定一个包含 n + 1 个整数的数组 nums ，其数字都在 [1, n] 范围内（包括 1 和 n），可知至少存在一个重复的整数。

假设 nums 只有 一个重复的整数 ，返回 这个重复的数 。

你设计的解决方案必须 不修改 数组 nums 且只用常量级 O(1) 的额外空间。

示例 1：

输入：nums = [1,3,4,2,2]
输出：2

示例 2：

输入：nums = [3,1,3,4,2]
输出：3

示例 3 :

输入：nums = [3,3,3,3,3]
输出：3

提示：

1 <= n <= 10^5
nums.length == n + 1
1 <= nums[i] <= n
nums 中 只有一个整数 出现 两次或多次 ，其余整数均只出现一次

进阶：

如何证明 nums 中至少存在一个重复的数字?
你可以设计一个线性级时间复杂度 O(n) 的解决方案吗？

2. 题解

# 这题的技巧是，用数组映射成链表，nums[i]就是i指向的下一个，所以就变成了链表判环问题了。

import ast


def solution(nums: list[int]) -> int:
    slow = nums[0]
    fast = nums[0]

    # 第一步：快慢指针相遇
    while True:
        slow = nums[slow]
        fast = nums[nums[fast]]
        if slow == fast:
            break

    # 第二步：从起点和相遇点同时走，环入口就是重复数
    slow = nums[0]
    while slow != fast:
        slow = nums[slow]
        fast = nums[fast]

    return slow


if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    print(solution(nums))

FastAPI 验证与运行：Testing、CLI、Uvicorn 与 Workers

Tue, 24 Mar 2026 00:00:00 GMT

如果前面的内容是在搭接口本身，这一篇就是在补“怎么确认它是对的，以及怎么把它跑起来”。

1. `TestClient`：为什么测试可以写成普通 `def`

官方测试页给的最小例子非常清楚：

from fastapi import FastAPI
from fastapi.testclient import TestClient

app = FastAPI()


@app.get("/")
async def read_main():
    return {"msg": "Hello World"}


client = TestClient(app)


def test_read_main():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"msg": "Hello World"}

官方特别提醒了两点：

测试函数可以是普通 def
client.get() 也是普通调用，不需要 await

这让你可以直接用 pytest，不会一上来就卡在异步测试细节里。
来源：Testing 官方页 https://fastapi.tiangolo.com/zh/tutorial/testing/

2. 测试文件通常怎么放

官方示例里常见的是：

app/
├── __init__.py
├── main.py
└── test_main.py

这样 test_main.py 可以直接相对导入：

from .main import app

如果项目结构更大，也可以把测试单独放到 tests/ 目录，但第一次入门时，先把测试贴着应用写更容易理解。

3. `fastapi dev` 是开发模式

开发时，最顺手的仍然是：

fastapi dev

或者：

fastapi dev main.py

如果没传路径，CLI 会尝试自动找应用；如果传了路径，它会按路径推断应用对象。官方也说明了，长期来看更推荐在 pyproject.toml 里配置 entrypoint，这样工具链更稳定。
来源：First Steps / FastAPI CLI 官方页
https://fastapi.tiangolo.com/zh/tutorial/first-steps/
https://fastapi.tiangolo.com/zh/fastapi-cli/

4. `fastapi run` 是生产模式入口

官方 CLI 页明确写到：

fastapi dev：开发模式
fastapi run：生产模式

而且 FastAPI CLI 内部实际就是基于 Uvicorn 来跑应用。
来源：FastAPI CLI 官方页 https://fastapi.tiangolo.com/zh/fastapi-cli/

也就是说，FastAPI 没有发明一套独立服务器，而是在 CLI 层帮你把 Uvicorn 这类 ASGI 服务器包起来了。

5. 手动运行为什么还是要懂 `uvicorn main:app`

官方手动运行页给出的最核心命令是：

uvicorn main:app --host 0.0.0.0 --port 80

这个字符串一定要能看懂：

main：main.py
app：文件里的 app = FastAPI() 对象

它等价于：

from main import app

所以 uvicorn main:app 的本质，就是告诉 ASGI 服务器“去哪里导入应用”。
来源：手动运行服务器官方页 https://fastapi.tiangolo.com/zh/deployment/manually/

6. `fastapi dev`、`fastapi run`、`uvicorn main:app` 应该怎么选

可以直接按场景分：

本地开发：fastapi dev
想直接操作底层服务器：uvicorn main:app
更接近生产的 FastAPI CLI 启动：fastapi run

如果只是平时写代码，fastapi dev 最省心。
如果要真正理解部署、容器和 server process，uvicorn main:app 一定要看懂。

7. `--reload` 的位置

--reload 只适合开发阶段。

uvicorn main:app --reload

它的意义是：

文件变化后自动重启

它不是生产特性，而是开发便利。

8. 为什么还会在代码里写 `uvicorn.run(app, ...)`

你本地 21.md 里记的是这种方式：

import uvicorn
from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def root():
    return {"hello world": "ok"}


if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

这类写法最适合：

本地点一下文件直接调试
临时验证逻辑
不想切回终端敲命令

但它更像“调试入口”，不是长期部署约定。

9. Workers：多进程是什么时候开始重要

官方 Workers 页给出的典型命令是：

uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4

来源：Workers 官方页 https://fastapi.tiangolo.com/zh/deployment/server-workers/

这里的意思是：

启动多个 worker 进程
用多个进程共同处理请求

这通常和生产部署有关，而不是入门开发阶段就要立刻开。

第一次学时更值得先记住的是：

单进程开发跑通
理解 CLI 和 Uvicorn 的关系
再去看 workers、多进程、容器和反向代理

10. 从本地到部署，这一层真正连起来的是什么

这一篇其实是在把几条原本散落的线收起来：

怎么测试
怎么调试
怎么启动
怎么理解 CLI
怎么理解 Uvicorn
怎么理解 workers

当这些线连起来之后，FastAPI 才算真的从“写几个接口”走向“能把服务稳稳跑起来”。

LangChain 核心组件 03：Tools

Tue, 24 Mar 2026 00:00:00 GMT

走到这一篇时，前面的模型和消息已经足够支撑“理解输入输出”；现在开始补上行动能力。Tools 是 LangChain 从“会说”走向“会做”的第一步。

1. 介绍

工具能够拓展智能体的能力 —— 让它们获取实时数据、执行代码、查询外部数据库，并在现实场景中采取行动。

在底层实现中，工具是具备明确定义输入与输出的可调用函数，这些函数会被传递给对话模型。模型会根据对话上下文判断何时调用工具，以及提供哪些输入参数。

2. 创建工具

(1) 基础工具定义

创建工具最简单的方式是使用@tool装饰器。默认情况下，函数的文档字符串会成为工具的描述，帮助模型理解何时使用该工具:

from langchain.tools import tool

@tool
def search_database(query: str, limit: int = 10) -> str:
    """Search the customer database for records matching the query.

    Args:
        query: Search terms to look for
        limit: Maximum number of results to return
    """
    return f"Found {limit} results for '{query}'"

注意类型提示是必需的，因为它们定义了工具的输入架构。文档字符串应内容详实且简洁，以帮助模型理解工具的用途。

(2) 自定义工具属性

我们可以给工具添加一个别名来Override，比如：

@tool("web_search")  # Custom name
def search(query: str) -> str:
    """Search the web for information."""
    return f"Results for: {query}"

print(search.name)  # web_search

或者自定义工具的描述：

@tool("calculator", description="Performs arithmetic calculations. Use this for any math problems.")
def calc(expression: str) -> str:
    """Evaluate mathematical expressions."""
    return str(eval(expression))

或者再高级一点，用schema定义，同样可以用pydantic、json schema等，这里用pydantic实例：

from pydantic import BaseModel, Field
from typing import Literal

class WeatherInput(BaseModel):
    """Input for weather queries."""
    location: str = Field(description="City name or coordinates")
    units: Literal["celsius", "fahrenheit"] = Field(
        default="celsius",
        description="Temperature unit preference"
    )
    include_forecast: bool = Field(
        default=False,
        description="Include 5-day forecast"
    )

@tool(args_schema=WeatherInput)
def get_weather(location: str, units: str = "celsius", include_forecast: bool = False) -> str:
    """Get current weather and optional forecast."""
    temp = 22 if units == "celsius" else 72
    result = f"Current weather in {location}: {temp} degrees {units[0].upper()}"
    if include_forecast:
        result += "\nNext 5 days: Sunny"
    return result

不过注意有两个保留名称，不能用作工具参数，分别是config和runtime。config保留用于内部向工具传递RunnableConfig；runtime保留用于ToolRuntime参数（访问状态、上下文、存储）。

3. 访问上下文

当工具能够访问运行时信息（如对话历史、用户数据和持久化内存）时，其功能最为强大。本节将介绍如何在工具内部访问和更新这些信息。

工具可通过ToolRuntime参数访问运行时信息，该参数提供以下能力：

组件	描述	用例
State	短期内存 —— 当前对话中存在的可变数据（消息、计数器、自定义字段）	访问对话历史，追踪工具调用次数
Context	调用时传入的不可变配置（用户 ID、会话信息）	根据用户身份个性化响应内容
Store	长期内存 —— 跨对话持久保存的数据	保存用户偏好设置，维护知识库
Stream Writer	在工具执行过程中发送实时更新	展示耗时操作的执行进度
Config	执行所用的 RunnableConfig	访问回调函数、标签和元数据
Tool Call ID	当前工具调用的唯一标识符	关联日志与模型调用中的工具调用记录

%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontFamily": "monospace"
  }
}}%%
graph LR
    subgraph Tool_Runtime_Context
        A[Tool Call] --> B[ToolRuntime]
        B --> C[State Access]
        B --> D[Context Access]
        B --> E[Store Access]
        B --> F[Stream Writer]
    end

    subgraph Available_Resources
        C --> G[Messages]
        C --> H[Custom State]
        D --> I[User ID]
        D --> J[Session Info]
        E --> K[Long-term Memory]
        E --> L[User Preferences]
    end

    subgraph Enhanced_Tool_Capabilities
        M[Context-Aware Tools]
        N[Stateful Tools]
        O[Memory-Enabled Tools]
        P[Streaming Tools]
    end

    G --> M
    H --> N
    I --> M
    J --> M
    K --> O
    L --> O
    F --> P

    classDef trigger fill:#DCFCE7,stroke:#16A34A,stroke-width:2px,color:#14532D;
    classDef process fill:#DBEAFE,stroke:#2563EB,stroke-width:2px,color:#1E3A8A;
    classDef output fill:#F3E8FF,stroke:#9333EA,stroke-width:2px,color:#581C87;
    classDef neutral fill:#F3F4F6,stroke:#9CA3AF,stroke-width:2px,color:#374151;

    class A trigger;
    class B,C,D,E,F process;
    class G,H,I,J,K,L neutral;
    class M,N,O,P output;

这张图说明了 ToolRuntime 在 LangChain 工具体系中的位置。

一次工具调用发生时，工具拿到的不只是普通参数，还可以通过 ToolRuntime 访问运行时环境中的多种资源，包括当前会话状态（State）、调用上下文（Context）、长期存储（Store）以及流式输出能力（Stream Writer）。

正因为工具可以访问这些额外信息，所以它不再只是一个简单函数，而可以演变为：

能感知用户和会话信息的上下文工具；
能依赖当前对话状态工作的有状态工具；
能结合长期记忆的记忆增强工具；
能边执行边输出进度的流式工具。

换句话说，ToolRuntime 让工具从“静态函数”升级成了“运行时感知组件”。

(1) State Access (短时记忆)

Tools可通过runtime.state访问当前对话状态：

from langchain.tools import tool, ToolRuntime
from langchain.messages import HumanMessage

@tool
def get_last_user_message(runtime: ToolRuntime) -> str:
    """Get the most recent message from the user."""
    messages = runtime.state["messages"]

    # Find the last human message
    for message in reversed(messages):
        if isinstance(message, HumanMessage):
            return message.content

    return "No user messages found"

# Access custom state fields
@tool
def get_user_preference(
    pref_name: str,
    runtime: ToolRuntime
) -> str:
    """Get a user preference value."""
    preferences = runtime.state.get("user_preferences", {})
    return preferences.get(pref_name, "Not set")

不仅如此，还可以用Command更新智能体的状态：

from langgraph.types import Command
from langchain.tools import tool

@tool
def set_user_name(new_name: str) -> Command:
    """Set the user's name in the conversation state."""
    return Command(update={"user_name": new_name})

(2) Context Access

上下文提供在调用时传递的不可变配置数据，可用于用户ID、会话详情或对话过程中不应更改的应用特定设置。通过runtime.context访问上下文：

from dataclasses import dataclass
from langchain_openai import ChatOpenAI
from langchain.agents import create_agent
from langchain.tools import tool, ToolRuntime


USER_DATABASE = {
    "user123": {
        "name": "Alice Johnson",
        "account_type": "Premium",
        "balance": 5000,
        "email": "alice@example.com"
    },
    "user456": {
        "name": "Bob Smith",
        "account_type": "Standard",
        "balance": 1200,
        "email": "bob@example.com"
    }
}

@dataclass
class UserContext:
    user_id: str

@tool
def get_account_info(runtime: ToolRuntime[UserContext]) -> str:
    """Get the current user's account information."""
    user_id = runtime.context.user_id

    if user_id in USER_DATABASE:
        user = USER_DATABASE[user_id]
        return f"Account holder: {user['name']}\nType: {user['account_type']}\nBalance: ${user['balance']}"
    return "User not found"

model = ChatOpenAI(model="gpt-4.1")
agent = create_agent(
    model,
    tools=[get_account_info],
    context_schema=UserContext,
    system_prompt="You are a financial assistant."
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What's my current balance?"}]},
    context=UserContext(user_id="user123")
)

(3) Store Access (长时记忆)

BaseStore提供可跨对话持久保存的存储功能。与状态（短期记忆）不同，存储中保存的数据在后续会话中依然可用。

通过runtime.store访问存储。存储采用命名空间或者key的模式来组织数据。

from typing import Any
from langgraph.store.memory import InMemoryStore
from langchain.agents import create_agent
from langchain.tools import tool, ToolRuntime
from langchain_openai import ChatOpenAI

# Access memory
@tool
def get_user_info(user_id: str, runtime: ToolRuntime) -> str:
    """Look up user info."""
    store = runtime.store
    user_info = store.get(("users",), user_id)
    return str(user_info.value) if user_info else "Unknown user"

# Update memory
@tool
def save_user_info(user_id: str, user_info: dict[str, Any], runtime: ToolRuntime) -> str:
    """Save user info."""
    store = runtime.store
    store.put(("users",), user_id, user_info)
    return "Successfully saved user info."

model = ChatOpenAI(model="gpt-4.1")

store = InMemoryStore()
agent = create_agent(
    model,
    tools=[get_user_info, save_user_info],
    store=store
)

# First session: save user info
agent.invoke({
    "messages": [{"role": "user", "content": "Save the following user: userid: abc123, name: Foo, age: 25, email: foo@langchain.dev"}]
})

# Second session: get user info
agent.invoke({
    "messages": [{"role": "user", "content": "Get user info for user with id 'abc123'"}]
})
# Here is the user info for user with ID "abc123":
# - Name: Foo
# - Age: 25
# - Email: foo@langchain.dev

(4) Stream Writer

在执行过程中流式传输来自工具的实时更新。这对于在长时间运行的操作期间向用户提供进度反馈非常有用。

使用runtime.stream_writer来发送自定义更新：

from langchain.tools import tool, ToolRuntime

@tool
def get_weather(city: str, runtime: ToolRuntime) -> str:
    """Get weather for a given city."""
    writer = runtime.stream_writer

    # Stream custom updates as the tool executes
    writer(f"Looking up data for city: {city}")
    writer(f"Acquired data for city: {city}")

    return f"It's always sunny in {city}!"

4. ToolNode

ToolNode是一个预构建节点，用于在 LangGraph 工作流中执行工具。它会自动处理工具并行执行、错误处理和状态注入。这一块应该会在LangGraph中应用比较多。

这个部分主要是用于精细控制工具执行模式的自定义工作流，不然可以直接使用create_agent。换句话说，它是支撑智能体工具执行的基础组件。

由于这部分主要是LangGraph的内容，所以我将暂时跳过。

5. Tools的返回值

自定义工具@tool后，可以为工具选择不同的返回值：

返回string，用于生成人类可读的结果。
返回object，用于生成模型需要解析的结构化结果。
返回Command（可附带消息），用于需要写入状态的场景。

(1) String返回值

from langchain.tools import tool


@tool
def get_weather(city: str) -> str:
    """Get weather for a city."""
    return f"It is currently sunny in {city}."

返回值会被转换为ToolMessage。
模型会读取该文本并决定下一步操作。
除非模型或其他工具后续修改，否则不会更改任何智能体状态字段。

如果结果是人类可阅读的样子，应该选择此种返回。

(2) Object返回值

from langchain.tools import tool


@tool
def get_weather_data(city: str) -> dict:
    """Get structured weather data for a city."""
    return {
        "city": city,
        "temperature_c": 22,
        "conditions": "sunny",
    }

该对象会被序列化后作为工具输出返回。
模型可读取特定字段并基于这些字段进行推理。
与字符串返回值类似，此操作不会直接更新图状态。

当下游推理可从显式字段而非自由格式文本中获益时，使用此方式。

(3) Command返回值

from langchain.messages import ToolMessage
from langchain.tools import ToolRuntime, tool
from langgraph.types import Command


@tool
def set_language(language: str, runtime: ToolRuntime) -> Command:
    """Set the preferred response language."""
    return Command(
        update={
            "preferred_language": language,
            "messages": [
                ToolMessage(
                    content=f"Language set to {language}.",
                    tool_call_id=runtime.tool_call_id,
                )
            ],
        }
    )

该命令通过update更新状态。
更新后的状态可在同一次运行的后续步骤中使用。
对于可能被并行工具调用更新的字段，请使用 reducer。

当工具不仅返回数据，还会修改智能体状态时使用此方法。

6. Prebuilt tools

LangChain 提供了大量适用于网络搜索、代码解析、数据库访问等常见任务的预制工具与工具包。这些开箱即用的工具可直接集成到你的Agent中，无需编写自定义代码。详见这里。

7. Server-side tool use

部分聊天模型具备由模型提供商在服务器端运行的内置工具。这些工具包括网络搜索、代码解释器等功能，你无需自行定义或托管工具逻辑。详见这里和这里这里。

Milvus 多模态实践：图文嵌入到检索闭环

Tue, 24 Mar 2026 00:00:00 GMT

这一篇不再停留在概念层，而是把前面的知识点真正串起来，做一条从图文编码到 Milvus 检索的完整链路。

RAG - Milvus多模态实践

1. 初始化与工具定义

首先导入所有必需的库，定义好模型路径、数据目录等常量。为了代码的整洁和复用，将 Visualized-BGE 模型的加载和编码逻辑封装在一个 Encoder 类中，并定义了一个 visualize_results 函数用于后续的结果可视化。

import os
from tqdm import tqdm
from glob import glob
import torch
from visual_bge.visual_bge.modeling import Visualized_BGE
from pymilvus import MilvusClient, FieldSchema, CollectionSchema, DataType
import numpy as np
import cv2
from PIL import Image

# 1. 初始化设置
MODEL_NAME = "BAAI/bge-base-en-v1.5"
MODEL_PATH = "../../models/bge/Visualized_base_en_v1.5.pth"
DATA_DIR = "../../data/C3"
COLLECTION_NAME = "multimodal_demo"
MILVUS_URI = "http://localhost:19530"

# 2. 定义工具 (编码器和可视化函数)
class Encoder:
    """编码器类，用于将图像和文本编码为向量。"""
    def __init__(self, model_name: str, model_path: str):
        self.model = Visualized_BGE(model_name_bge=model_name, model_weight=model_path)
        self.model.eval()

    def encode_query(self, image_path: str, text: str) -> list[float]:
        with torch.no_grad():
            query_emb = self.model.encode(image=image_path, text=text)
        return query_emb.tolist()[0]

    def encode_image(self, image_path: str) -> list[float]:
        with torch.no_grad():
            query_emb = self.model.encode(image=image_path)
        return query_emb.tolist()[0]

def visualize_results(query_image_path: str, retrieved_images: list, img_height: int = 300, img_width: int = 300, row_count: int = 3) -> np.ndarray:
    """从检索到的图像列表创建一个全景图用于可视化。"""
    panoramic_width = img_width * row_count
    panoramic_height = img_height * row_count
    panoramic_image = np.full((panoramic_height, panoramic_width, 3), 255, dtype=np.uint8)
    query_display_area = np.full((panoramic_height, img_width, 3), 255, dtype=np.uint8)

    # 处理查询图像
    query_pil = Image.open(query_image_path).convert("RGB")
    query_cv = np.array(query_pil)[:, :, ::-1]
    resized_query = cv2.resize(query_cv, (img_width, img_height))
    bordered_query = cv2.copyMakeBorder(resized_query, 10, 10, 10, 10, cv2.BORDER_CONSTANT, value=(255, 0, 0))
    query_display_area[img_height * (row_count - 1):, :] = cv2.resize(bordered_query, (img_width, img_height))
    cv2.putText(query_display_area, "Query", (10, panoramic_height - 20), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 0, 0), 2)

    # 处理检索到的图像
    for i, img_path in enumerate(retrieved_images):
        row, col = i // row_count, i % row_count
        start_row, start_col = row * img_height, col * img_width
        
        retrieved_pil = Image.open(img_path).convert("RGB")
        retrieved_cv = np.array(retrieved_pil)[:, :, ::-1]
        resized_retrieved = cv2.resize(retrieved_cv, (img_width - 4, img_height - 4))
        bordered_retrieved = cv2.copyMakeBorder(resized_retrieved, 2, 2, 2, 2, cv2.BORDER_CONSTANT, value=(0, 0, 0))
        panoramic_image[start_row:start_row + img_height, start_col:start_col + img_width] = bordered_retrieved
        
        # 添加索引号
        cv2.putText(panoramic_image, str(i), (start_col + 10, start_row + 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 0, 255), 2)

    return np.hstack([query_display_area, panoramic_image])

初看代码两眼一黑，现在我们来拆解。

开头导包的环节，有几个还不太熟悉的，简单看看。tqdm是一个快速可拓展的python进度条，glob是用来查看符合特定规则的目录和文件将搜索到的结果返回到一个列表。

导入模型的环节，作者有一个带setup.py的路径all-in-rag/code/C3/visual_bge，下面有一个visual_bge文件夹，里面还有modeling.py，作者就是从这里导入了这个Visualized_BGE类。这是作者对将几部分模型能力拼出来的，比如文本部分用Hugging Face 的 AutoConfig / AutoModel 加载 BGE 底座；视觉部分用 create_eva_vision_and_transforms(...) 引入 EVA-CLIP 视觉编码器；对齐层作者自己加了一个 visual_proj = nn.Linear(...)，把视觉特征映射到和 BGE 一致的语义空间；权重加载通过 self.load_state_dict(torch.load(...)) 把训练好的 Visualized-BGE 权重灌进去。

然后就是pymilvus提供的几个包，和处理图像用的几个包。

常量配置部分，做了一些全局配置，包括模型名、目录、Collection名、Milvus地址。

Encoder类封装了关键的encode_image()和encode_query()方法，用于创建模型对象进行推理，将输出的二位张量取出需要的向量，包含纯图片和图+文，从而得到嵌入向量。

visualize_results则是可视化结果。

2. 创建Colletion

这是与 Milvus 交互的开始。首先初始化 Milvus 客户端，然后定义 Collection 的 Schema，它规定了集合的数据结构。

# 3. 初始化客户端
print("--> 正在初始化编码器和Milvus客户端...")
encoder = Encoder(MODEL_NAME, MODEL_PATH)
milvus_client = MilvusClient(uri=MILVUS_URI)

# 4. 创建 Milvus Collection
print(f"\n--> 正在创建 Collection '{COLLECTION_NAME}'")
if milvus_client.has_collection(COLLECTION_NAME):
    milvus_client.drop_collection(COLLECTION_NAME)
    print(f"已删除已存在的 Collection: '{COLLECTION_NAME}'")

image_list = glob(os.path.join(DATA_DIR, "dragon", "*.png"))
if not image_list:
    raise FileNotFoundError(f"在 {DATA_DIR}/dragon/ 中未找到任何 .png 图像。")
dim = len(encoder.encode_image(image_list[0]))

fields = [
    FieldSchema(name="id", dtype=DataType.INT64, is_primary=True, auto_id=True),
    FieldSchema(name="vector", dtype=DataType.FLOAT_VECTOR, dim=dim),
    FieldSchema(name="image_path", dtype=DataType.VARCHAR, max_length=512),
]

# 创建集合 Schema
schema = CollectionSchema(fields, description="多模态图文检索")
print("Schema 结构:")
print(schema)

# 创建集合
milvus_client.create_collection(collection_name=COLLECTION_NAME, schema=schema)
print(f"成功创建 Collection: '{COLLECTION_NAME}'")
print("Collection 结构:")
print(milvus_client.describe_collection(collection_name=COLLECTION_NAME))

这里的代码比较直白，但是涉及到和Milvus的交互，注意几个方法。首先用MilvusClient类创建实例，然后做了一个预先处理：如果有同名Collection，先drop掉（这是为了每次从干净状态开始，否则会有旧数据残留的可能，正式生产环境一般不会这么做，这么做事为了反复运行demo）。

紧接着，用glob来提取png成列表，通过 encoder.encode_image(image_list[0]) 对第一张图片进行编码，并用 len(...) 获取向量维度。这是因为 Milvus 在创建 FLOAT_VECTOR 字段时，必须提前知道向量维度。

接着，我们去定义一下需要用的元素的类型作为schema，传入create_collection方法构建collection。本次定义了三个字段，作为主键的id，INT64；图像对应的向量类型，类型为FLOAT_VECTOR；然后是图片路径，类型VERCHAR。

然后，我们传入Schema去构建了Collection。

输出Collections和Schema的结构类似于（此处是作者示例）：

--> 正在创建 Collection 'multimodal_demo'

Schema 结构:
{
    'auto_id': True, 
    'description': '多模态图文检索', 
    'fields': [
        {'name': 'id', 'description': '', 'type': <DataType.INT64: 5>, 'is_primary': True, 'auto_id': True}, 
        {'name': 'vector', 'description': '', 'type': <DataType.FLOAT_VECTOR: 101>, 'params': {'dim': 768}}, 
        {'name': 'image_path', 'description': '', 'type': <DataType.VARCHAR: 21>, 'params': {'max_length': 512}}
    ], 
    'enable_dynamic_field': False
}

成功创建 Collection: 'multimodal_demo'

Collection 结构:
{
    'collection_name': 'multimodal_demo', 
    'auto_id': True, 
    'num_shards': 1, 
    'description': '多模态图文检索', 
    'fields': [
        {'field_id': 100, 'name': 'id', 'description': '', 'type': <DataType.INT64: 5>, 'params': {}, 'auto_id': True, 'is_primary': True}, 
        {'field_id': 101, 'name': 'vector', 'description': '', 'type': <DataType.FLOAT_VECTOR: 101>, 'params': {'dim': 768}}, 
        {'field_id': 102, 'name': 'image_path', 'description': '', 'type': <DataType.VARCHAR: 21>, 'params': {'max_length': 512}}
    ], 
    'functions': [], 
    'aliases': [], 
    'collection_id': 459243798405253751, 
    'consistency_level': 2, 
    'properties': {}, 
    'num_partitions': 1, 
    'enable_dynamic_field': False, 
    'created_timestamp': 459249546649403396, 
    'update_timestamp': 459249546649403396
}

3. 准备并插入数据

创建好 Collection 后，需要将数据填充进去。通过遍历指定目录下的所有图片，将它们逐一编码成向量，然后与图片路径一起组织成符合 Schema 结构的格式，最后批量插入到 Collection 中。

# 5. 准备并插入数据
print(f"\n--> 正在向 '{COLLECTION_NAME}' 插入数据")
data_to_insert = []
for image_path in tqdm(image_list, desc="生成图像嵌入"):
    vector = encoder.encode_image(image_path)
    data_to_insert.append({"vector": vector, "image_path": image_path})

if data_to_insert:
    result = milvus_client.insert(collection_name=COLLECTION_NAME, data=data_to_insert)
    print(f"成功插入 {result['insert_count']} 条数据。")

4. 创建索引

为了实现快速检索，需要为向量字段创建索引。这里选择 HNSW 索引，它在召回率和查询性能之间有着很好的平衡。创建索引后，必须调用 load_collection 将集合加载到内存中才能进行搜索。

# 6. 创建索引
print(f"\n--> 正在为 '{COLLECTION_NAME}' 创建索引")
index_params = milvus_client.prepare_index_params()
index_params.add_index(
    field_name="vector",
    index_type="HNSW",
    metric_type="COSINE",
    params={"M": 16, "efConstruction": 256}
)
milvus_client.create_index(collection_name=COLLECTION_NAME, index_params=index_params)
print("成功为向量字段创建 HNSW 索引。")
print("索引详情:")
print(milvus_client.describe_index(collection_name=COLLECTION_NAME, index_name="vector"))
milvus_client.load_collection(collection_name=COLLECTION_NAME)
print("已加载 Collection 到内存中。")

5. 执行多模态检索

# 7. 执行多模态检索
print(f"\n--> 正在 '{COLLECTION_NAME}' 中执行检索")
query_image_path = os.path.join(DATA_DIR, "dragon", "query.png")
query_text = "一条龙"
query_vector = encoder.encode_query(image_path=query_image_path, text=query_text)

search_results = milvus_client.search(
    collection_name=COLLECTION_NAME,
    data=[query_vector],
    output_fields=["image_path"],
    limit=5,
    search_params={"metric_type": "COSINE", "params": {"ef": 128}}
)[0]

retrieved_images = []
print("检索结果:")
for i, hit in enumerate(search_results):
    print(f"  Top {i+1}: ID={hit['id']}, 距离={hit['distance']:.4f}, 路径='{hit['entity']['image_path']}'")
    retrieved_images.append(hit['entity']['image_path'])

输出结果会类似：

--> 正在 'multimodal_demo' 中执行检索
检索结果:
  Top 1: ID=459243798403756667, 距离=0.9411, 路径='../../data/C3\dragon\dragon01.png'
  Top 2: ID=459243798403756668, 距离=0.5818, 路径='../../data/C3\dragon\dragon02.png'
  Top 3: ID=459243798403756671, 距离=0.5731, 路径='../../data/C3\dragon\dragon05.png'
  Top 4: ID=459243798403756670, 距离=0.4894, 路径='../../data/C3\dragon\dragon04.png'
  Top 5: ID=459243798403756669, 距离=0.4100, 路径='../../data/C3\dragon\dragon03.png'

6. 可视化与清理

最后，将检索到的图片路径用于可视化，生成一张直观的结果对比图。在完成所有操作后，应该释放 Milvus 中的资源，包括从内存中卸载 Collection 和删除整个 Collection。

# 8. 可视化与清理
print(f"\n--> 正在可视化结果并清理资源")
if not retrieved_images:
    print("没有检索到任何图像。")
else:
    panoramic_image = visualize_results(query_image_path, retrieved_images)
    combined_image_path = os.path.join(DATA_DIR, "search_result.png")
    cv2.imwrite(combined_image_path, panoramic_image)
    print(f"结果图像已保存到: {combined_image_path}")
    Image.open(combined_image_path).show()

milvus_client.release_collection(collection_name=COLLECTION_NAME)
print(f"已从内存中释放 Collection: '{COLLECTION_NAME}'")
milvus_client.drop_collection(COLLECTION_NAME)
print(f"已删除 Collection: '{COLLECTION_NAME}'")

7. 结果

过程日志如下：

(all-in-rag) ➜  C3 git:(main) ✗ python 04_multi_milvus.py
/opt/homebrew/anaconda3/envs/all-in-rag/lib/python3.12/site-packages/timm/models/layers/__init__.py:49: FutureWarning: Importing from timm.models.layers is deprecated, please import via timm.layers
  warnings.warn(f"Importing from {__name__} is deprecated, please import via timm.layers", FutureWarning)
--> 正在初始化编码器和Milvus客户端...
tokenizer_config.json: 100%|█| 366/366 [00:00<00:00, 624kB/s
vocab.txt: 232kB [00:00, 826kB/s] 
special_tokens_map.json: 100%|█| 125/125 [00:00<00:00, 163kB
tokenizer.json: 711kB [00:00, 2.91MB/s]

--> 正在创建 Collection 'multimodal_demo'
Schema 结构:
{'auto_id': True, 'description': '多模态图文检索', 'fields': [{'name': 'id', 'description': '', 'type': <DataType.INT64: 5>, 'is_primary': True, 'auto_id': True}, {'name': 'vector', 'description': '', 'type': <DataType.FLOAT_VECTOR: 101>, 'params': {'dim': 768}}, {'name': 'image_path', 'description': '', 'type': <DataType.VARCHAR: 21>, 'params': {'max_length': 512}}], 'enable_dynamic_field': False}
成功创建 Collection: 'multimodal_demo'
Collection 结构:
{'collection_name': 'multimodal_demo', 'auto_id': True, 'num_shards': 1, 'description': '多模态图文检索', 'fields': [{'field_id': 100, 'name': 'id', 'description': '', 'type': <DataType.INT64: 5>, 'params': {}, 'auto_id': True, 'is_primary': True}, {'field_id': 101, 'name': 'vector', 'description': '', 'type': <DataType.FLOAT_VECTOR: 101>, 'params': {'dim': 768}}, {'field_id': 102, 'name': 'image_path', 'description': '', 'type': <DataType.VARCHAR: 21>, 'params': {'max_length': 512}}], 'functions': [], 'aliases': [], 'collection_id': 465268713610543383, 'consistency_level': 2, 'properties': {}, 'num_partitions': 1, 'enable_dynamic_field': False, 'created_timestamp': 465268727841554436, 'update_timestamp': 465268727841554436}

--> 正在向 'multimodal_demo' 插入数据
生成图像嵌入: 100%|███████████| 7/7 [00:02<00:00,  2.42it/s]
成功插入 7 条数据。

--> 正在为 'multimodal_demo' 创建索引
成功为向量字段创建 HNSW 索引。
索引详情:
{'M': '16', 'efConstruction': '256', 'metric_type': 'COSINE', 'index_type': 'HNSW', 'field_name': 'vector', 'index_name': 'vector', 'total_rows': 0, 'indexed_rows': 0, 'pending_index_rows': 0, 'state': 'Finished'}
已加载 Collection 到内存中。

--> 正在 'multimodal_demo' 中执行检索
检索结果:
  Top 1: ID=465268713610543405, 距离=0.9466, 路径='/Users/owen/AI_learning/RAG/all-in-rag/data/C3/dragon/query.png'
  Top 2: ID=465268713610543410, 距离=0.7443, 路径='/Users/owen/AI_learning/RAG/all-in-rag/data/C3/dragon/dragon02.png'
  Top 3: ID=465268713610543407, 距离=0.6851, 路径='/Users/owen/AI_learning/RAG/all-in-rag/data/C3/dragon/dragon06.png'
  Top 4: ID=465268713610543408, 距离=0.6049, 路径='/Users/owen/AI_learning/RAG/all-in-rag/data/C3/dragon/dragon03.png'
  Top 5: ID=465268713610543404, 距离=0.5360, 路径='/Users/owen/AI_learning/RAG/all-in-rag/data/C3/dragon/dragon05.png'

--> 正在可视化结果并清理资源
结果图像已保存到: /Users/owen/AI_learning/RAG/all-in-rag/data/C3/search_result.png
已从内存中释放 Collection: 'multimodal_demo'
已删除 Collection: 'multimodal_demo'

可验证强化学习：RLVR 与 Tülu 3

Tue, 24 Mar 2026 00:00:00 GMT

在LLMs的快速发展中, 强化学习与可验证奖励作为一种创新的训练方法, 引起了广泛关注. RLVR通过使用可验证的、基于规则的奖励函数, 为模型提供明确的二元反馈, 从而优化其性能. 与传统的RLHF不同, RLVR避免了主观人类评估或复杂奖励模型的依赖, 使得训练过程更加透明高效. 并且这种方式特别适用于数学推理、代码生成等具有明确正确性标准的任务.

一. 起源论文精读

可验证奖励的强化学习(Reinforcement Learning with Verifiable Rewards, RLVR), 首次在Tülu3项目中提出, 论文Tülu 3: Pushing Frontiers in Open Language Model Post-Training, 现在我们来具体阅读和实操一下论文所说的东西.

本论文未来弥补开源和闭源post training之间的差距, 本文提出了Tülu3 -- 一系列开放的、最先进的后训练模型, 包括他们的全部相关数据、训练配方、代码、基础设设施和评估框架.

先来看使用了RLVF方法等Tülu3模型, 在三个尺度下(405B、70B、8B) 的性能比较, 涵盖了综合能力（Avg）、知识（MMLU）、数学（MATH, GSM8K）、代码（HumanEval）、指令遵循（IFEval）和安全性（Safety）等多个维度.

从上述表格可以看出:

超大模型对比方面, GPT-4o依然遥遥领先, 但Tülu3的RLVR表现强劲, 优于Llama3.1 405B Instruct而均分接近GPT-4o. 另外Deepseek V3在数学题和BigBenchHard上表现突出
大模型对比方面, Tülu3 70B综合第一, 而Qwen2.5 72B在MATH和HumanEval+上具有压倒性优势.
小模型方面, Qwen2.5 7B统治力最强, 大幅领先对手. 但是Tülu3 8B则在小学数学(GSM8K)、IFEval(指令微调)和Safety(安全性)上表现很好.
Tülu3 的后训练策略, 从SFT到DPO再到RLVR, 性能都有显著且稳定的提升.
RLVR实际上起到了修复逻辑功能的作用, 比如在SFT到DPO, MATH任务反而准确度降低了, 而采用RLVR之后产生了大幅反超. 另外在指令准确度和特定领域(小学数学)的上限也发生了提高 (我们可以认为, RLVR对“刷分”行为进行了一定程度的制裁, 在风格偏好调整好的情况下, 又把丢失的部分逻辑功能拿了回来.)

Tülu 3团队自己总结该架构的重要元素如下:

仔细调研了开源数据集, 分析其来源并进行了去噪, 同时进行策划了针对核心技能的合成提示, 以获取高质量的提示. 并发现了针对性的提示对提升核心技能具有显著的影响.
创造了一个多经验的SFT数据集, 通过构建专门针对的模型在评估套件中确定一个上限, 然后通过混合数据使通用模型去接近这一上限.
构建了一种同策略偏好数据集, 通过一种同策略数据整理流程, 来拓展偏好数据集生产规模. 具体而言是用Tülu3-SFT及其他模型生成补全结果, 并通过两两比较获得偏好标签. 最终获得了354,192个用于偏好调优的数据实例.
在偏好微调算法设计中, 实验中优先考虑了简单性和效率, 因此整个开发过程中采用了长度归一化的DPO, 而没有投入更多成本去研究基于强化学习的方法如PPO.
采用了具有可验证奖励的特定技能强化学习, 利用标准的强化学习范式来针对那些能够与真实结果进行评估的技能 (例如数学), 这一方法被称为RLVR. 当任务完成时, 该算法会获得一个恒定的奖励值, 这显著提升了GSM8K、MATH和IFEval的表现.
实现了一种异步训练架构, 通过vLLM高效运行大语言模型推理, 同时学习器并行执行梯度更新.
实现了评估框架Tülu 3 Eval, 是一款开放的评估工具包, 旨在通过精心挑选的评估套件和去噪工具, 指导开发过程.

1. Tülu 3 数据集

Tülu数据集是通过整合公开数据并人工精选数据, 来策划和收集得到的. 它聚焦于知识回忆、推理能力、数学、编程、指令执行、通用对话和安全等核心技能.

(1) 提示词精选

团队首先对公开数据集进行了广泛的调研, 然后对每个数据集进行人工审核, 并根据以下考量挑选出合适的数据集:

多样性
目标技能
数据溯源与许可

2. Tülu 3 评估工具

评估工具在 https://github.com/allenai/olmes 上公开.

3. Tülu 3 配方

现在, 来介绍一下Tülu3这个模型时怎么训练出来的, 据团队自己所说, Tülu3的关键贡献在于数据、方法、架构改变和严格评估.

(1) 数据整理

(2) 监督微调

(3) 偏好微调

(4) RLVR

LangChain 核心组件 04：Short-term Memory

Mon, 23 Mar 2026 00:00:00 GMT

这一篇我放在 Tools 后面，是因为记忆本质上是在“模型 + 消息 + 工具调用”都成立之后，才真正开始变得重要。它处理的是对话变长之后的现实问题。

1. 介绍

记忆是一种能够记录过往交互信息的系统。对于智能体而言，记忆至关重要，因为它能让智能体记住过往的交互过程，从反馈中学习，并适应用户的偏好。当智能体处理涉及大量用户交互的复杂任务时，这项能力对于提升效率与用户满意度都不可或缺。

短期记忆可让应用程序在单一对话线程或对话中记住过往的交互内容。

对话历史是短期记忆最常见的形式。冗长的对话对当下的大语言模型构成挑战；完整的对话历史可能无法容纳于大语言模型的上下文窗口中，进而导致上下文丢失或错误。

即便你的模型支持完整的上下文长度，大多数大语言模型在处理长上下文时的表现依然不佳。它们会被过时或无关的内容“干扰”，同时还会面临响应速度变慢、成本升高的问题。

聊天模型通过Message接收上下文信息，这些消息包含指令（系统消息）和输入内容（用户消息）。在聊天应用中，消息会在用户输入与模型回复之间交替呈现，由此形成的消息列表会随着时间推移不断变长。由于上下文窗口存在限制，许多应用都可以借助相关技术来移除或“遗忘”过时信息。

2. 基本使用

要为智能体添加短期记忆（线程级持久化），你需要在创建智能体时指定一个checkpointer。

from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver  


agent = create_agent(
    "gpt-5",
    tools=[get_user_info],
    checkpointer=InMemorySaver(),
)

agent.invoke(
    {"messages": [{"role": "user", "content": "Hi! My name is Bob."}]},
    {"configurable": {"thread_id": "1"}},
)

如果要使用记忆，我们必须要定义好一个线程。如果，我们要生成随机线程号，可以用{"configurable": {"thread_id": str(uuid.uuid4())}}，uuid.uuid4()是生成一个新的随机的UUID再转成字符串。

在持久化场景中，configurable最常用的就是thread_id，此外也是有其他键的，也可以自己定义业务参数：

config = {
    "configurable": {
        "thread_id": "thread-1",
        "user_id": "owen",
        "lang": "zh",
        "tenant_id": "school-a"
    }
}

再往深盘一下，config的完整结果如下：

config = {
    "configurable": {
        # 运行逻辑要用的参数
        "thread_id": "...",
        "user_id": "...",
        "lang": "zh",
    },
    # 观测/追踪用
    "tags": [...],
    "metadata": {...},
}

而在生产环境中，往往使用数据库支持的检查点保存器，如使用langgraph提供的和Postgres结合的包：

pip install langgraph-checkpoint-postgres

然后，我们用如下语法连接数据库：

from langchain.agents import create_agent

from langgraph.checkpoint.postgres import PostgresSaver  


DB_URI = "postgresql://postgres:postgres@localhost:5442/postgres?sslmode=disable"
with PostgresSaver.from_conn_string(DB_URI) as checkpointer:
    checkpointer.setup() # auto create tables in PostgreSQL
    agent = create_agent(
        "gpt-5",
        tools=[get_user_info],
        checkpointer=checkpointer,
    )

至于对更多数据库的支持，看这里。

3. 自定义agent记忆

默认情况下，agents通过AgentState来管理短期记忆，比如直接用message键来查看对话历史。

但是，我们也可以给AgentState加入别的信息，自定义的state schemas会被传递给create_agent的state_schema参数。

from langchain.agents import create_agent, AgentState
from langgraph.checkpoint.memory import InMemorySaver


class CustomAgentState(AgentState):
    user_id: str
    preferences: dict

agent = create_agent(
    "gpt-5",
    tools=[get_user_info],
    state_schema=CustomAgentState,
    checkpointer=InMemorySaver(),
)

# Custom state can be passed in invoke
result = agent.invoke(
    {
        "messages": [{"role": "user", "content": "Hello"}],
        "user_id": "user_123",
        "preferences": {"theme": "dark"}
    },
    {"configurable": {"thread_id": "1"}})

4. 超出上下文的解决方案

(1) Trim messages

大多数大语言模型都有其支持的最大上下文窗口（以令牌为单位计量）。

判断何时截断消息的一种方法是统计消息历史中的令牌数量，当令牌数接近该上限时便进行截断。若你使用 LangChain 框架，可借助消息裁剪工具，指定需要保留的令牌数量，以及处理边界时所采用的strategy（例如保留最后max_tokens个令牌）。

若要在Agent中裁剪消息历史，可使用@before_model中间件装饰器，示例如下：

from langchain.messages import RemoveMessage
from langgraph.graph.message import REMOVE_ALL_MESSAGES
from langgraph.checkpoint.memory import InMemorySaver
from langchain.agents import create_agent, AgentState
from langchain.agents.middleware import before_model
from langgraph.runtime import Runtime
from langchain_core.runnables import RunnableConfig
from typing import Any


@before_model
def trim_messages(state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
    """Keep only the last few messages to fit context window."""
    messages = state["messages"]

    if len(messages) <= 3:
        return None  # No changes needed

    first_msg = messages[0]
    recent_messages = messages[-3:] if len(messages) % 2 == 0 else messages[-4:]
    new_messages = [first_msg] + recent_messages

    return {
        "messages": [
            RemoveMessage(id=REMOVE_ALL_MESSAGES),
            *new_messages
        ]
    }

agent = create_agent(
    your_model_here,
    tools=your_tools_here,
    middleware=[trim_messages],
    checkpointer=InMemorySaver(),
)

config: RunnableConfig = {"configurable": {"thread_id": "1"}}

agent.invoke({"messages": "hi, my name is bob"}, config)
agent.invoke({"messages": "write a short poem about cats"}, config)
agent.invoke({"messages": "now do the same but for dogs"}, config)
final_response = agent.invoke({"messages": "what's my name?"}, config)

final_response["messages"][-1].pretty_print()
"""
================================== Ai Message ==================================

Your name is Bob. You told me that earlier.
If you'd like me to call you a nickname or use a different name, just say the word.
"""

我们可以看到，trim_message方法被加上@before_model装饰器，放进了中间件（之前介绍过before_model的位置。这里使用了langgraph.graph.message的方法，REMOVE_ALL_MESSAGES。还是使用了一些高级用法，比如运行时，这里暂时不用看。

(2) Delete message

这里使用RemoveMessage把消息从图中删掉

from langchain.messages import RemoveMessage  

def delete_messages(state):
    messages = state["messages"]
    if len(messages) > 2:
        # remove the earliest two messages
        return {"messages": [RemoveMessage(id=m.id) for m in messages[:2]]}

如果是要删除所有消息，就按照trim message方案中那样：

from langgraph.graph.message import REMOVE_ALL_MESSAGES  

def delete_messages(state):
    return {"messages": [RemoveMessage(id=REMOVE_ALL_MESSAGES)]}

给出一个完整删除最早期两个消息的过程：

from langchain.messages import RemoveMessage
from langchain.agents import create_agent, AgentState
from langchain.agents.middleware import after_model
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.runtime import Runtime
from langchain_core.runnables import RunnableConfig


@after_model
def delete_old_messages(state: AgentState, runtime: Runtime) -> dict | None:
    """Remove old messages to keep conversation manageable."""
    messages = state["messages"]
    if len(messages) > 2:
        # remove the earliest two messages
        return {"messages": [RemoveMessage(id=m.id) for m in messages[:2]]}
    return None


agent = create_agent(
    "gpt-5-nano",
    tools=[],
    system_prompt="Please be concise and to the point.",
    middleware=[delete_old_messages],
    checkpointer=InMemorySaver(),
)

config: RunnableConfig = {"configurable": {"thread_id": "1"}}

for event in agent.stream(
    {"messages": [{"role": "user", "content": "hi! I'm bob"}]},
    config,
    stream_mode="values",
):
    print([(message.type, message.content) for message in event["messages"]])

for event in agent.stream(
    {"messages": [{"role": "user", "content": "what's my name?"}]},
    config,
    stream_mode="values",
):
    print([(message.type, message.content) for message in event["messages"]])

(3) Summarize messages

如上所示，裁剪或删除消息的问题在于，消息队列的筛选操作可能会导致信息丢失。正因如此，部分应用采用更为复杂的方法，即借助对话模型对消息历史进行总结，从而获得更好的效果。

我们使用SummarizationMiddleware中间件对历史对话进行总结，完整用法示例如下：

from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware
from langgraph.checkpoint.memory import InMemorySaver
from langchain_core.runnables import RunnableConfig


checkpointer = InMemorySaver()

agent = create_agent(
    model="gpt-4.1",
    tools=[],
    middleware=[
        SummarizationMiddleware(
            model="gpt-4.1-mini",
            trigger=("tokens", 4000),
            keep=("messages", 20)
        )
    ],
    checkpointer=checkpointer,
)

config: RunnableConfig = {"configurable": {"thread_id": "1"}}
agent.invoke({"messages": "hi, my name is bob"}, config)
agent.invoke({"messages": "write a short poem about cats"}, config)
agent.invoke({"messages": "now do the same but for dogs"}, config)
final_response = agent.invoke({"messages": "what's my name?"}, config)

final_response["messages"][-1].pretty_print()
"""
================================== Ai Message ==================================

Your name is Bob!
"""

5. 访问记忆

可以通过多种方式访问和修改智能体的短期记忆（也叫state）。

(1) 工具

在工具一节就详细介绍过，tool可以通过ToolRuntime来修改state的信息。下面我们直接贴官网的两个示例，一个是读取state，一个是写入state：

from langchain.agents import create_agent, AgentState
from langchain.tools import tool, ToolRuntime


class CustomState(AgentState):
    user_id: str

@tool
def get_user_info(
    runtime: ToolRuntime
) -> str:
    """Look up user info."""
    user_id = runtime.state["user_id"]
    return "User is John Smith" if user_id == "user_123" else "Unknown user"

agent = create_agent(
    model="gpt-5-nano",
    tools=[get_user_info],
    state_schema=CustomState,
)

result = agent.invoke({
    "messages": "look up user information",
    "user_id": "user_123"
})
print(result["messages"][-1].content)
# > User is John Smith.

from langchain.tools import tool, ToolRuntime
from langchain_core.runnables import RunnableConfig
from langchain.messages import ToolMessage
from langchain.agents import create_agent, AgentState
from langgraph.types import Command
from pydantic import BaseModel


class CustomState(AgentState):
    user_name: str

class CustomContext(BaseModel):
    user_id: str

@tool
def update_user_info(
    runtime: ToolRuntime[CustomContext, CustomState],
) -> Command:
    """Look up and update user info."""
    user_id = runtime.context.user_id
    name = "John Smith" if user_id == "user_123" else "Unknown user"
    return Command(update={
        "user_name": name,
        # update the message history
        "messages": [
            ToolMessage(
                "Successfully looked up user information",
                tool_call_id=runtime.tool_call_id
            )
        ]
    })

@tool
def greet(
    runtime: ToolRuntime[CustomContext, CustomState]
) -> str | Command:
    """Use this to greet the user once you found their info."""
    user_name = runtime.state.get("user_name", None)
    if user_name is None:
       return Command(update={
            "messages": [
                ToolMessage(
                    "Please call the 'update_user_info' tool it will get and update the user's name.",
                    tool_call_id=runtime.tool_call_id
                )
            ]
        })
    return f"Hello {user_name}!"

agent = create_agent(
    model="gpt-5-nano",
    tools=[update_user_info, greet],
    state_schema=CustomState,
    context_schema=CustomContext,
)

agent.invoke(
    {"messages": [{"role": "user", "content": "greet the user"}]},
    context=CustomContext(user_id="user_123"),
)

(2) Prompt

在中间件中访问短期记忆（状态），基于对话历史或自定义状态字段生成动态提示词。

from langchain.agents import create_agent
from typing import TypedDict
from langchain.agents.middleware import dynamic_prompt, ModelRequest


class CustomContext(TypedDict):
    user_name: str


def get_weather(city: str) -> str:
    """Get the weather in a city."""
    return f"The weather in {city} is always sunny!"


@dynamic_prompt
def dynamic_system_prompt(request: ModelRequest) -> str:
    user_name = request.runtime.context["user_name"]
    system_prompt = f"You are a helpful assistant. Address the user as {user_name}."
    return system_prompt


agent = create_agent(
    model="gpt-5-nano",
    tools=[get_weather],
    middleware=[dynamic_system_prompt],
    context_schema=CustomContext,
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What is the weather in SF?"}]},
    context=CustomContext(user_name="John Smith"),
)
for msg in result["messages"]:
    msg.pretty_print()

如果你还有印象，这个@dynamic_prompt是专门调整提示词的装饰器，范围比直接before_model或者wrap_model_xxxx更小。

(3) After model

在agent一章提到了这个部分，是在模型返回消息之后进行操作的钩子，当然也可以用于操作state。

%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontFamily": "monospace"
  },
  "flowchart": {
    "curve": "basis"
  }
}}%%
graph TD
    S(["__start__"])
    MODEL(model)
    POST(after_model)
    TOOLS(tools)
    E(["__end__"])

    S --> MODEL
    MODEL --> POST
    POST -.-> E
    POST -.-> TOOLS
    TOOLS --> MODEL

    classDef blueHighlight fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A;
    classDef greenHighlight fill:#DCFCE7,stroke:#16A34A,color:#14532D;
    classDef neutral fill:#F3F4F6,stroke:#9CA3AF,stroke-width:2px,color:#374151;

    class S blueHighlight;
    class E blueHighlight;
    class POST greenHighlight;
    class MODEL,TOOLS neutral;

这里提供一个示例，一看就懂了。这是触发STOP_WORDS的时候消除所有消息。

from langchain.messages import RemoveMessage
from langgraph.checkpoint.memory import InMemorySaver
from langchain.agents import create_agent, AgentState
from langchain.agents.middleware import after_model
from langgraph.runtime import Runtime


@after_model
def validate_response(state: AgentState, runtime: Runtime) -> dict | None:
    """Remove messages containing sensitive words."""
    STOP_WORDS = ["password", "secret"]
    last_message = state["messages"][-1]
    if any(word in last_message.content for word in STOP_WORDS):
        return {"messages": [RemoveMessage(id=last_message.id)]}
    return None

agent = create_agent(
    model="gpt-5-nano",
    tools=[],
    middleware=[validate_response],
    checkpointer=InMemorySaver(),
)

Naive-RAG 端到端实战：从文档入库到 FastAPI 服务

Mon, 23 Mar 2026 00:00:00 GMT

这一篇可以看作前面 1 到 6 篇的第一次汇总练习。目标不是做一个“很聪明”的系统，而是先把最小闭环打通：文档 -> 切分 -> 嵌入 -> Milvus -> 检索 -> 回答 -> API 服务。

Naive-RAG 实战

1. 设想和路线

我们假设已经有LangChain的基础，RAG理论，Milvus入门的学习了，现在想要做一个简单的demo，目标是整合FastAPI + LangChain，做一个Naive-RAG端到端回答系统，然后用Docker打包发布，从而将部分学习的东西先变成整体，化为内功。

什么是Naive-RAG？简单来说，这就是最原始、最直接的RAG生成方式，分为“检索+生成”两步走。

我准备直接把我的强化学习文档作为检索来源，上传。

AI给我的最小交付建议：

POST /ingest：上传 pdf/md/txt，完成切块、embedding、入库
POST /ask：输入问题，返回答案、命中文档片段、来源
GET /health：健康检查
docker-compose up 能一键启动
准备一份 20~30 条的小评测集

并且评估不能靠“感觉答得不错”，要看4件事：

检索命中率：答案所在片段有没有进 top-k
答案正确性：回答是否接近参考答案
Groundedness：回答是否被检索到的上下文支持
延迟/成本：一次问答耗时和 token 开销

回到我的资料，我准备用强化学习入门时候的笔记（文件是markdown），特点是有大量的图片，但是文字量本身不大，标题层级明显，章节结构不错。麻烦点在于图片里有关键知识，我决定预处理把图片先换成AI生成的图片描述，然后再处理纯文本的md。

第一阶段应该把重点放在“让回答严格受笔记约束”。主要是因为，RL算是LLM本来就很熟的领域，如果不限制就直接用自己的知识答了，所以我们第一版要做成grounded_only的设计（以后可以拓展）。

2. 文档入库

我必须先实现好文档的切分和入库。我采用在项目文件下写一个.env的方法，存入我的三方数据库和key，还有milvus相关配置。

经过边写边和AI沟通考虑，我将先写下处理单个文档的脚本markdown_splitter.py，它对外暴露split_markdown_file，返回一个list[Document]（Document是langchain.core里面的一个类，用于处理文件，后续RAG大多依赖于这个）。对文档我们采用两级切分，首先按markdown语法切分，然后再检索其中过长的块，进行第二次Recursive切分。代码如下：

from langchain_text_splitters import MarkdownHeaderTextSplitter
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_community.document_loaders import TextLoader
from pathlib import Path
from langchain_core.documents import Document


def _load_markdown_txt(file_path:Path) -> str:
    """
    根据路径加载markdown文件
    """
    loader = TextLoader(file_path)
    docs = loader.load()
    return docs[0].page_content

def _split_by_header(text:str) -> list[Document]:
    """
    对markdown文件进行第一次切分
    """
    markdown_spliter = MarkdownHeaderTextSplitter(
        strip_headers = False,
        headers_to_split_on=[
            ("#","h1"),
            ("##","h2"),
            ("###","h3")
        ],
        return_each_line = False
    )
    return markdown_spliter.split_text(text)
   

def _split_large_chunks(chunks:list[Document]) -> list[Document]:
    """
    对Document列表较长的块进一步切分
    """
    recursive_split = RecursiveCharacterTextSplitter(
        # 我当时笔记喜欢半角标点
        separators=["\n\n","\n",". ",", "," ",""],
        chunk_size = 300,
        chunk_overlap = 20,
    )

    docs_list = []

    for chunk in chunks:
        if len(chunk.page_content)>300:
            i = recursive_split.split_documents([chunk])
            docs_list.extend(i)
        else:
            docs_list.append(chunk)
    return docs_list


def split_markdown_file(file_path:Path) -> list[Document]:
    """
    对外接口，传入md文件路径，返回切分完成的documents
    """
    text = _load_markdown_txt(file_path)
    header_chunks = _split_by_header(text)
    final_chunks = _split_large_chunks(header_chunks)
    return final_chunks


def _resolve_debug_target() -> Path:
    """默认取 processed 目录下一篇 markdown，方便单独调试 splitter。可以自己改第几个。"""
    script_path = Path(__file__).resolve()
    project_root = script_path.parent.parent
    processed_dir = project_root / "docs" / "processed"
    md_files = sorted(processed_dir.glob("*.md"))
    if not md_files:
        raise FileNotFoundError(f"在 {processed_dir} 下没有找到 markdown 文件")
    return md_files[0]


if __name__ == "__main__":
    import sys

    if len(sys.argv) > 1:
        target_file = Path(sys.argv[1]).expanduser().resolve()
    else:
        target_file = _resolve_debug_target()

    chunks = split_markdown_file(target_file)
    print(f"调试文件: {target_file}")
    print(f"总块数: {len(chunks)}")
    print()

    for i, chunk in enumerate(chunks):
        print("=" * 10 + f" 第{i}块 " + "=" * 10)
        print(f"长度: {len(chunk.page_content)}")
        print(f"metadata: {chunk.metadata}")
        print("正文预览:")
        print(chunk.page_content[:400])
        print()

3. chunk加载进库

前面我们已经切分完毕，现在写一个docs_to_milvus.py函数，负责创建需要的Collection并且将chunk调整成适合schema的字典，插入Collection。

from markdown_splitter import split_markdown_file
from pathlib import Path
from pymilvus import MilvusClient, FieldSchema, CollectionSchema, DataType
from dotenv import load_dotenv
import os
from langchain_openai import OpenAIEmbeddings

# 根目录相对设置
script_path = Path(__file__).resolve()
project_path = script_path.parent.parent

# 资源寻路
processed_dir = project_path/"docs"/"processed"
env_path = project_path/".env"

# 全局变量
load_dotenv(env_path)


# 开始切分docs
# Path.glob(...)返回的不是列表本身，而是一个可迭代对象
print("=" * 5 + "正在切分md文件" + "=" * 5 + "\n")
chunk_list = []
for file_path in processed_dir.glob("*.md"):
    chunk_list.extend(split_markdown_file(file_path))
print("=" * 5 + "文件切分完成" + "=" * 5 + "\n")


# 开始连接milvus
# 建立客户端连接
client = MilvusClient(uri = os.environ.get("MILVUS_URL"))


# 进行嵌入
# 我这里从中转站随便挑了一个text-embedding-3-small，默认嵌入长度是1536
# 进行嵌入
print("=" * 5 + "正在嵌入chunk" + "=" * 5 + "\n")
embedding_model = OpenAIEmbeddings(
    model="text-embedding-3-small",
    api_key=os.environ.get("QIHANG_API"),
    base_url=os.environ.get("QIHANG_BASE_URL"),
)

# 遍历 chunk list，将 page_content 放入列表，批量嵌入
page_content_list = [chunk.page_content for chunk in chunk_list]

vectors = embedding_model.embed_documents(page_content_list)

print("=" * 5 + "嵌入完成" + "=" * 5 + "\n")

# print(f"chunk 数量: {len(page_content_list)}")
# print(f"向量数量: {len(vectors)}")
# print(f"单个向量维度: {len(vectors[0])}")


# 动态得到需要嵌入的维度
vector_dim = len(vectors[0])

print("=" * 5 + "开始构造Collection" + "=" * 5 + "\n")
# 动态判断text所需要最大长度
# 注意不是字符数而是token数，要encode一下
max_length_text = 0
max_length_title = 0
for chunk in chunk_list:
    max_length_text = max(max_length_text,len(chunk.page_content.encode("utf-8")))
    max_length_title = max(max_length_title,len(chunk.metadata.get("h1","").encode("utf-8")),len(chunk.metadata.get("h2","").encode("utf-8")),len(chunk.metadata.get("h3","").encode("utf-8")))



# 定义Collection的schema
fields = [
    FieldSchema(
        name = "id",
        dtype = DataType.INT64,
        description="作为主键的id",
        is_primary = True,
        auto_id = True
    ),
    FieldSchema(
        name = "vector",
        dtype = DataType.FLOAT_VECTOR, 
        # dim必须和嵌入模型一致
        dim = vector_dim,
        description = "存储chunk的向量"
    ),
    FieldSchema(
        name = "text",
        dtype = DataType.VARCHAR,
        # VARCHAR的最大长度
        max_length = max_length_text,
        description = "原始page_content文本"
    ),
    FieldSchema(
        name = "h1",
        dtype = DataType.VARCHAR,
        max_length = max_length_title,
        description = "一级标题"
    ),
    FieldSchema(
        name = "h2",
        dtype = DataType.VARCHAR,
        max_length = max_length_title,
        description = "二级标题"
    ),
    FieldSchema(
        name = "h3",
        dtype = DataType.VARCHAR,
        max_length = max_length_title,
        description = "三级标题"
    )
]

schema = CollectionSchema(fields)

# 创建Collection，注意去重
if client.has_collection("RL_docs"):
    client.drop_collection("RL_docs")

# 创建collection
client.create_collection(
    collection_name="RL_docs", 
    schema=schema
)

# 给Collection建立索引
index_params = client.prepare_index_params()
index_params.add_index(
    field_name="vector",
    index_type="FLAT",
    index_name="vector_index",
    metric_type="COSINE",
    params={},
)
client.create_index(
    collection_name="RL_docs", index_params=index_params
)


print("=" * 5 + "Collection构造完成" + "=" * 5 + "\n")

# print(len(data) == len(vectors))

# 开始构建Milvus insert data并插入
# data里面是Document的list，vectors是向量，现在对齐遍历
# 我们最终需要一个列表，里面有所有对应chunk数目的字典数，字典对应schema字段

print("=" * 5 + "数据入库中" + "=" * 5 + "\n")
records = []
for chunk, vec in zip(chunk_list, vectors):
    record = {
        "vector": vec,
        "text": chunk.page_content,
        "h1": chunk.metadata.get("h1", ""),
        "h2": chunk.metadata.get("h2", ""),
        "h3": chunk.metadata.get("h3", ""),
    }
    records.append(record)

print("=" * 5 + "入库已完成" + "=" * 5 + "\n")
client.insert(
    collection_name = "RL_docs",
    data = records
)

4. 本地QA

为了先看看Naive-RAG是否已经形成了完整的通路，我们现在本地用聊天模型试试效果。代码qa_pipeline.py和运行结果如下：

# 本地问答测试
from langchain.chat_models import init_chat_model
from dotenv import load_dotenv
from pathlib import Path
from pymilvus import MilvusClient
from langchain_openai import OpenAIEmbeddings
import os

# 加载项目相对路径
script_path = Path(__file__).resolve()
project_path = script_path.parent.parent
env_path = project_path/".env"

# 加载全局配置
load_dotenv(env_path)
COLLECTION_NAME = "RL_docs"
TOP1_THRESHOLD = 0.45
HIT_THRESHOLD = 0.40

# 连接数据库
client = MilvusClient(uri = os.environ.get("MILVUS_URL"))


# 加载embedding模型
embeddings_model = OpenAIEmbeddings(
    model = "text-embedding-3-small",
    api_key = os.environ.get("QIHANG_API"),
    base_url = os.environ.get("QIHANG_BASE_URL")
)

# 加载聊天模型
chat_model = init_chat_model(
    model = "openai:gpt-4o-mini",
    temperature=0.5,
    timeout=30,
    max_retries=6, 
    api_key = os.environ.get("QIHANG_API"),
    base_url = os.environ.get("QIHANG_BASE_URL")
)


# 加载Collection
if not client.has_collection(COLLECTION_NAME):
    raise ValueError(f"Collection {COLLECTION_NAME} 不存在，请先运行入库脚本")

client.load_collection(collection_name=COLLECTION_NAME)


def retrieve(question, k = 4):
    """
    查询并返回topk结果
    """
    query_vector = embeddings_model.embed_query(question)
    result = client.search(
        collection_name = COLLECTION_NAME,
        data = [query_vector],
        limit = k,
        output_fields=["text","h1","h2","h3"],
        anns_field = "vector",
        search_params={"metric_type": "COSINE", "params": {}},
    )
    return result[0]


def filter_hits(hits, top1_threshold=TOP1_THRESHOLD, hit_threshold=HIT_THRESHOLD):
    """
    根据相似度分数过滤检索结果:
    1. top1 太低时直接视为未命中
    2. 只保留达到最低阈值的片段
    """
    if not hits:
        return []

    top1_score = hits[0].get("distance", 0.0)
    if top1_score < top1_threshold:
        return []

    return [hit for hit in hits if hit.get("distance", 0.0) >= hit_threshold]


def build_context(hits):
    """
    将 Milvus 命中结果拼成带编号、标题、正文的上下文
    """
    blocks = []

    # 从1开始编号
    for idx, hit in enumerate(hits, start=1):
        entity = hit.get("entity", {})

        text = entity.get("text", "").strip()
        h1 = entity.get("h1", "").strip()
        h2 = entity.get("h2", "").strip()
        h3 = entity.get("h3", "").strip()

        title_parts = [part for part in [h1, h2, h3] if part]
        title_path = " > ".join(title_parts) if title_parts else "未标注标题"

        block = (
            f"[片段{idx}]\n"
            f"标题：{title_path}\n"
            f"内容：{text}"
        )
        blocks.append(block)

    return "\n\n".join(blocks)


def build_sources(hits):
    """
    对检索到的内容，生成标注字符串
    """
    sources = []

    for idx, hit in enumerate(hits, start=1):
        entity = hit.get("entity", {})
        h1 = entity.get("h1", "").strip()
        h2 = entity.get("h2", "").strip()
        h3 = entity.get("h3", "").strip()

        title_parts = [part for part in [h1, h2, h3] if part]
        title_path = " > ".join(title_parts) if title_parts else "未标注标题"

        sources.append(f"[片段{idx}] {title_path}")

    return "【资料来源】\n" + "\n".join(sources)


def answer(question):
    """
    结合搜索结果回答问题
    """
    SYSTEM_MESSAGE = """
    你是一个基于强化学习资料回答问题的助手，只能根据给定片段回答。
    如果资料没有覆盖，就明确回答“资料未覆盖”。
    不要使用外部知识，不要编造来源。

    以下是检索到的资料片段：
    """
    raw_hits = retrieve(question)
    hits = filter_hits(raw_hits)
    if not hits:
        return "资料未覆盖。"

    context = build_context(hits)
    sources = build_sources(hits)
    result = chat_model.invoke(
    [
        {"role":"system","content":SYSTEM_MESSAGE + context},
        {"role":"user","content":question}
    ]
    )
    return result.content + "\n\n" + sources


if __name__ == "__main__":
    question = input().strip()
    result = answer(question)
    print(result)

5. FastAPI

我们在Naive-RAG下面再创建一个文件夹叫做app，并存放逻辑，将其做成一个最小但是像项目的结构。

原来的 qa_pipeline.py -> 被拆成 rag_service.py + schemas.py + main.py

原来脚本里的 os.environ.get(...) -> 收到 config.py

原来的 if name == "main": -> 变成了 FastAPI 的 /ask 路由

原来“打印字符串结果” -> 变成结构化 API 响应

这样使得结果更适应FastAPI。

一个一个来，我们先看看app/rag_service.py，它是将之前的所有流程都封装了进去，对外暴露一个RAGService类。当然，逻辑和前面都是一样。

from langchain.chat_models import init_chat_model
from langchain_openai import OpenAIEmbeddings
from pymilvus import MilvusClient

from .config import Settings
from .schemas import AskResponse, SourceItem


SYSTEM_MESSAGE = """
你是一个基于强化学习资料回答问题的助手，只能根据给定片段回答。
如果资料没有覆盖，就明确回答“资料未覆盖”。
不要使用外部知识，不要编造来源，也不要假装自己看过未提供的资料。

以下是检索到的资料片段：
""".strip()


# 用一个RAGSerice类，封装整个流程
class RAGService:
    def __init__(self, settings: Settings):
        self.settings = settings
        self.client = MilvusClient(uri=settings.milvus_url)

        if not self.client.has_collection(settings.collection_name):
            raise ValueError(
                f"Collection {settings.collection_name} 不存在，请先运行入库脚本"
            )

        self.client.load_collection(collection_name=settings.collection_name)

        self.embeddings_model = OpenAIEmbeddings(
            model=settings.embedding_model,
            api_key=settings.qihang_api,
            base_url=settings.qihang_base_url,
        )

        self.chat_model = init_chat_model(
            model=settings.chat_model,
            model_provider="openai",
            temperature=settings.chat_temperature,
            timeout=settings.chat_timeout,
            max_retries=settings.chat_max_retries,
            api_key=settings.qihang_api,
            base_url=settings.qihang_base_url,
        )

    def retrieve(self, question: str, k: int | None = None) -> list[dict]:
        query_vector = self.embeddings_model.embed_query(question)
        result = self.client.search(
            collection_name=self.settings.collection_name,
            data=[query_vector],
            limit=k or self.settings.default_k,
            output_fields=["text", "h1", "h2", "h3"],
            anns_field="vector",
            search_params={"metric_type": "COSINE", "params": {}},
        )
        return result[0]

    def filter_hits(self, hits: list[dict]) -> list[dict]:
        if not hits:
            return []

        top1_score = hits[0].get("distance", 0.0)
        if top1_score < self.settings.top1_threshold:
            return []

        return [
            hit
            for hit in hits
            if hit.get("distance", 0.0) >= self.settings.hit_threshold
        ]

    def build_context(self, hits: list[dict]) -> str:
        blocks: list[str] = []
        for idx, hit in enumerate(hits, start=1):
            entity = hit.get("entity", {})
            text = entity.get("text", "").strip()
            h1 = entity.get("h1", "").strip()
            h2 = entity.get("h2", "").strip()
            h3 = entity.get("h3", "").strip()

            title_parts = [part for part in [h1, h2, h3] if part]
            title_path = " > ".join(title_parts) if title_parts else "未标注标题"

            blocks.append(
                f"[片段{idx}]\n"
                f"标题：{title_path}\n"
                f"内容：{text}"
            )

        return "\n\n".join(blocks)

    def build_sources(self, hits: list[dict]) -> list[SourceItem]:
        sources: list[SourceItem] = []
        seen_titles: set[str] = set()

        for idx, hit in enumerate(hits, start=1):
            entity = hit.get("entity", {})
            h1 = entity.get("h1", "").strip()
            h2 = entity.get("h2", "").strip()
            h3 = entity.get("h3", "").strip()

            title_parts = [part for part in [h1, h2, h3] if part]
            title_path = " > ".join(title_parts) if title_parts else "未标注标题"

            if title_path in seen_titles:
                continue

            seen_titles.add(title_path)
            sources.append(
                SourceItem(
                    snippet_id=f"片段{idx}",
                    title=title_path,
                    score=round(hit.get("distance", 0.0), 4),
                )
            )

        return sources

    def answer(self, question: str, k: int | None = None) -> AskResponse:
        raw_hits = self.retrieve(question, k)
        hits = self.filter_hits(raw_hits)

        if not hits:
            return AskResponse(answer="资料未覆盖。", covered=False, sources=[])

        context = self.build_context(hits)
        response = self.chat_model.invoke(
            [
                {"role": "system", "content": f"{SYSTEM_MESSAGE}\n\n{context}"},
                {"role": "user", "content": question},
            ]
        )

        return AskResponse(
            answer=response.content.strip(),
            covered=True,
            sources=self.build_sources(hits),
        )

然后是app/config.py，这里直接对外暴露一个settings实例，以后直接调用即可。我们把默认设置和环境变量都在这里读取了先。

from pathlib import Path

from pydantic import Field
from pydantic_settings import BaseSettings, SettingsConfigDict

app_path = Path(__file__).resolve()
project_path = app_path.parent.parent
env_path = project_path / ".env"


class Settings(BaseSettings):
    milvus_url: str = Field(validation_alias="MILVUS_URL")
    qihang_api: str = Field(validation_alias="QIHANG_API")
    qihang_base_url: str = Field(validation_alias="QIHANG_BASE_URL")

    collection_name: str = "RL_docs"
    embedding_model: str = "text-embedding-3-small"
    chat_model: str = "gpt-4o-mini"
    chat_temperature: float = 0.5
    chat_timeout: int = 30
    chat_max_retries: int = 6
    top1_threshold: float = 0.45
    hit_threshold: float = 0.40
    default_k: int = 4

    model_config = SettingsConfigDict(
        env_file=env_path,
        env_file_encoding="utf-8",
        extra="ignore",
    )


settings = Settings()

我们可以看到，这里用到了之前都没有用过的from pydantic_settings import BaseSettings, SettingsConfigDict。其实这属于专门用来写配置类的Pydantic基类。下面的语法，就是给BaseSettings配置行为用的，他告诉BaseSettings去哪个文件找配置，然后按什么编码读文件，遇到没有声明过的环境变量怎么处理。

model_config = SettingsConfigDict(
    env_file=env_path,
    env_file_encoding="utf-8",
    extra="ignore",
)

所以我们在Settings类中定义了milvus_url等，并把validation_alias设置成了MILVUS_URL，跟环境变量里面写的对上了。

然后，因为我们要做的FastAPI接口了，用户不再是“终端里的一句话”，而是一个HTTP请求。所以程序必须知道这个请求体的规范，这就要请app/schemas.py登场了：

from pydantic import BaseModel, Field


class AskRequest(BaseModel):
    question: str = Field(..., min_length=1, description="用户提问内容")
    k: int | None = Field(default=None, ge=1, le=10, description="返回的检索片段数量")


class SourceItem(BaseModel):
    snippet_id: str
    title: str
    score: float


class AskResponse(BaseModel):
    answer: str
    covered: bool
    sources: list[SourceItem] = Field(default_factory=list)


class HealthResponse(BaseModel):
    status: str
    collection_name: str

里面定义了四个类。AskRequest是定义了/ask请求应该接受什么样的请求体，包括question用min_length = 1表示必填，k可选（我们在config中已经定义默认值为4了，不需要用户一定要每次请求提供）；SourceItem适用于定义单条来源信息的标准结构，因为每次回答我们还会返回一个来源列表，包含片段编号、标题、分数；AskResponse用于定义/ask最终返回给调用方的数据结构，包含答案、是否覆盖、来源列表；HealthResponse就是给/health用的。

其实可以返回的时候全写字典，但是这样写对FastAPI 文档自动生成更友好，而且更容易维护。我们可以看到，rag_service.py就引用了这些类来作为信息的包装。

最后，我们来看看app/main.py：

from contextlib import asynccontextmanager

from fastapi import FastAPI, Request

from .config import settings
from .rag_service import RAGService
from .schemas import AskRequest, AskResponse, HealthResponse


@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.rag_service = RAGService(settings)
    yield


app = FastAPI(
    title="Naive RAG API",
    version="0.1.0",
    lifespan=lifespan,
)


@app.get("/health", response_model=HealthResponse)
async def health() -> HealthResponse:
    return HealthResponse(status="ok", collection_name=settings.collection_name)


@app.post("/ask", response_model=AskResponse)
async def ask(payload: AskRequest, request: Request) -> AskResponse:
    rag_service: RAGService = request.app.state.rag_service
    return rag_service.answer(payload.question, payload.k)

这个就是FastAPI的主入口，我们已经知道config.py 是配置入口，schemas.py 是接口协议，rag_service.py 是真正干活的业务层，那main.py的指责就很单纯了，它负责把HTTP请求接进来，再转交给RAGService。

先导入全局配置settings，导入fastapi的请求和对象，导入业务类RAGService，导入schemas中的各种规范类。

然后，用lifespan初始化一个全局可复用的RAGService，传入settings参数，生成并挂载应用级别全局对象app.state.rag_service。然后用yield表示初始化完成，可以开始处理请求（注意后面做FastAPI实例的时候传入一下lifespan）。然后，定义了一个健康检查路由/health，先用GET /health看看服务是否健康，并告诉连接的是哪个collection。

然后，就是重头戏/ask接口了，定义了一个用于POST /ask 的，按照AskRequest包装起来，调用RAGService的answer，返回。

使用uvicorn app.main:app --reload启动之后，我们直接访问文档页，http://127.0.0.1:8000/docs#/，发现就可以看到自己定义的接口和规范：

执行健康检查，状态没问题，并显示出Collection名：

执行ask，查看RAG链路是否正确：

再看一眼我们定义的Schemas：

不过另外要提醒一下，glob + 读文件 + 切分 + 入库依旧在docs_to_milvus.py里面，没有塞进FastAPI在线请求，不然会很重耦合（并且每次启动都要嵌入文件，很慢）。

6. Docker打包

在打包发布之前，我们先整理依赖。这个项目比较简单，可以记住用过哪些依赖。以后的开发最后都单独建一个环境，然后把用到的包都给freeze一下。

fastapi==0.135.1
uvicorn==0.42.0
pydantic==2.12.5
pydantic-settings==2.13.1
langchain==1.2.13
langchain-openai==1.1.12
pymilvus==2.6.11
python-dotenv==1.2.2

然后，我们写Dockerfile如下：

FROM python:3.11-slim

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

WORKDIR /app

COPY requirements.txt .

RUN pip install --no-cache-dir --upgrade pip \
    && pip install --no-cache-dir -r requirements.txt

COPY app ./app

EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

这版本的Dockerfile，将FastAPI问答服务包装成一个可运行镜像，打包app在线服务层（不包含离线注入脚本）。以一个已经装好 Python 3.11 的轻量 Linux 镜像作为基础，ENV PYTHONDONTWRITEBYTECODE=1 \ PYTHONUNBUFFERED=1代表不生产.pyc字节码缓存文件；PYTHONUNBUFFERED=1让python日志立刻输出；WORKDIR /app表示设置容器内的工作目录；COPY requirements.txt .是把requirements.txt复制到/app下；然后我们RUN一下环境依赖（记得加--no-cache-dir ）；COPY app ./app表示将本地的app/目录复制到容器里/app/app，这里没有复制docs和scripts;EXPOSE 8000表好似暴露容器的8000端口到宿主机，最后用CMD命令表示启动的命令。

现在，来到项目根目录，就可以用docker build -t owen571/naive-rag:0.1.0 .根据file文件构建起来一个镜像。

然后我们用docker run --rm -p 8000:8000 --env-file .env owen571/naive-rag:0.1.0来确认是否构建镜像成功即可。这里还有几个坑：

不能继续使用localhost，要是用MILVUS_URL=http://host.docker.internal:19530这样的说法。
环境变量不需要引号，等号两边不能有空格。docker的-env-file检查比load_dotenv严格一点

如下启动完成了（由于没写名字，被临时取名了）

启动之后，我们会发现功能都是正常的。

7. 发布

登录时候，直接推送如下：

docker push owen571/naive-rag:0.1.0

RLHF 奠基论文：Helpful & Harmless Assistant 速记

Mon, 23 Mar 2026 00:00:00 GMT

由于从开学到现在主要研究的方向均为Agent和他们之间的合作，因此现在将对这个方向进行一些稍微深入的挖掘。

一. 奠基与探索

Training a Helpful and Harmless Assistant with RLHF

仅仅模仿, 无法让模型在多元且冲突的人类价值观中做出选择. 在这样的背景下, Training a Helpful and Harmless Assistant with RLHF 论文作为Anthropic公司的早期工作, 系统阐述了RLHF如何弥补这一关键的鸿沟, 将模型训练从"模仿学习"的问题转变成了"优化目标"问题.

RLHF ( Reinforcement learning from human feedback), 基于人类反馈的强化学习, 本文提出这种技术来帮助Agent做出符合人类偏好的选择, 已得到一个在帮助性 ( Helpful ) 和无害性 ( Harmless )之间取得最佳平衡的语言模型助手.

其数据集的收集过程和模型的训练过程, 可以用下图来总结:

第一条线路以预训练模型为起点 ( PLM ), 根据互联网上的比较数据得到预训练偏好模型 ( PMP ), 然后再通过人类返回的比较数据集上微调, 得到偏好模型 ( PM ).
第二条线路再以PLM为起点, 根据提示数据, 将52B模型的蒸馏给更小的模型, 独立训练不同参数量的模型.
后者的模型会作为强化学习的初始策略模型, 然后以PM模型作为奖励模型, 基于PPO的方法进行强化学习训练; 根据得到的强化学习模型, 生成新的对比数据, 人工标注后重新训练PM, 然后再训练强化学习模型, 如此迭代.

有了对图片大致的了解, 接下来来详细介绍这个过程.

(1) 数据收集

团队选择直观且熟悉的任务, 从用户反馈界面收集反馈. 在Helpful的界面中, 让众包工作者选择更好的回复, 而在Harmless中 ( 红队 ), 工作者会激发其有害的回应, 选择更差的回复. 这样构成了人类偏好数据集, 下图分别为数据集的说明, 工作者看到的界面:

部署在这个界面上的模型有三类, 来对比数据监控进展且提高数据的多样性 ( 也许 ). 并用这三类数据集的结果, 把数据也划分成了三种分布, 前两个是静态数据集, 而最后一个不断迭代 ( 即文中的Online数据集, 后面证明效果确实比较好, 但是不是这次学习关注的重点 ). 最终通过Elo Score来比较模型性能.

(2) 偏好模型预训练

PMP

(3) 偏好模型

(4) 迭代

flowchart TD
    subgraph A [范式一: 偏好对齐训练]
        direction LR
        subgraph A1 [数据基础]
            A1_1["静态偏好数据集"]
        end
        
        A2["偏好奖励微调(PBRFT)"]
        A3["目标: 模仿人类偏好"]
        
        A1_1 -- 输入 --> A2
        A2 -- 导向 --> A3
    end

    subgraph B [范式二: 智能体强化学习]
        direction LR
        subgraph B1 [数据基础]
            B1_1["动态环境交互"]
        end
        
        B2["智能体强化学习(Agentic RL)"]
        B3["目标: 掌握复杂技能"]
        
        B1_1 -- 通过 --> B2
        B2 -- 导向 --> B3
    end

    A -- 范式演进 --> B

行为克隆👉监督微调👉强化微调👉基于偏好RFT👉智能体强化学习

LangChain 核心组件 05：Streaming

Sun, 22 Mar 2026 00:00:00 GMT

Streaming 我刻意放在 Memory 后面，因为它不是“先学会调用模型”的必修项，而是当你的应用开始像真实产品那样运行时，才最能体现价值。

1. 介绍

LangChain 实现了一套流式传输系统，用于呈现实时更新。

流式传输对于提升基于大语言模型构建的应用程序的响应能力至关重要。通过逐步展示输出内容，即便在完整响应生成完成之前，流式传输也能显著改善用户体验（UX），尤其是在应对大语言模型存在延迟的情况下。

借助 LangChain 流式传输可实现以下功能：

流式传输智能体执行进度—— 在智能体每一步执行后获取状态更新。
流式传输大语言模型令牌—— 在语言模型令牌生成时实时流式传输。
流式传输思考 / 推理令牌—— 在模型生成推理内容时实时呈现。
流式传输自定义更新—— 发送用户自定义信号（例如 "Fetched 10/100 records"）。
流式传输多种模式—— 可选择 updates（智能体执行进度）、messages（大语言模型令牌 + 元数据）或 custom（任意用户数据）。

2. 流式模式选择

updates：在每个智能体步骤后流式传输状态更新。若在同一步骤中产生多次更新（例如运行多个节点），这些更新将分别进行流式传输。
messages：从调用了大语言模型的任意图节点中，流式传输(token, metadata)元组。
custom：使用流式写入器从图节点内部流式传输自定义数据。

(1) update与Agent进程

带工具的Agent的信息流动，可以简化为经过三次update。首先。LLM node会返回带有工具调用的AIMessage，然后Tool Node会返回带有工具执行结果的ToolMessage（当然，这里也可以是Command，详细的信息我们在后面的ToolNode再学），最后LLM node再做最终的AI response：

from langchain.agents import create_agent


def get_weather(city: str) -> str:
    """Get weather for a given city."""

    return f"It's always sunny in {city}!"

agent = create_agent(
    model="gpt-5-nano",
    tools=[get_weather],
)
for chunk in agent.stream(
    {"messages": [{"role": "user", "content": "What is the weather in SF?"}]},
    stream_mode="updates",
    version="v2",
):
    if chunk["type"] == "updates":
        for step, data in chunk["data"].items():
            print(f"step: {step}")
            print(f"content: {data['messages'][-1].content_blocks}")

看到的输出类似这样：

step: model
content: [{'type': 'tool_call', 'name': 'get_weather', 'args': {'city': 'San Francisco'}, 'id': 'call_OW2NYNsNSKhRZpjW0wm2Aszd'}]

step: tools
content: [{'type': 'text', 'text': "It's always sunny in San Francisco!"}]

step: model
content: [{'type': 'text', 'text': 'It's always sunny in San Francisco!'}]

(2) messages与LLM token

若要流式传输大语言模型生成的令牌，请使用stream_mode="messages"。下方你可以看到智能体流式调用工具的输出以及最终响应：

from langchain.agents import create_agent


def get_weather(city: str) -> str:
    """Get weather for a given city."""

    return f"It's always sunny in {city}!"

agent = create_agent(
    model="gpt-5-nano",
    tools=[get_weather],
)
for chunk in agent.stream(
    {"messages": [{"role": "user", "content": "What is the weather in SF?"}]},
    stream_mode="messages",
    version="v2",
):
    if chunk["type"] == "messages":
        token, metadata = chunk["data"]
        print(f"node: {metadata['langgraph_node']}")
        print(f"content: {token.content_blocks}")
        print("\n")

输出

node: model
content: [{'type': 'tool_call_chunk', 'id': 'call_vbCyBcP8VuneUzyYlSBZZsVa', 'name': 'get_weather', 'args': '', 'index': 0}]


node: model
content: [{'type': 'tool_call_chunk', 'id': None, 'name': None, 'args': '{"', 'index': 0}]


node: model
content: [{'type': 'tool_call_chunk', 'id': None, 'name': None, 'args': 'city', 'index': 0}]


node: model
content: [{'type': 'tool_call_chunk', 'id': None, 'name': None, 'args': '":"', 'index': 0}]


node: model
content: [{'type': 'tool_call_chunk', 'id': None, 'name': None, 'args': 'San', 'index': 0}]


node: model
content: [{'type': 'tool_call_chunk', 'id': None, 'name': None, 'args': ' Francisco', 'index': 0}]


node: model
content: [{'type': 'tool_call_chunk', 'id': None, 'name': None, 'args': '"}', 'index': 0}]


node: model
content: []


node: tools
content: [{'type': 'text', 'text': "It's always sunny in San Francisco!"}]


node: model
content: []


node: model
content: [{'type': 'text', 'text': 'Here'}]


node: model
content: [{'type': 'text', 'text': ''s'}]


node: model
content: [{'type': 'text', 'text': ' what'}]


node: model
content: [{'type': 'text', 'text': ' I'}]


node: model
content: [{'type': 'text', 'text': ' got'}]


node: model
content: [{'type': 'text', 'text': ':'}]


node: model
content: [{'type': 'text', 'text': ' "'}]


node: model
content: [{'type': 'text', 'text': "It's"}]


node: model
content: [{'type': 'text', 'text': ' always'}]


node: model
content: [{'type': 'text', 'text': ' sunny'}]


node: model
content: [{'type': 'text', 'text': ' in'}]


node: model
content: [{'type': 'text', 'text': ' San'}]


node: model
content: [{'type': 'text', 'text': ' Francisco'}]


node: model
content: [{'type': 'text', 'text': '!"\n\n'}]

(3) custom

自定义流式信息怎么写。若要在工具执行时流式传输更新信息，可使用get_stream_writer。

from langchain.agents import create_agent
from langgraph.config import get_stream_writer  


def get_weather(city: str) -> str:
    """Get weather for a given city."""
    writer = get_stream_writer()
    # stream any arbitrary data
    writer(f"Looking up data for city: {city}")
    writer(f"Acquired data for city: {city}")
    return f"It's always sunny in {city}!"

agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[get_weather],
)

for chunk in agent.stream(
    {"messages": [{"role": "user", "content": "What is the weather in SF?"}]},
    stream_mode="custom",
    version="v2",
):
    if chunk["type"] == "custom":
        print(chunk["data"])

输出

Looking up data for city: San Francisco
Acquired data for city: San Francisco

(4) 多重模式

你可以通过将流模式以列表形式传递来指定多种流模式：stream_mode=["updates", "custom"]。每个流式数据块都是一个包含type、ns和data键的StreamPart字典。使用chunk["type"]来确定流模式，并通过chunk["data"]访问有效载荷。

from langchain.agents import create_agent
from langgraph.config import get_stream_writer


def get_weather(city: str) -> str:
    """Get weather for a given city."""
    writer = get_stream_writer()
    writer(f"Looking up data for city: {city}")
    writer(f"Acquired data for city: {city}")
    return f"It's always sunny in {city}!"

agent = create_agent(
    model="gpt-5-nano",
    tools=[get_weather],
)

for chunk in agent.stream(
    {"messages": [{"role": "user", "content": "What is the weather in SF?"}]},
    stream_mode=["updates", "custom"],
    version="v2",
):
    print(f"stream_mode: {chunk['type']}")
    print(f"content: {chunk['data']}")
    print("\n")

输出

stream_mode: updates
content: {'model': {'messages': [AIMessage(content='', response_metadata={'token_usage': {'completion_tokens': 280, 'prompt_tokens': 132, 'total_tokens': 412, 'completion_tokens_details': {'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 256, 'rejected_prediction_tokens': 0}, 'prompt_tokens_details': {'audio_tokens': 0, 'cached_tokens': 0}}, 'model_provider': 'openai', 'model_name': 'gpt-5-nano-2025-08-07', 'system_fingerprint': None, 'id': 'chatcmpl-C9tlgBzGEbedGYxZ0rTCz5F7OXpL7', 'service_tier': 'default', 'finish_reason': 'tool_calls', 'logprobs': None}, id='lc_run--480c07cb-e405-4411-aa7f-0520fddeed66-0', tool_calls=[{'name': 'get_weather', 'args': {'city': 'San Francisco'}, 'id': 'call_KTNQIftMrl9vgNwEfAJMVu7r', 'type': 'tool_call'}], usage_metadata={'input_tokens': 132, 'output_tokens': 280, 'total_tokens': 412, 'input_token_details': {'audio': 0, 'cache_read': 0}, 'output_token_details': {'audio': 0, 'reasoning': 256}})]}}


stream_mode: custom
content: Looking up data for city: San Francisco


stream_mode: custom
content: Acquired data for city: San Francisco


stream_mode: updates
content: {'tools': {'messages': [ToolMessage(content="It's always sunny in San Francisco!", name='get_weather', tool_call_id='call_KTNQIftMrl9vgNwEfAJMVu7r')]}}


stream_mode: updates
content: {'model': {'messages': [AIMessage(content='San Francisco weather: It's always sunny in San Francisco!\n\n', response_metadata={'token_usage': {'completion_tokens': 764, 'prompt_tokens': 168, 'total_tokens': 932, 'completion_tokens_details': {'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 704, 'rejected_prediction_tokens': 0}, 'prompt_tokens_details': {'audio_tokens': 0, 'cached_tokens': 0}}, 'model_provider': 'openai', 'model_name': 'gpt-5-nano-2025-08-07', 'system_fingerprint': None, 'id': 'chatcmpl-C9tljDFVki1e1haCyikBptAuXuHYG', 'service_tier': 'default', 'finish_reason': 'stop', 'logprobs': None}, id='lc_run--acbc740a-18fe-4a14-8619-da92a0d0ee90-0', usage_metadata={'input_tokens': 168, 'output_tokens': 764, 'total_tokens': 932, 'input_token_details': {'audio': 0, 'cache_read': 0}, 'output_token_details': {'audio': 0, 'reasoning': 704}})]}}

3. 常见使用场景

(1) 流式传输思考/推理token

可以通过筛选标准内容块中type为"reasoning"的内容，实时流式传输这些生成的思考 / 推理令牌。

若要流式传输智能体的思考令牌，可使用stream_mode="messages"并筛选推理内容块。

from langchain.agents import create_agent
from langchain.messages import AIMessageChunk
from langchain_anthropic import ChatAnthropic
from langchain_core.runnables import Runnable


def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"


model = ChatAnthropic(
    model_name="claude-sonnet-4-6",
    timeout=None,
    stop=None,
    thinking={"type": "enabled", "budget_tokens": 5000},
)
agent: Runnable = create_agent(
    model=model,
    tools=[get_weather],
)

for token, metadata in agent.stream(
    {"messages": [{"role": "user", "content": "What is the weather in SF?"}]},
    stream_mode="messages",
):
    if not isinstance(token, AIMessageChunk):
        continue
    reasoning = [b for b in token.content_blocks if b["type"] == "reasoning"]
    text = [b for b in token.content_blocks if b["type"] == "text"]
    if reasoning:
        print(f"[thinking] {reasoning[0]['reasoning']}", end="")
    if text:
        print(text[0]["text"], end="")

输出会类似：

[thinking] The user is asking about the weather in San Francisco. I have a tool
[thinking]  available to get this information. Let me call the get_weather tool
[thinking]  with "San Francisco" as the city parameter.
The weather in San Francisco is: It's always sunny in San Francisco!

无论模型提供商是谁，其工作原理均保持一致 ——LangChain 会通过content_blocks属性，将各提供商专属的格式（Anthropic 的thinking模块、OpenAI 的reasoning摘要等）统一规范化为标准的"reasoning"内容块类型。

(2) 流式工具调用

可能需要同时流式传输以下两类内容：

工具调用生成过程中的部分 JSON 数据
执行完毕且已解析的完整工具调用结果

指定stream_mode="messages"将流式传输智能体中所有大语言模型调用生成的增量消息片段

若这些消息在状态中被追踪（如create_agent的模型节点中），可使用stream_mode=["messages", "updates"]，通过状态更新获取完整消息（如下方示例所示）。
若这些消息未在状态中被追踪，则可使用自定义更新，或在流式循环过程中聚合消息片段（下一节）。

代码示例如下：

from typing import Any

from langchain.agents import create_agent
from langchain.messages import AIMessage, AIMessageChunk, AnyMessage, ToolMessage


def get_weather(city: str) -> str:
    """Get weather for a given city."""

    return f"It's always sunny in {city}!"


agent = create_agent("openai:gpt-5.2", tools=[get_weather])


def _render_message_chunk(token: AIMessageChunk) -> None:
    if token.text:
        print(token.text, end="|")
    if token.tool_call_chunks:
        print(token.tool_call_chunks)
    # N.B. all content is available through token.content_blocks


def _render_completed_message(message: AnyMessage) -> None:
    if isinstance(message, AIMessage) and message.tool_calls:
        print(f"Tool calls: {message.tool_calls}")
    if isinstance(message, ToolMessage):
        print(f"Tool response: {message.content_blocks}")


input_message = {"role": "user", "content": "What is the weather in Boston?"}
for chunk in agent.stream(
    {"messages": [input_message]},
    stream_mode=["messages", "updates"],
    version="v2",
):
    if chunk["type"] == "messages":
        token, metadata = chunk["data"]
        if isinstance(token, AIMessageChunk):
            _render_message_chunk(token)
    elif chunk["type"] == "updates":
        for source, update in chunk["data"].items():
            if source in ("model", "tools"):  # `source` captures node name
                _render_completed_message(update["messages"][-1])

输出

[{'name': 'get_weather', 'args': '', 'id': 'call_D3Orjr89KgsLTZ9hTzYv7Hpf', 'index': 0, 'type': 'tool_call_chunk'}]
[{'name': None, 'args': '{"', 'id': None, 'index': 0, 'type': 'tool_call_chunk'}]
[{'name': None, 'args': 'city', 'id': None, 'index': 0, 'type': 'tool_call_chunk'}]
[{'name': None, 'args': '":"', 'id': None, 'index': 0, 'type': 'tool_call_chunk'}]
[{'name': None, 'args': 'Boston', 'id': None, 'index': 0, 'type': 'tool_call_chunk'}]
[{'name': None, 'args': '"}', 'id': None, 'index': 0, 'type': 'tool_call_chunk'}]
Tool calls: [{'name': 'get_weather', 'args': {'city': 'Boston'}, 'id': 'call_D3Orjr89KgsLTZ9hTzYv7Hpf', 'type': 'tool_call'}]
Tool response: [{'type': 'text', 'text': "It's always sunny in Boston!"}]
The| weather| in| Boston| is| **|sun|ny|**|.|

(3) 访问已完成信息

(4) Steaming with human-in-the-loop

(5) Streaming from sub-agents

4. 禁用streaming

有些时候需要禁用单个模型token的流式输出，比如：

使用多智能体系统时，控制哪些智能体进行输出流式传输
将支持流式传输的模型与不支持该功能的模型混合使用
部署至LangSmith平台，且希望阻止特定模型的输出流式传输至客户端

这样可以直接在模型构建的时候传入streaming=False完成。

5. v2流式输出格式

其实你可以注意到，前面已经用到了version = "v2"了，其实v2和v1（默认）的区别就在于，前者有统一的输出格式，每个StreamPart都是包含type、ns、data作为key的输出，而v1则会传回类似(mode,data)的元组，需要你手动unpack。

此外，v2 格式还改进了invoke()方法 —— 它会返回一个包含.value和.interrupts属性的GraphOutput对象，将状态与中断元数据清晰地分离开来：

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Hello"}]},
    version="v2",
)
print(result.value)       # state (dict, Pydantic model, or dataclass)
print(result.interrupts)  # tuple of Interrupt objects (empty if none)

RAG 索引优化：上下文拓展与结构化索引

Sun, 22 Mar 2026 00:00:00 GMT

这一篇承接前面的 Naive-RAG 实战。目标不是切换框架，而是把 LlamaIndex 在索引层提供的两个思路吸收下来，再映射回自己当前的 LangChain + Milvus + FastAPI 主线。

RAG - 索引优化

1. LlamaIndex

这一章开始接触 LlamaIndex。它和 LangChain 的定位不完全一样，LangChain 更像一个通用的 LLM 应用框架，链、工具、Agent、RAG 都能做；而 LlamaIndex 更聚焦在“怎么把数据接进 LLM”，也就是文档、索引、检索、查询这一套抽象会更清楚一些。

不过，我当前的主线仍然是 LangChain + Milvus + FastAPI，所以这里没必要切到另一个框架去重做一遍 demo。更合适的做法是，把 LlamaIndex 里面对 RAG 有启发的索引优化思想吸收下来，看懂它到底在解决什么问题，之后再映射回我自己的项目。

这一章主要记两种索引优化：

上下文拓展
结构化索引

2. 上下文拓展

RAG 里一直有一个很经典的矛盾：如果 chunk 切得很小，检索时通常更精确，因为语义更集中，更容易命中真正相关的那一句或那一小段；但与此同时，小 chunk 给 LLM 的上下文又太少，最后回答可能不完整，甚至语义不连贯。反过来，如果 chunk 一开始就切得很大，那上下文当然更完整，但检索时又容易混入很多无关信息，召回虽然“看起来相关”，其实噪音会明显增加。

LlamaIndex 针对这个问题给出的一个很直观的思路就是句子窗口检索（Sentence Window Retrieval）。它不是简单地说“应该切大一点”或者“应该切小一点”，而是把检索阶段和生成阶段分开看：检索时，仍然用非常小的单位去找；但在交给 LLM 生成答案之前，再把它恢复成一个更大的上下文窗口。

它的核心代码并不复杂：

# 1. 加载文档
documents = SimpleDirectoryReader(
    input_files=["../../data/C3/pdf/IPCC_AR6_WGII_Chapter03.pdf"]
).load_data()

# 2. 创建句子窗口索引
node_parser = SentenceWindowNodeParser.from_defaults(
    window_size=3,
    window_metadata_key="window",
    original_text_metadata_key="original_text",
)
sentence_nodes = node_parser.get_nodes_from_documents(documents)
sentence_index = VectorStoreIndex(sentence_nodes)

# 3. 构建查询引擎
sentence_query_engine = sentence_index.as_query_engine(
    similarity_top_k=2,
    node_postprocessors=[
        MetadataReplacementPostProcessor(target_metadata_key="window")
    ],
)

乍一看其实也没有什么魔法，核心就两步：

第一步，SentenceWindowNodeParser 会把文档切成一个个句子。注意这里不是普通的固定长度切块，而是按句子切。每个句子都会变成一个节点，同时它还会额外保存一段“窗口”信息，也就是这个句子前后若干句组成的上下文。

第二步，在真正查询时，检索器先检索的仍然是这些小句子节点。也就是说，相似度匹配依然发生在“小而精”的粒度上。等命中之后，再通过 MetadataReplacementPostProcessor 把节点里原本那一句话，替换成之前存在 metadata 里的整段窗口文本。这样最后送给 LLM 的就不再是孤立的一句话，而是带有前后文的一小段内容。

所以这个方法的本质可以直接记成一句话：

检索时用小块保证精度，生成时用大块补足上下文。

它解决的不是“向量模型不够强”，而是 chunk 粒度设计的矛盾。

LlamaIndex 底层怎么做这件事，其实想清楚也不难。它先把文档拆成句子列表，然后遍历每个句子，对第 i 个句子来说，去取前后若干句，把它们拼起来存进 metadata 里。注意这里很关键的一点是：真正参与 embedding 的，还是当前句子本身；窗口信息只是被当成附加元数据，供后处理阶段替换使用。这样才能保证检索时保持高精度，而不是一开始就把大窗口拿去做 embedding。

这一点对我很有启发，因为我现在自己的 Naive-RAG 做法是：

先按 markdown 标题切
再对过长 chunk 递归切分
检索到什么 chunk，就直接把什么 chunk 交给 LLM

这个方案能跑，而且已经能做出一个端到端 demo。但它的问题也很明显：如果后面遇到那种“某一句特别关键，但单句上下文不足”的情况，我就很容易在两个坏选项之间摇摆：

把 chunk 切得更小，检索更准，但回答更碎
把 chunk 切得更大，上下文更多，但噪音上来

句子窗口检索给的启发其实非常直接：检索粒度和生成粒度，不一定必须相同。
这并不是 LlamaIndex 专属能力，换到我现在的 LangChain + Milvus 项目里也完全能借鉴。比如以后我可以：

用更小粒度的句子/短段落建索引
在 metadata 里保存所属段落或者前后句窗口
检索时命中小块
返回给 LLM 时再替换成更大的文本窗口

所以这一节真正值得记住的，不是某个类名，而是这个思路本身。

3. 结构化索引

前面的上下文拓展，主要解决的是 chunk 粒度矛盾；而结构化索引解决的是另一个问题：知识库大了以后，不能总是对全库做无差别检索。

如果知识库里只有几篇文档，那对所有 chunk 直接做 top-k 向量搜索问题不大。但当文档库规模变大，例如几百份 PDF、多个表格、多个年份、多个专题，很多问题其实从一开始就只和一小部分数据有关。这个时候，如果还是在全库里盲搜，不仅效率差，还很容易被无关 chunk 干扰。

这时候就要引入结构化索引。它的本质不是一种新向量模型，而是：除了文本和向量，还给每个 chunk 附加结构化元数据，用这些元数据先做过滤或路由。

这些元数据可以很简单，比如：

文件名
文档类型
日期
作者
一级、二级、三级标题
自定义标签

然后在检索时走两步：

先根据 metadata 把搜索范围缩小
再在这个缩小后的候选集合里做向量检索

这种“先过滤，再搜索”的思路，在数据规模变大后会非常有用。

这里其实和我当前项目已经能直接对应上了。因为在第二章我就用了 MarkdownHeaderTextSplitter，它会自动把 h1 / h2 / h3 写进每个 chunk 的 metadata 里。后面入 Milvus 的时候，我也把这些字段一起存进去了。所以严格来说，我现在的系统虽然还只是 Naive-RAG，但已经有了结构化索引的雏形。

换句话说：

基于文档结构切块，并保留标题 metadata，本身就是结构化索引的一部分。

这意味着后面我完全可以继续往前走，而不是另起一套：

只在某一篇文档里搜索
只在某个一级标题下搜索
只在某个章节范围里搜索

这些都属于结构化索引的直接应用。

LlamaIndex 在这一块常见会讲到两种比较典型的实现方式。

第一种比较直白，就是 metadata filtering。
也就是先根据结构化信息筛一遍，再做向量搜索。比如问题是“请总结 2023 年第二季度财报里关于 AI 的论述”，那就没必要在整个知识库乱搜，而是先限定在：

文档类型 = 财报
年份 = 2023
季度 = Q2

然后再做相似度搜索。

第二种更进一步，是“先路由，再进入目标数据源做检索”，也就是递归检索或者分层检索的思路。LlamaIndex 经常举的例子是多工作表 Excel：每个 sheet 单独是一个数据源，先用摘要节点判断问题属于哪个表，再进入那个表里继续查询。

这个例子的代码挺长，但真正需要记住的不是 RecursiveRetriever 或者 PandasQueryEngine 的具体调用，而是它背后的逻辑：

先为每个子数据源准备摘要
用摘要做第一层路由
命中后再进入目标数据源做第二层查询

也就是说，这种方法的核心不是“递归”这个形式，而是：

先决定去哪搜，再决定怎么搜。

这个思路如果放回我自己的项目里，其实也很容易理解。比如以后如果我不只是有一套 RL 笔记，而是有：

强化学习
RAG
LangChain
系统设计

几套完全不同的知识库，那我就没必要每次都把所有内容放在一起无差别检索。更合理的做法是，先判断这个问题大概属于哪个知识域，再进入对应知识域检索。这就是结构化索引更进一步的价值。

另外，LlamaIndex 在多表格例子里还用了 PandasQueryEngine 这类能让 LLM 生成 Pandas 代码并执行的工具。这个思路很强，但它也带来明显的安全问题，因为本质上已经接近“让模型生成代码然后执行”。所以这里我更应该记住的是：

结构化索引和路由是有价值的
但具体实现方式要考虑安全性

对于我现在的主线来说，最实际的落点还是前面那条：

优先把 metadata 用起来，先做过滤，再做向量检索。

4. 关于框架

框架是加速开发的强大工具，是帮助我们快速跨越技术鸿沟的“桥梁”。但任何桥梁都有其设计边界和局限性。我们的目标不是成为一个熟练的“过桥者”，而是成为一个懂得如何设计和建造桥梁的“工程师”。

如果希望深入某个框架的细节，官方文档永远是最好的选择。但是现在的学习，是为了建立起关于RAG的坚实知识体系，这样在切换工具的时候也能游刃有余。

LangChain 核心组件 06：Structured Output

Sat, 21 Mar 2026 00:00:00 GMT

结构化输出我放在 Agents 前面，是因为它本质上是“让模型结果进入程序逻辑”的桥。等这个概念清楚了，再去看 Agent 里的 response_format 就不会突兀。

结构化输出使得智能体能够以特定、可预测的格式返回数据。你无需解析自然语言响应，而是可以直接获取以 JSON 对象、Pydantic 模型或数据类形式呈现的结构化数据，供应用程序直接使用。

LangChain 的create_agent可自动处理结构化输出。用户设置所需的结构化输出模式，当模型生成结构化数据时，该数据会被捕获、验证，并以structured_response为键名返回至智能体状态中。

def create_agent(
    ...
    response_format: Union[
        ToolStrategy[StructuredResponseT],
        ProviderStrategy[StructuredResponseT],
        type[StructuredResponseT],
        None,
    ]

1. 响应格式

使用response_format控制智能体返回结构化数据的方式：

ToolStrategy[StructuredResponseT]：通过工具调用实现结构化输出
ProviderStrategy[StructuredResponseT]：采用服务提供商原生结构化输出
type[StructuredResponseT]：架构类型 —— 根据模型能力自动选择最优策略
None：未明确请求结构化输出

当直接提供架构类型时，LangChain 会自动选择：

ProviderStrategy（若所选模型及服务提供商支持原生结构化输出，例如 OpenAI、Anthropic (Claude)或xAI (Grok)）。
ToolStrategy（适用于其他所有模型）。

2. Provider strategy

部分模型提供商通过其 API 原生支持结构化输出（例如 OpenAI、xAI（Grok）、Gemini、Anthropic（Claude））。在可用的情况下，这是最可靠的方法。

要使用此策略，请配置一个ProviderStrategy：

class ProviderStrategy(Generic[SchemaT]):
    schema: type[SchemaT]
    strict: bool | None = None

定义结构化输出格式的模式。支持：

Pydantic 模型：带有字段验证的BaseModel子类，返回经过验证的 Pydantic 实例。
数据类：带有类型注解的 Python 数据类，返回字典。
类型字典：类型化字典类，返回字典。
JSON 模式：包含 JSON 模式规范的字典，返回字典。

下面提供这四种情况的代码

from pydantic import BaseModel, Field
from langchain.agents import create_agent


class ContactInfo(BaseModel):
    """Contact information for a person."""
    name: str = Field(description="The name of the person")
    email: str = Field(description="The email address of the person")
    phone: str = Field(description="The phone number of the person")

agent = create_agent(
    model="gpt-5",
    response_format=ContactInfo  # Auto-selects ProviderStrategy
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Extract contact info from: John Doe, john@example.com, (555) 123-4567"}]
})

print(result["structured_response"])
# ContactInfo(name='John Doe', email='john@example.com', phone='(555) 123-4567')

from dataclasses import dataclass
from langchain.agents import create_agent


@dataclass
class ContactInfo:
    """Contact information for a person."""
    name: str # The name of the person
    email: str # The email address of the person
    phone: str # The phone number of the person

agent = create_agent(
    model="gpt-5",
    tools=tools,
    response_format=ContactInfo  # Auto-selects ProviderStrategy
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Extract contact info from: John Doe, john@example.com, (555) 123-4567"}]
})

result["structured_response"]
# {'name': 'John Doe', 'email': 'john@example.com', 'phone': '(555) 123-4567'}

from typing_extensions import TypedDict
from langchain.agents import create_agent


class ContactInfo(TypedDict):
    """Contact information for a person."""
    name: str # The name of the person
    email: str # The email address of the person
    phone: str # The phone number of the person

agent = create_agent(
    model="gpt-5",
    tools=tools,
    response_format=ContactInfo  # Auto-selects ProviderStrategy
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Extract contact info from: John Doe, john@example.com, (555) 123-4567"}]
})

result["structured_response"]
# {'name': 'John Doe', 'email': 'john@example.com', 'phone': '(555) 123-4567'}

from langchain.agents import create_agent


contact_info_schema = {
    "type": "object",
    "description": "Contact information for a person.",
    "properties": {
        "name": {"type": "string", "description": "The name of the person"},
        "email": {"type": "string", "description": "The email address of the person"},
        "phone": {"type": "string", "description": "The phone number of the person"}
    },
    "required": ["name", "email", "phone"]
}

agent = create_agent(
    model="gpt-5",
    tools=tools,
    response_format=ProviderStrategy(contact_info_schema)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Extract contact info from: John Doe, john@example.com, (555) 123-4567"}]
})

result["structured_response"]
# {'name': 'John Doe', 'email': 'john@example.com', 'phone': '(555) 123-4567'}

3. Tool calling strategy

对于不支持原生结构化输出的模型，LangChain 会通过工具调用来实现相同的效果。该方法适用于所有支持工具调用的模型（大多数现代模型）。

要使用此策略，请配置ToolStrategy：

class ToolStrategy(Generic[SchemaT]):
    schema: type[SchemaT]
    tool_message_content: str | None
    handle_errors: Union[
        bool,
        str,
        type[Exception],
        tuple[type[Exception], ...],
        Callable[[Exception], str],
    ]

同样，这里的schema模版支持以下：

Pydantic 模型：BaseModel 子类，具备字段校验功能，返回校验后的 Pydantic 实例。
数据类：带有类型注解的 Python 数据类，返回字典。
类型字典：类型化字典类，返回字典。
JSON 模式：符合 JSON 模式规范的字典，返回字典。
联合类型：多种模式选项，模型会根据上下文选择最合适的模式。

这里分别提供五种情况的示例代码：

from pydantic import BaseModel, Field
from typing import Literal
from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy


class ProductReview(BaseModel):
    """Analysis of a product review."""
    rating: int | None = Field(description="The rating of the product", ge=1, le=5)
    sentiment: Literal["positive", "negative"] = Field(description="The sentiment of the review")
    key_points: list[str] = Field(description="The key points of the review. Lowercase, 1-3 words each.")

agent = create_agent(
    model="gpt-5",
    tools=tools,
    response_format=ToolStrategy(ProductReview)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Analyze this review: 'Great product: 5 out of 5 stars. Fast shipping, but expensive'"}]
})
result["structured_response"]
# ProductReview(rating=5, sentiment='positive', key_points=['fast shipping', 'expensive'])

from dataclasses import dataclass
from typing import Literal
from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy


@dataclass
class ProductReview:
    """Analysis of a product review."""
    rating: int | None  # The rating of the product (1-5)
    sentiment: Literal["positive", "negative"]  # The sentiment of the review
    key_points: list[str]  # The key points of the review

agent = create_agent(
    model="gpt-5",
    tools=tools,
    response_format=ToolStrategy(ProductReview)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Analyze this review: 'Great product: 5 out of 5 stars. Fast shipping, but expensive'"}]
})
result["structured_response"]
# {'rating': 5, 'sentiment': 'positive', 'key_points': ['fast shipping', 'expensive']}

from typing import Literal
from typing_extensions import TypedDict
from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy


class ProductReview(TypedDict):
    """Analysis of a product review."""
    rating: int | None  # The rating of the product (1-5)
    sentiment: Literal["positive", "negative"]  # The sentiment of the review
    key_points: list[str]  # The key points of the review

agent = create_agent(
    model="gpt-5",
    tools=tools,
    response_format=ToolStrategy(ProductReview)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Analyze this review: 'Great product: 5 out of 5 stars. Fast shipping, but expensive'"}]
})
result["structured_response"]
# {'rating': 5, 'sentiment': 'positive', 'key_points': ['fast shipping', 'expensive']}

from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy


product_review_schema = {
    "type": "object",
    "description": "Analysis of a product review.",
    "properties": {
        "rating": {
            "type": ["integer", "null"],
            "description": "The rating of the product (1-5)",
            "minimum": 1,
            "maximum": 5
        },
        "sentiment": {
            "type": "string",
            "enum": ["positive", "negative"],
            "description": "The sentiment of the review"
        },
        "key_points": {
            "type": "array",
            "items": {"type": "string"},
            "description": "The key points of the review"
        }
    },
    "required": ["sentiment", "key_points"]
}

agent = create_agent(
    model="gpt-5",
    tools=tools,
    response_format=ToolStrategy(product_review_schema)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Analyze this review: 'Great product: 5 out of 5 stars. Fast shipping, but expensive'"}]
})
result["structured_response"]
# {'rating': 5, 'sentiment': 'positive', 'key_points': ['fast shipping', 'expensive']}

from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy


product_review_schema = {
    "type": "object",
    "description": "Analysis of a product review.",
    "properties": {
        "rating": {
            "type": ["integer", "null"],
            "description": "The rating of the product (1-5)",
            "minimum": 1,
            "maximum": 5
        },
        "sentiment": {
            "type": "string",
            "enum": ["positive", "negative"],
            "description": "The sentiment of the review"
        },
        "key_points": {
            "type": "array",
            "items": {"type": "string"},
            "description": "The key points of the review"
        }
    },
    "required": ["sentiment", "key_points"]
}

agent = create_agent(
    model="gpt-5",
    tools=tools,
    response_format=ToolStrategy(product_review_schema)
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "Analyze this review: 'Great product: 5 out of 5 stars. Fast shipping, but expensive'"}]
})
result["structured_response"]
# {'rating': 5, 'sentiment': 'positive', 'key_points': ['fast shipping', 'expensive']}

4. Custom tool message content

tool_message_content 参数允许你自定义生成结构化输出时，显示在对话历史中的消息内容。效果如下：

from pydantic import BaseModel, Field
from typing import Literal
from langchain.agents import create_agent
from langchain.agents.structured_output import ToolStrategy


class MeetingAction(BaseModel):
    """Action items extracted from a meeting transcript."""
    task: str = Field(description="The specific task to be completed")
    assignee: str = Field(description="Person responsible for the task")
    priority: Literal["low", "medium", "high"] = Field(description="Priority level")

agent = create_agent(
    model="gpt-5",
    tools=[],
    response_format=ToolStrategy(
        schema=MeetingAction,
        tool_message_content="Action item captured and added to meeting notes!"
    )
)

agent.invoke({
    "messages": [{"role": "user", "content": "From our meeting: Sarah needs to update the project timeline as soon as possible"}]
})

================================ Human Message =================================

From our meeting: Sarah needs to update the project timeline as soon as possible
================================== Ai Message ==================================
Tool Calls:
  MeetingAction (call_1)
 Call ID: call_1
  Args:
    task: Update the project timeline
    assignee: Sarah
    priority: high
================================= Tool Message =================================
Name: MeetingAction

Action item captured and added to meeting notes!

如果没有tool_message_content，最终的ToolMessage会像这样：

================================= Tool Message =================================
Name: MeetingAction

Returning structured response: {'task': 'update the project timeline', 'assignee': 'Sarah', 'priority': 'high'}

5. 错误处理

先skip

RAG 混合检索：稀疏、密集与 Milvus 实现

Sat, 21 Mar 2026 00:00:00 GMT

这一篇开始正式进入“检索优化”阶段。前面的重点是先把索引和基础检索链路搭起来，这一篇则开始回答一个更现实的问题：只靠单路 dense 检索，什么时候会不够。

RAG - 检索优化

一、混合检索

混合检索（Hybrid Search）是一种结合了稀疏向量（Sparse Vectors）和密集向量（Dense Vectors）优势的先进搜索技术。旨在同时利用稀疏向量的关键词精确匹配能力和密集向量的语义理解能力，以克服单一向量检索的局限性，从而在各种搜索场景下提供更准确、更鲁棒的检索结果。

1. 稀疏向量

稀疏向量，也常被称为“词法向量”，是基于词频统计的传统信息检索方法的数学表示。它通常是一个维度极高（与词汇表大小相当）但绝大多数元素为零的向量。经典方法包括one-hot、Bag of words、TF、TF-IDF、BM25等。

One-hot：先建一个词表，每个词对应固定位置，出现为1，不出现为2
Bag of Words：把一段文本表示成“词出现次数”的向量，比one-hot更进一步，能表示词频
TF（Term Frequency）：某个词在当前文档里出现得有多频繁。
TF-IDF（Term Frequency * Inverse Document Frequency）：在TF的基础又加了一层全局分布度，思想是一个词在当前文档里出现很多次，说明它对这篇文档重要。相反如果它在所有文档里都很常见，那它区分度不高，应该降权。
BM25：可以看成是对TF-IDF的进一步改进，是检索算法中非常经典的排序函数，它综合考虑“查询词是否出现在文档里”、“出现多少次”、“词本身是否稀有”、“文档长度是否过长”，我们可以看一下公式： $$ Score(Q, D) = \sum_{i=1}^{n} IDF(q_i)\cdot \frac{f(q_i, D)(k_1+1)} {f(q_i, D) + k_1\left(1-b+b\cdot\frac{|D|}{avgdl}\right)} $$
- $IDF(q_i)$：查询词 $q_i$ 的逆文档频率，用于衡量一个词的普遍程度。越常见的词，IDF 值越低。如果一个词很少见，比如某个专有术语、型号名、算法名，那它更能说明“这篇文档和查询强相关”，贡献就高。
- $f(q_i, D)$：查询词 $q_i$ 在文档 $D$ 中的词频。但不是单纯越多越好，不是线性增长，会慢慢饱和。
- $|D|$：文档 $D$ 的长度。这是归一化修正要用的，否则长文本天然包含更多词更占便宜。
- $avgdl$：集合中所有文档的平均长度。
- $k_1, b$：可调节的超参数。$k_1$ 用于控制词频饱和度（一个词在文档中出现 10 次和 100 次，其重要性增长并非线性），$b$ 用于控制文档长度归一化的程度。

2. 密集向量

密集向量，也常被称为“语义向量”，是通过深度学习模型学习到的数据（如文本、图像）的低维、稠密的浮点数表示。这些向量旨在将原始数据映射到一个连续的、充满意义的“语义空间”中来捕捉“语义”或“概念”。

其主要优点是能够理解同义词、近义词和上下文关系，泛化能力强，在语义搜索任务中表现卓越。但缺点也同样明显：可解释性差（向量中的每个维度通常没有具体的物理意义），需要大量数据和算力进行模型训练，且对于未登录词（OOV）的处理相对困难。

OOV（Out-of-Vocabulary）未登录词：指在模型训练时没有出现在词汇表中，但在实际使用时遇到的新词汇。例如，如果模型训练时词汇表中没有"ChatGPT"这个词，那么在实际应用中遇到它时就是OOV。传统的稀疏向量方法（如BM25）对OOV词汇会完全忽略，而现代的密集向量方法通过子词分割（如BPE、WordPiece）可以更好地处理OOV问题。

二、混合检索的方法

混合检索通常并行执行两种检索算法，然后将两组异构的结果集融合成一个统一的排序列表。以下是两种主流的融合策略。

1. 倒数排序融合 (Reciprocal Rank Fusion, RRF)

RRF 不关心不同检索系统的原始得分，只关心每个文档在各自结果集中的排名。其思想是：一个文档在不同检索系统中的排名越靠前，它的最终得分就越高。其计分公式为： $$ RRF_{score}(d) = \sum_{i=1}^{k} \frac{1}{rank_i(d) + c} $$

其中：

$d$ 是待评分的文档。
$k$ 是检索系统的数量（这里是 2，即稀疏和密集）。
$rank_i(d)$ 是文档 $d$ 在第 $i$ 个检索系统中的排名。
$c$ 是一个常数（通常设为 60），用于降低排名靠前文档的相对权重，实现更稳健的排名融合。

2. 加权线性组合

这种方法需要先将不同检索系统的得分进行归一化（例如，统一到 0-1 区间），然后通过一个权重参数 α 来进行线性组合。

$$ Hybrid_{score} = \alpha \cdot Dense_{score} + (1 - \alpha) \cdot Sparse_{score} $$

通过调整 α 的值，可以灵活地控制语义相似性与关键词匹配在最终排序中的贡献比例。例如，在电商搜索中，可以调高关键词的权重；而在智能问答中，则可以侧重于语义。

3. 区别、优势与局限

线性加权融合的是 dense 和 sparse 的原始分数，因此要求不同检索器的分数具有一定可比性；RRF 融合的是各检索器中的排名，不依赖分数尺度，因此通常更稳健，也更常用于实际的多路检索融合。

两种方法的优势与局限如下：

优势	局限
召回率与准确率高：能同时捕获关键词和语义，显著优于单一检索。	计算资源消耗大：需要同时维护和查询两套索引。
灵活性强：可通过融合策略和权重调整，适应不同业务场景。	参数调试复杂：融合权重等超参数需要反复实验调优。
容错性好：关键词检索可部分弥补向量模型对拼写错误或罕见词的敏感性。	可解释性仍是挑战：融合后的结果排序理由难以直观分析。

三、用Milvus实现混合检索

下面直接阅读实例代码即可

1. 定义Collection

import json
import os
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com"
import numpy as np
from pymilvus import connections, MilvusClient, FieldSchema, CollectionSchema, DataType, Collection, AnnSearchRequest, RRFRanker
from pymilvus.model.hybrid import BGEM3EmbeddingFunction

# 1. 初始化设置
COLLECTION_NAME = "dragon_hybrid_demo"
MILVUS_URI = "http://localhost:19530"  # 服务器模式
DATA_PATH = "../../data/C4/metadata/dragon.json"  # 相对路径
BATCH_SIZE = 50

# 2. 连接 Milvus 并初始化嵌入模型
print(f"--> 正在连接到 Milvus: {MILVUS_URI}")
connections.connect(uri=MILVUS_URI)

print("--> 正在初始化 BGE-M3 嵌入模型...")
ef = BGEM3EmbeddingFunction(use_fp16=False, device="cpu")
print(f"--> 嵌入模型初始化完成。密集向量维度: {ef.dim['dense']}")

# 3. 创建 Collection
milvus_client = MilvusClient(uri=MILVUS_URI)
if milvus_client.has_collection(COLLECTION_NAME):
    print(f"--> 正在删除已存在的 Collection '{COLLECTION_NAME}'...")
    milvus_client.drop_collection(COLLECTION_NAME)

fields = [
    FieldSchema(name="pk", dtype=DataType.VARCHAR, is_primary=True, auto_id=True, max_length=100),
    FieldSchema(name="img_id", dtype=DataType.VARCHAR, max_length=100),
    FieldSchema(name="path", dtype=DataType.VARCHAR, max_length=256),
    FieldSchema(name="title", dtype=DataType.VARCHAR, max_length=256),
    FieldSchema(name="description", dtype=DataType.VARCHAR, max_length=4096),
    FieldSchema(name="category", dtype=DataType.VARCHAR, max_length=64),
    FieldSchema(name="location", dtype=DataType.VARCHAR, max_length=128),
    FieldSchema(name="environment", dtype=DataType.VARCHAR, max_length=64),
    FieldSchema(name="sparse_vector", dtype=DataType.SPARSE_FLOAT_VECTOR),
    FieldSchema(name="dense_vector", dtype=DataType.FLOAT_VECTOR, dim=ef.dim["dense"])
]

# 如果集合不存在，则创建它及索引
if not milvus_client.has_collection(COLLECTION_NAME):
    print(f"--> 正在创建 Collection '{COLLECTION_NAME}'...")
    schema = CollectionSchema(fields, description="关于龙的混合检索示例")
    # 创建集合
    collection = Collection(name=COLLECTION_NAME, schema=schema, consistency_level="Strong")
    print("--> Collection 创建成功。")

    # 创建索引
    print("--> 正在为新集合创建索引...")
    sparse_index = {"index_type": "SPARSE_INVERTED_INDEX", "metric_type": "IP"}
    collection.create_index("sparse_vector", sparse_index)
    print("稀疏向量索引创建成功。")

    dense_index = {"index_type": "AUTOINDEX", "metric_type": "IP"}
    collection.create_index("dense_vector", dense_index)
    print("密集向量索引创建成功。")

collection = Collection(COLLECTION_NAME)
collection.load()
print(f"--> Collection '{COLLECTION_NAME}' 已加载到内存。")

2. BGE-M3双向量生成

BGE-M3 作为向量生成器，它能够同时生成稀疏向量和密集向量。

首先加载数据：

if collection.is_empty:
    print(f"--> Collection 为空，开始插入数据...")
    with open(DATA_PATH, 'r', encoding='utf-8') as f:
        dataset = json.load(f)

    docs, metadata = [], []
    for item in dataset:
        parts = [
            item.get('title', ''),
            item.get('description', ''),
            item.get('location', ''),
            item.get('environment', ''),
        ]
        docs.append(' '.join(filter(None, parts)))
        metadata.append(item)

然后，我们生成向量：

print("--> 正在生成向量嵌入...")
embeddings = ef(docs)
print("--> 向量生成完成。")

# 获取两种向量
sparse_vectors = embeddings["sparse"]    # 稀疏向量：词频统计
dense_vectors = embeddings["dense"]      # 密集向量：语义编码

最后，我们在Collection中批量插入数据：

# 为每个字段准备批量数据
img_ids = [doc["img_id"] for doc in metadata]
paths = [doc["path"] for doc in metadata]
titles = [doc["title"] for doc in metadata]
descriptions = [doc["description"] for doc in metadata]
categories = [doc["category"] for doc in metadata]
locations = [doc["location"] for doc in metadata]
environments = [doc["environment"] for doc in metadata]

# 插入数据
collection.insert([
    img_ids, paths, titles, descriptions, categories, locations, environments,
    sparse_vectors, dense_vectors
])
collection.flush()

前面实现过了Milvus，这里的代码阅读应该没什么困难，就是稍微麻烦了点。

3. 实现混合检索

milvus中已经封装好了RRF算法，首先，我们生成查询向量：

# 6. 执行搜索
search_query = "悬崖上的巨龙"
search_filter = 'category in ["western_dragon", "chinese_dragon", "movie_character"]'
top_k = 5

print(f"\n{'='*20} 开始混合搜索 {'='*20}")
print(f"查询: '{search_query}'")
print(f"过滤器: '{search_filter}'")

# 生成查询向量
query_embeddings = ef([search_query])
dense_vec = query_embeddings["dense"][0]
sparse_vec = query_embeddings["sparse"]._getrow(0)

然后，使用 RRF 算法进行混合检索，通过 milvus 封装的 RRFRanker 实现。RRFRanker 的核心参数是 k 值（默认60），用于控制 RRF 算法中的排序平滑程度：

# 定义搜索参数
search_params = {"metric_type": "IP", "params": {}}

# 先执行单独的搜索
print("\n--- [单独] 密集向量搜索结果 ---")
dense_results = collection.search(
    [dense_vec],
    anns_field="dense_vector",
    param=search_params,
    limit=top_k,
    expr=search_filter,
    output_fields=["title", "path", "description", "category", "location", "environment"]
)[0]

for i, hit in enumerate(dense_results):
    print(f"{i+1}. {hit.entity.get('title')} (Score: {hit.distance:.4f})")
    print(f"    路径: {hit.entity.get('path')}")
    print(f"    描述: {hit.entity.get('description')[:100]}...")

print("\n--- [单独] 稀疏向量搜索结果 ---")
sparse_results = collection.search(
    [sparse_vec],
    anns_field="sparse_vector",
    param=search_params,
    limit=top_k,
    expr=search_filter,
    output_fields=["title", "path", "description", "category", "location", "environment"]
)[0]

for i, hit in enumerate(sparse_results):
    print(f"{i+1}. {hit.entity.get('title')} (Score: {hit.distance:.4f})")
    print(f"    路径: {hit.entity.get('path')}")
    print(f"    描述: {hit.entity.get('description')[:100]}...")

print("\n--- [混合] 稀疏+密集向量搜索结果 ---")
# 创建 RRF 融合器
rerank = RRFRanker(k=60)

# 创建搜索请求
dense_req = AnnSearchRequest([dense_vec], "dense_vector", search_params, limit=top_k)
sparse_req = AnnSearchRequest([sparse_vec], "sparse_vector", search_params, limit=top_k)

# 执行混合搜索
results = collection.hybrid_search(
    [sparse_req, dense_req],
    rerank=rerank,
    limit=top_k,
    output_fields=["title", "path", "description", "category", "location", "environment"]
)[0]

# 打印最终结果
for i, hit in enumerate(results):
    print(f"{i+1}. {hit.entity.get('title')} (Score: {hit.distance:.4f})")
    print(f"    路径: {hit.entity.get('path')}")
    print(f"    描述: {hit.entity.get('description')[:100]}...")

最终输出结果如下：

--- [单独] 密集向量搜索结果 ---
1. 悬崖上的白龙 (Score: 0.7219)
    路径: ../../data/C3/dragon/dragon02.png
    描述: 一头雄伟的白色巨龙栖息在悬崖边缘，背景是金色的云霞和远方的海岸。它拥有巨大的翅膀和优雅的身姿，是典型的西方奇幻生物。...
2. 中华金龙 (Score: 0.5131)
    路径: ../../data/C3/dragon/dragon06.png
    描述: 一条金色的中华龙在祥云间盘旋，它身形矫健，龙须飘逸，展现了东方神话中龙的威严与神圣。...
3. 驯龙高手：无牙仔 (Score: 0.5119)
    路径: ../../data/C3/dragon/dragon05.png
    描述: 在电影《驯龙高手》中，主角小嗝嗝骑着他的龙伙伴无牙仔在高空飞翔。他们飞向灿烂的太阳，下方是岛屿和海洋，画面充满了冒险与友谊。...

--- [单独] 稀疏向量搜索结果 ---
1. 悬崖上的白龙 (Score: 0.2319)
    路径: ../../data/C3/dragon/dragon02.png
    描述: 一头雄伟的白色巨龙栖息在悬崖边缘，背景是金色的云霞和远方的海岸。它拥有巨大的翅膀和优雅的身姿，是典型的西方奇幻生物。...
2. 中华金龙 (Score: 0.0923)
    路径: ../../data/C3/dragon/dragon06.png
    描述: 一条金色的中华龙在祥云间盘旋，它身形矫健，龙须飘逸，展现了东方神话中龙的威严与神圣。...
3. 驯龙高手：无牙仔 (Score: 0.0691)
    路径: ../../data/C3/dragon/dragon05.png
    描述: 在电影《驯龙高手》中，主角小嗝嗝骑着他的龙伙伴无牙仔在高空飞翔。他们飞向灿烂的太阳，下方是岛屿和海洋，画面充满了冒险与友谊。...

--- [混合] 稀疏+密集向量搜索结果 ---
1. 悬崖上的白龙 (Score: 0.0328)
    路径: ../../data/C3/dragon/dragon02.png
    描述: 一头雄伟的白色巨龙栖息在悬崖边缘，背景是金色的云霞和远方的海岸。它拥有巨大的翅膀和优雅的身姿，是典型的西方奇幻生物。...
2. 中华金龙 (Score: 0.0320)
    路径: ../../data/C3/dragon/dragon06.png
    描述: 一条金色的中华龙在祥云间盘旋，它身形矫健，龙须飘逸，展现了东方神话中龙的威严与神圣。...
3. 霸王龙的怒吼 (Score: 0.0318)
    路径: ../../data/C3/dragon/dragon03.png
    描述: 史前时代的霸王龙张开血盆大口，发出震天的怒吼。在它身后，几只翼龙在阴沉的天空中盘旋，展现了白垩纪的原始力量。...
4. 奔跑的奶龙 (Score: 0.0313)
    路径: ../../data/C3/dragon/dragon04.png
    描述: 一只Q版的黄色小恐龙，有着大大的绿色眼睛和友善的微笑。是一部动画中的角色，非常可爱。...
5. 驯龙高手：无牙仔 (Score: 0.0310)
    路径: ../../data/C3/dragon/dragon05.png
    描述: 在电影《驯龙高手》中，主角小嗝嗝骑着他的龙伙伴无牙仔在高空飞翔。他们飞向灿烂的太阳，下方是岛屿和海洋，画面充满了冒险与友谊。...

Python的ACM模式基础

Sat, 21 Mar 2026 00:00:00 GMT

一、单行输入

对10个整数从小到大排序，处理10个整数，并打印出来

# 程序入口
# 输入
if __name__=="__main__":
    # 去掉输如字符串的前后空格，然后分割成数组
    # 输入元素：
    # 4 85 3 234 45 345 345 122 30 12
    # 下面这句也可以写成list(map(lambda x: int(x),input().strip().split()))
    data = list(map(int,input().strip().split()))
    data.sort()
    print(" ".join(map(str,data)))

二、多行输入，不确定行数

给定正整数A和B，计算A+B

if __name__ == "__main__":
    # 不确定函数，我们需要while循环
    # 输入元素：
    """
    1 1
    2 3
    """
    while True:
        # 这里的map是一个迭代器
        # 用try来接受文件结束错误
        try:
            a,b = map(int,input().strip().split())
            print(a+b)
        except EOFError:
            break

三、多行输入，确定行数

输入一个n，然后再输入n组数据样例，返回他们的和

if __name__ == "__main__":
    n = int(input().strip())
    for i in range(n):
        a, b = map(int,input().strip().split())
        print(a+b)

四、多行输入，指定结束符号

还是两数之和，指定0 0结束

if __name__ == "__main__":
    n = int(input().strip())
    for i in range(n):
        a,b = map(int,input().strip().split())
        if a == 0 and b == 0:
            break
        print(a + b)

五、不确定行数，不确定个数

输入多组数据样例，每组数据占一行，每一行的输入划分为第一个数和其他数，第一个数代表后面多少数求和，返回和。

if __name__ == "__main__":
    while True:
        try:
            data = list(map(int,input().strip().split()))
            n,array = data[0],data[1:]
            print(sum(array))
        except EOFError:
            break

六、确定行数不确定个数

先输入n，然后给n行，每行个数不确定，返回和

if __name__ == "__main__":
    n = int(input().strip())
    for _ in range(n):
        data = list(map(int,input().strip().split()))
        print(sum(data))

七、多行输入，不确定类型

给定 n，然后输入 n 行，每行包含成绩单信息。

输出三行，第一行语文最好的学生姓名学科分数，第二行数学成绩最好的学生姓名学科分数，第三行英语成绩最好的学生姓名学科分数。

def number_or_chars(x):
    if x.isdigit():
        return int(x)
    else:
        return x

if __name__ == "__main__":
    n = int(input().strip())
    info = []
    for _ in range(n):
        data = list(map(number_or_chars,input().strip().split()))
        info.append(data)

    max_c = 0
    max_c_id = 0
    max_m = 0
    max_m_id = 0
    max_e = 0
    max_e_id = 0

    for i, each in enumerate(info):
        if max_c < each[3]:
            max_c = each[3]
            max_c_id = i
        if max_m < each[5]:
            max_m = each[5]
            max_m_id = i
        if max_e < each[7]:
            max_e = each[7]
            max_e_id = i

    print(info[max_c_id][0],info[max_c_id][2],info[max_c_id][3])
    print(info[max_m_id][0],info[max_m_id][4],info[max_m_id][5])
    print(info[max_e_id][0],info[max_e_id][6],info[max_e_id][7])

八、`sys.stdin` 的几种常见写法

等价于不断读到 EOF 为止，一行一行读入，不用自己写 while True + try/except。一般有如下三种情况：

1. 逐行读到 EOF

import sys

for line in sys.stdin:
    nums = list(map(int, line.split()))
    print(sum(nums))

2. 一次性读完

import sys

data = sys.stdin.read().split()
nums = list(map(int, data))
print(sum(nums))

3. 代替 `input()` 提速

import sys

input = sys.stdin.readline

n = int(input().strip())
for _ in range(n):
    a, b = map(int, input().split())
    print(a + b)

九、`ast.literal_eval` 解析嵌套结构

有些题目的本地输入会直接写成 Python 风格的嵌套列表，比如：

[[1,2],[3,4],[5,6]]

或者像随机链表那样：

[[7,null],[13,0],[11,4],[10,2],[1,0]]

这时候如果手动 split 会很麻烦，用 ast.literal_eval 往往更省事。

它的作用是：安全地把“字符串形式的字面量”解析成真正的 Python 数据结构。

import ast

if __name__ == "__main__":
    line = input().strip()
    data = ast.literal_eval(line)
    print(data)

例如输入：

[[1,2],[3,4],[5,6]]

输出就是：

[[1, 2], [3, 4], [5, 6]]

如果输入里有 null，Python 不认识，需要先替换成 None：

import ast

if __name__ == "__main__":
    line = input().strip()
    data = ast.literal_eval(line.replace("null", "None"))
    print(data)

这个方法特别适合：

二维数组
嵌套列表
树、图、随机链表这类带结构的本地模拟输入

注意这里一般用的是 ast.literal_eval，而不是 eval，因为前者更安全，只会解析字面量，不会执行任意代码。

算法总结-动态规划

Sat, 21 Mar 2026 00:00:00 GMT

动态规划的核心理解

什么是动态规划

动态规划（DP）的本质是把一个大问题拆成有重叠的子问题，每个子问题只算一次，用数组/哈希表存下来，然后从这些子问题的解推导出原问题的解。

两个核心要素：

最优子结构：大问题的最优解可以由子问题的最优解推导出来
重叠子问题：同一个子问题会被反复遇到，不缓存就会重复计算

简单说：遇到一个问题的状态可以由前面的状态推导出来，而且前面的状态会被多次用到，就该想到 DP。

DP 和递归、记忆化搜索的关系

三者本质是同一张 DAG（有向无环图）上的不同遍历方式：

递归（自顶向下）→ 加 @cache → 记忆化搜索 → 翻转方向 → DP 数组（自底向上）

	方向	存储	典型写法
无缓存递归	顶→底	无	指数级重复计算
记忆化搜索	顶→底	cache/hash	`@cache` + dfs
DP 数组	底→顶	数组	for 循环填表

同一道题，dfs(i) 的参数 i 就是 dp[i] 的下标，返回值就是 dp[i] 的值。记忆化搜索和 DP 数组完全等价，只是遍历方向相反。树形 DP 天然适合递归写法（树没有重叠子问题），线性/网格 DP 适合数组写法（空间压缩更方便）。

什么时候想到动态规划

题目求最值、方案数、可行性（"最多""最少""有多少种""能不能"）
每个步骤有选择，选择影响后续（选或不选、选哪个）
状态可以用有限个变量描述（位置、容量、剩余次数……）
一看就有大量重复子问题，暴力会超时
数据范围：n ≤ 10^4~10^5（一维 DP），n ≤ 500（二维 DP），n ≤ 20（状态压缩 DP）

反面信号：要你输出所有具体方案（不是方案数）→ 回溯；数据范围 n ≥ 10^6 且无特殊结构 → 贪心或数学。

动态规划五步法

拿到一道 DP 题按这五步走：

定义 dp 含义：dp[i] 或 dp[i][j] 到底代表什么？一句话说清楚
推导转移方程：当前状态能从哪些前驱状态推导过来？
初始化：基础情况（空串、边界、第一行/列）填什么？
确定遍历顺序：从小到大还是从大到小？外层是什么？保证依赖的前驱先被算好
返回值：最终答案在 dp 数组的哪个位置？

状态定义

最关键的一步。常见的 dp 含义模式：

以 i 结尾：dp[i] = 以位置 i 结尾时的最优值（LC53 最大子数组和、LC300 LIS）
前 i 个元素：dp[i] = 考虑前 i 个元素时的最优值（LC198 打家劫舍）
区间 [i, j]：dp[i][j] = 区间上的最优值（LC5 回文子串、LC312 戳气球）
双序列：dp[i][j] = s 的前 i 个和 t 的前 j 个的结果（LC1143 LCS、LC72 编辑距离）
状态机：定义多个状态互相转移（股票买卖、LC968 监控二叉树）
mask 压缩：dp[mask] 用二进制表示集合（LC698 划分子集）

好的定义让转移方程自然涌现，坏的定义令人想破头。如果转移很别扭，大概率是状态定义歪了。

状态转移

从"前一个状态 + 当前选择"推导当前状态。常见模式：

选或不选：dp[i] = max(dp[i-1], dp[i-2] + val[i])（打家劫舍）
选哪个：dp[i] = max(dp[i-1], dp[0..i-1]) + cost（LIS、零钱兑换）
两端收缩：dp[i][j] 由 dp[i+1][j] 和 dp[i][j-1] 转移（回文 DP）
中间切分：dp[i][j] 由 dp[i][k] + dp[k+1][j] 转移（区间 DP）
两路汇合：dp[i][j] 由 dp[i-1][j] 和 dp[i][j-1] 转移（网格路径、LCS）

写不出转移时，画个小例子在纸上手动推三步，看相邻状态之间的关系。

初始化

初始化决定了"空状态"和"边界状态"的值，直接影响后续所有填表。

0/1 背包：dp[0] = 0（容量 0 时价值 0），其余 -∞ 或 False
计数 DP：dp[0] = 1（"什么都不选"算一种方案）
双序列 DP：dp[i][0] 和 dp[0][j] 对应空串的情况（多开一圈的好处）
路径 DP：第一行和第一列特殊处理（或用越界保护统一）

小技巧：多开一圈（dp = [0] * (n+1)）让 dp[0] 代表空前缀，避免单独处理边界。

遍历顺序

核心原则：计算 dp[i] 时，它依赖的所有状态必须已经算好。

一维：通常是正序（依赖 i-1），背包倒序（避免物品重复使用）
二维网格：i 正序 j 正序（依赖上方和左方）
回文 DP：i 倒序 j 正序（依赖 i+1 和 j-1）
区间 DP：按区间长度递增（短区间先算）
树形 DP：后序遍历（子节点先算）

不确定顺序时，画一个二维表，标出 (i,j) 依赖哪些格子，箭头方向就是遍历方向。

返回值

不是所有 DP 的答案都在最后一个位置。常见情况：

dp[n] 或 dp[m][n]：整个问题的答案（LCS、编辑距离）
max(dp)：最优值可能出现在任意位置（最大子数组和、LIS）
dp[0][n-1]：整个区间/字符串的答案（回文 DP、区间 DP）
min(dp[:2])：状态机的最终状态（监控二叉树、股票问题）
dp[(1<<n)-1]：全选状态（状态压缩 DP）

空间压缩

如果 dp[i] 只依赖固定的前几项，可以用滚动变量代替整个数组：

依赖 dp[i-1] 和 dp[i-2] → 用两个变量（斐波那契、爬楼梯）
依赖 dp[i-1][j] 和 dp[i][j-1] → 用一维数组滚动（二维路径）
依赖上一行的邻近列 → 用两个一维数组交替（下降路径最小和）

空间压缩不是必需的，先写出完整 DP 跑通，再考虑优化。

Python 中常用写法

# 基础一维 DP
dp = [0] * (n + 1)
for i in range(1, n + 1):
    dp[i] = max(dp[i-1], dp[i-2] + val)

# 多开一圈避免边界判断
dp = [[0] * (n + 1) for _ in range(m + 1)]

# 越界保护（用 INF）
from_up = dp[i-1][j] if i > 0 else float('inf')

# 记忆化搜索（等价 DP）
from functools import cache
@cache
def dfs(i, j):
    ...

# 滚动变量替代数组
cur, prev = 1, 1
for i in range(2, n + 1):
    cur, prev = cur + prev, cur

入门一维 DP

斐波那契模型

LC509 - 斐波那契数

感觉反复写过很多遍了，也罢，放在dp专题里面再写一次吧，注意一下范围问题。

def fib(n:int):
    if n<2:
        return n
    dp = [0]*(n+1)
    dp[0] = 0
    dp[1] = 1
    for i in range(2,n+1):
        dp[i] = dp[i-1] + dp[i-2]
    return dp[n]

LC70 - 爬楼梯

def climbStairs(self, n: int) -> int:
    dp = [0] * (n+1)
    dp[0] = 1
    dp[1] = 1
    for i in range(2,n+1):
        dp[i] = dp[i-1] + dp[i-2]
    return dp[n]

LC746 - 使用最小花费爬楼梯

最小花费爬楼梯问题，我们将dp[i]定义为到i级台阶的最小费用。这里注意，真实台阶的下标是0 ~ n-1，我们求的dp[n]就是已经算上最后的台阶的费用了。

def minCostClimbingStairs(self, cost: list[int]) -> int:
    n = len(cost)
    dp = [0] * (n+1)
    for i in range(2,n+1):
        dp[i] = min(dp[i-2]+cost[i-2],dp[i-1]+cost[i-1])
    return dp[n]

打家劫舍模型

LC198 - 打家劫舍

打家劫舍是经典的dp题，也是经典的带限制0-1背包。每个房间可以选择偷或不偷，但是相邻的房子不能被偷。

我们用dp[i]表示偷的房子编号以i结尾的最大金额，其转移方程为 dp[i] = max(dp[i-2]+nums[i], dp[i-1])。它表示要么从两个前偷过来，要么这里不偷沿用上一个的金额。

def rob(self, nums: list[int]) -> int:
    n = len(nums)
    dp = [0] * n
    if n == 0:
        return 0
    if n == 1:
        return nums[0]
    dp[0] = nums[0]
    dp[1] = max(nums[0],nums[1])
    for i in range(2,n):
        dp[i] = max(dp[i-2]+nums[i],dp[i-1])
    return dp[n-1]

需要注意的就是下标越界问题。所以dp题都应该先考虑让初始条件成立（如果有下标初始化先保证下标有意义），然后再进行转移。

LC213 - 打家劫舍 II

与打家劫舍的区别是房子现在围成一圈。环形打家劫舍关键限制就是第0间和第n-1间不能同时偷，因为它们相邻。所以合法的方案只能在不偷最后一间，不偷第一间中选。我们直接写出打家劫舍，然后return两种情况的max就行。

def rob_linear(self, nums: List[int]) -> int:
    n = len(nums)
    dp = [0] * (n + 1)
    if n == 0:
        return 0
    if n == 1:
        return nums[0]
    dp[0] = nums[0]
    dp[1] = max(nums[0], nums[1])
    for i in range(2, n):
        dp[i] = max(dp[i - 2] + nums[i], dp[i - 1])
    return dp[n - 1]

def rob(self, nums: List[int]) -> int:
    n = len(nums)
    if n == 0:
        return 0
    if n == 1:
        return nums[0]
    # 复用打家劫舍1
    return max(self.rob_linear(nums[0 : n - 1]), self.rob_linear(nums[1:n]))

LC337 - 打家劫舍 III

树形打家劫舍。实际上就是限制父树和子树不能同时被偷。我们复用树的结构，存rob和not_rob两个值，来表示偷/不偷的时候最大金额。这样，就有两个转移方程：

如果偷了当前节点，左右孩子都不能偷了：rob = root.val + left.not_rob + right.not_rob
如果不偷当前节点，那左右孩子可以偷，也可以不偷，各自取最大：not_rob = max(left.rob, left.not_rob) + max(right.rob, right.not_rob)

树形打家劫舍里，当前节点的答案依赖左右子树的答案。所以就是标准的后序问题，按照左右中即可：

def rob(root):
    def dfs(node):
        if not node:
            return (0, 0)

        left_rob, left_not_rob = dfs(node.left)
        right_rob, right_not_rob = dfs(node.right)

        rob_cur = node.val + left_not_rob + right_not_rob
        not_rob_cur = max(left_rob, left_not_rob) + max(right_rob, right_not_rob)

        return (rob_cur, not_rob_cur)

    return max(dfs(root))

最大子数组模型

LC53 - 最大子数组和

经典dp，注意最大子数组和不一定出现在最后即可。还有注意下标问题，dp最容易出现下标问题，还有边界问题（只有1个数据的时候），尽量脑子里想一下，实在不行就保护0、1、2的时候。

dp[i] 的含义是，是以位置i结尾的时候的最大子数组和。因此dp数组只要开到n-1下标

def maxSubArray(self, nums: list[int]) -> int:
    n = len(nums)
    dp = [0] * n
    dp[0] = nums[0]
    for i in range(1,n):
        dp[i] = max(dp[i-1]+nums[i],nums[i])
    return max(dp)

当然，这一题只要求一个最大值，我们可以不维护整个dp数组。我们用curr_max维持遍历的时候目前的最大连续子数组和，然后ans来记录全局答案即可。

def maxSubArray(self, nums: list[int]) -> int:
    n = len(nums)
    curr_max = nums[0]
    ans = nums[0]
    for i in range(1,n):
        curr_max = max(curr_max+nums[i],nums[i])
        ans = max(ans,curr_max)
    return ans

LC918 - 环形子数组的最大和

环形最大子数组问题可以被拆成两类问题，即最大子数组不跨越首尾、最大子数组跨越首尾。前者回退到LC53，而后者则是可以用总会-最小子数组和。

def maxSubarraySumCircular(nums):
    total = sum(nums)

    cur_max = max_sum = nums[0]
    cur_min = min_sum = nums[0]

    for x in nums[1:]:
        cur_max = max(x, cur_max + x)
        max_sum = max(max_sum, cur_max)

        cur_min = min(x, cur_min + x)
        min_sum = min(min_sum, cur_min)

    # 如果都是负数，也不允许一个都不选。因为可以用 total - min_sum = 0 表示一个都不选。
    if max_sum < 0:
        return max_sum

    return max(max_sum, total - min_sum)

一维 DP 常见模板

# 基础模板：dp[i] = f(dp[i-1], dp[i-2], ...)
n = len(data)
dp = [0] * n
dp[0] = init_val
for i in range(1, n):
    dp[i] = max(dp[i-1], dp[i-2] + val[i])  # 具体转移看题
return dp[-1]  # 或 max(dp)

# 空间压缩：依赖固定前几项时用两个变量
cur, prev = init_cur, init_prev
for i in range(2, n + 1):
    cur, prev = update(cur, prev), cur
return cur

一维 DP 的核心是搞清楚 dp[i] 代表什么：是以 i 结尾，还是前 i 个元素。

二维网格 DP

网格路径的核心理解

网格 DP 的状态依赖上方和左方（或更多方向），典型的转移模式：

dp[i][j] = f(dp[i-1][j], dp[i][j-1]) + cost[i][j]

遍历顺序通常是 i 正序 j 正序，保证左和上的状态先算好。

LC62 - 不同路径

路径题是经典的二维dp。我们用同样尺寸的dp网格，dp[i][j]表示到坐标ij处的路径数，然后返回dp[m-1][n-1]就行。

def uniquePaths(self, m: int, n: int) -> int:
    dp = [[0]* n for _ in range(m)]
    # 初始化边界
    for i in range(m):
        dp[i][0] = 1
    for j in range(n):
        dp[0][j] = 1
    
    for i in range(1,m):
        for j in range(1,n):
            dp[i][j] = dp[i-1][j] + dp[i][j-1]
    return dp[m-1][n-1]

LC63 - 不同路径 II

存在表示为1的石头，不能走。其实就是在石头位置把dp设置为0，这样对后面的路贡献也清掉了。另外边界情况时，如果遇到石头，那后面的也要全部置为0。

def uniquePathsWithObstacles(obstacleGrid):
    m, n = len(obstacleGrid), len(obstacleGrid[0])
    dp = [[0] * n for _ in range(m)]

    if obstacleGrid[0][0] == 1:
        return 0

    dp[0][0] = 1

    for j in range(1, n):
        if obstacleGrid[0][j] == 0:
            dp[0][j] = dp[0][j - 1]

    for i in range(1, m):
        if obstacleGrid[i][0] == 0:
            dp[i][0] = dp[i - 1][0]

    for i in range(1, m):
        for j in range(1, n):
            if obstacleGrid[i][j] == 1:
                dp[i][j] = 0
            else:
                dp[i][j] = dp[i - 1][j] + dp[i][j - 1]

    return dp[m - 1][n - 1]

这一题为了简洁，我们也可以不单独拿出来初始化边界，而是在遍历中判断，把石头的dp变成0，其他统一用带边界判断if-else的转移方程（统一规划越界方向0）。

def uniquePathsWithObstacles(obstacleGrid):
    m, n = len(obstacleGrid), len(obstacleGrid[0])
    dp = [[0] * n for _ in range(m)]

    dp[0][0] = 1 if obstacleGrid[0][0] == 0 else 0

    for i in range(m):
        for j in range(n):
            if obstacleGrid[i][j] == 1:
                dp[i][j] = 0
            # 不单独初始化也要单独弄掉零零
            elif i == 0 and j == 0:
                continue
            else:
                from_up = dp[i - 1][j] if i > 0 else 0
                from_left = dp[i][j - 1] if j > 0 else 0
                dp[i][j] = from_up + from_left

    return dp[-1][-1]

LC64 - 最小路径和

我们用dp[i][j]存储到当前路径，可以用越界统一正无穷保护。

def minPathSum(self, grid: list[list[int]]) -> int:
    m, n = len(grid), len(grid[0])
    dp = [[0]*n for _ in range(m)]
    for i in range(m):
        for j in range(n):
            if i == 0 and j == 0:
                dp[i][j] = grid[0][0]
            else:
                from_up = dp[i-1][j] if i>0 else float('INF')
                from_left = dp[i][j-1] if j>0 else float('INF')
                dp[i][j] = min(from_left,from_up)+grid[i][j]
    return dp[-1][-1]

LC931 - 下降路径最小和

下降元素最小和问题，我们可以先用dp[i][j]表示到达坐标ij的下降路径最小和，然后转移方程就是dp[i][j] = min(dp[i-1][j], dp[i-1][j-1], dp[i-1][j+1]) + matrix[i][j]，越界保护正无穷即可。

def minFallingPathSum(self, matrix: list[list[int]]) -> int:
    m, n = len(matrix), len(matrix[0])
    dp = [[0] * n for _ in range(m)]
    for i in range(m):
        for j in range(n):
            if i == 0:
                dp[i][j] = matrix[i][j]
            else:
                a = dp[i-1][j-1] if j-1 >= 0 else float('INF')
                b = dp[i-1][j]
                c = dp[i-1][j+1] if j+1 < n else float('INF')
                dp[i][j] = min(a,b,c) + matrix[i][j]
    return min(dp[-1])

LC120 - 三角形最小路径和

跟上一题差不多的，用dp[i][j]存这里可以走到的最小路径和，j最多只到i+1的位置。转移方程式 dp[i][j] = min(dp[i-1][j], dp[i-1][j-1]) + triangle[i][j]。

def minimumTotal(self, triangle: list[list[int]]) -> int:
    n = len(triangle)
    dp = [[0]*n for _ in range(n)]
    for i in range(n):
        for j in range(i+1):
            if i == 0:
                dp[i][j] = triangle[i][j]
            else:
                a = dp[i-1][j] if j<=i-1 else float('INF')
                b = dp[i-1][j-1] if j-1>=0 else float('INF')
                dp[i][j] = min(a,b) + triangle[i][j]
    return min(dp[-1])

二维网格 DP 常见模板

# 基础模板
m, n = len(grid), len(grid[0])
dp = [[0] * n for _ in range(m)]
dp[0][0] = grid[0][0]
for i in range(1, m): dp[i][0] = dp[i-1][0] + grid[i][0]
for j in range(1, n): dp[0][j] = dp[0][j-1] + grid[0][j]
for i in range(1, m):
    for j in range(1, n):
        dp[i][j] = min(dp[i-1][j], dp[i][j-1]) + grid[i][j]
return dp[-1][-1]

# 越界保护版（免去初始化边界）
for i in range(m):
    for j in range(n):
        if i == 0 and j == 0:
            dp[i][j] = grid[0][0]
        else:
            from_up = dp[i-1][j] if i > 0 else float('inf')
            from_left = dp[i][j-1] if j > 0 else float('inf')
            dp[i][j] = min(from_up, from_left) + grid[i][j]

背包 DP

背包问题的核心理解

背包问题的本质是：有一个容量限制，每个物品有体积和价值，在不超过容量的前提下做选择，使得总价值最大（或判断能否装满）。

三种基本变体：

0-1 背包：每个物品只能选或不选。遍历时倒序（保证每个物品只用一次）
完全背包：每个物品可以选无数次。遍历时正序（允许同一物品被重复使用）
多重背包：每个物品有有限个。可转化为 0-1 背包或用计数数组优化

此外还有分组背包（每组最多选一个）等变体。

背包 DP 的一个重要技巧是 "求什么就设什么为 dp 值"：

目标	dp 含义	转移核心
最大价值	`dp[j]` = 容量 j 时的最大价值	`dp[j] = max(dp[j], dp[j-v] + w)`
能否装满	`dp[j]` = 能否凑出 j	`dp[j] = dp[j] or dp[j-num]`
装满的方案数	`dp[j]` = 凑出 j 的方案数	`dp[j] += dp[j-num]`
最少物品数	`dp[j]` = 凑出 j 的最少物品数	`dp[j] = min(dp[j], dp[j-num] + 1)`

0-1 背包

0-1 背包模板

# 0-1 背包：求最大价值
def knapsack01(weights, values, capacity):
    dp = [0] * (capacity + 1)
    for i in range(len(weights)):
        for j in range(capacity, weights[i] - 1, -1):  # 倒序！
            dp[j] = max(dp[j], dp[j - weights[i]] + values[i])
    return dp[capacity]

# 0-1 背包：能否装满（布尔背包）
dp = [False] * (target + 1)
dp[0] = True
for num in nums:
    for j in range(target, num - 1, -1):
        dp[j] = dp[j] or dp[j - num]

# 0-1 背包：方案数
dp = [0] * (target + 1)
dp[0] = 1
for num in nums:
    for j in range(target, num - 1, -1):
        dp[j] += dp[j - num]

倒序是关键——正序会让同一物品被重复使用，变成完全背包。

LC416 - 分割等和子集

这一题其实就是组合总和 II 的「判定版」，而且 target 固定为总和的一半。完全可以直接拿过来用。

from functools import cache

def canPartition(nums):
    total = sum(nums)
    if total % 2:
        return False

    target = total // 2
    nums.sort()

    @cache
    def dfs(start,target):
        if target<0:
            return False
        if target == 0:
            return True
        
        for i in range(start,len(nums)):
            if dfs(i+1,target-nums[i]):
                return True
        return False
    return dfs(0,target)

但是，如果直接拿过来有一个注意事项，就是组合总和II是需要答案组合，还不能重复，所以有一个跳过下一层选同样数字的设置（那边每个数字只能用一次），这里要去除。然后，那里需要组合的具体数字，这里只需要True/False，有大量重复状态，可以@cache加速。折腾完了之后，你会发现可以惊人打败5%了。。

所以，因为不需要具体选择，只要“能不能凑出来”这个状态的结果，这一题的做法还得是0/1背包滚动更新。0/1 背包解决的是“每个东西只能选一次，在容量/目标限制下选出最优或判断能否达成”的问题。

我们设 dp[j] 为能不能凑出来数字j，不能重复选的0/1背包，做法是倒序遍历，这样能保证每个num只被使用一次。有转移方程 dp[j] = dp[j] or dp[j-num]。

这里有点绕，我们来举个例子理解这个问题。比如[1,5,11,5]，那么我们就要找能不能切分成两个和为11的。首先，我们肯定会让dp[0] = True，因为凑个0默认都是可以凑的，不选呗。然后，我们看到第一个数字1，从大到小更新，按照转移方程，dp[11] = dp[11] or dp[10]，dp[10] = dp[10] or dp[9]…… 这样检查下去，都是False，没有什么影响，直到看到 dp[1] = dp[1] or dp[0] 的时候，dp[1]会被变成True。

你发现了没有，倒序更新不会乱动后面的dp，但是给目前能凑出来的结果dp[j-num]，转移到了dp[j]。如果正序的话，这个结果就会错误被传递下去，一个 dp[0] = True 和一个 num = 1可以直接全部推成True。

至于倒序只到 num-1 比较好理解，因为num不可能凑出来比 num 还小的数字。好了，至此，我们就可以写出这道0/1背包的经典入门题：

def canPartition(nums):
    total = sum(nums)
    if total % 2:
        return False

    target = total // 2
    dp = [False] * (target + 1)
    dp[0] = True

    for num in nums:
        for j in range(target, num - 1, -1):
            dp[j] = dp[j] or dp[j - num]

    return dp[target]

LC494 - 目标和

这一题当然可以用带cache的dfs来做，如果想按照01背包来做，需要做一些改动。如果被加号选中的数字为P，减号选中的为N，则有 P-N = target，而且 P + N = S（数组总和），我们可以直接得到 P = (S + target) / 2，问题成功被转化为nums中选一些数让他们和为(S + target) / 2，问有多少选法。

然后，不是求是否能选，而是有多少选法时，转移方程也稍微变一下，变成 dp[j] += dp[j-num] 即可（dp初始化全0）。

def findTargetSumWays(nums, target):
    total = sum(nums)

    if abs(target) > total:
        return 0

    if (total + target) % 2 == 1:
        return 0

    bag = (total + target) // 2

    dp = [0] * (bag + 1)
    dp[0] = 1

    for num in nums:
        for j in range(bag, num - 1, -1):
            dp[j] += dp[j - num]

    return dp[bag]

这样写时间上也是爆杀dfs，不错。

LC1049 - 最后一块石头的重量 II

这题跟上一题有点像，但是不再提供目标，而是要去求 min(abs(P - N))。两堆谁大谁小无所谓，我们假设 P 小，N - P = (S - P) - P = S - 2P。所以差值最小的情况，就是 P 最接近 S/2 的情况：从 stones 里选一些石头，每个石头最多选一次，让它们的和尽量接近但不超过 sum(stones) // 2。

这就是标准的01背包问题！01背包本来的样子，就是接近但不超过容量要装的最大重量石头。我们按照最大重量背包问题直接求解，转移方程从布尔背包变成了 dp[j] = max(dp[j], dp[j - stone] + stone)。这里就是P最接近 S/2 的重量，然后我们用总重量 - 2P 就达成了。

def lastStoneWeightII(stones):
    total = sum(stones)
    target = total // 2

    dp = [0] * (target + 1)

    for stone in stones:
        for j in range(target, stone - 1, -1):
            dp[j] = max(dp[j], dp[j - stone] + stone)

    return total - 2 * dp[target]

完全背包

完全背包模板

# 完全背包：最少硬币数
dp = [INF] * (amount + 1)
dp[0] = 0
for coin in coins:
    for j in range(coin, amount + 1):  # 正序！
        dp[j] = min(dp[j], dp[j - coin] + 1)

# 完全背包：方案数（组合）
dp = [0] * (amount + 1)
dp[0] = 1
for coin in coins:              # 物品在外
    for j in range(coin, amount + 1):  # 容量在内
        dp[j] += dp[j - coin]

# 排列数：容量在外，物品在内
dp = [0] * (target + 1)
dp[0] = 1
for j in range(1, target + 1):  # 容量在外
    for num in nums:            # 物品在内
        if j >= num:
            dp[j] += dp[j - num]

正序 vs 倒序决定了同一物品能否被多次选取。组合 vs 排列由物品循环和容量循环的嵌套顺序决定。

多重背包

每个物品有数量限制 count[i]。简单做法是将每个物品拆成 count[i] 个 0-1 背包物品（复杂度过高），优化用二进制拆分或计数数组。

# 多重背包：二进制拆分法
for w, v, cnt in items:
    k = 1
    while k <= cnt:
        # 打包成 k 个物品
        for j in range(capacity, w * k - 1, -1):
            dp[j] = max(dp[j], dp[j - w * k] + v * k)
        cnt -= k
        k *= 2
    if cnt:  # 剩余的再打一包
        for j in range(capacity, w * cnt - 1, -1):
            dp[j] = max(dp[j], dp[j - w * cnt] + v * cnt)

分组背包

每组物品最多选一个。物品分好组后，外层枚举组，内层倒序枚举容量，最内层枚举组内物品。

for group in groups:
    for j in range(capacity, -1, -1):
        for w, v in group:
            if j >= w:
                dp[j] = max(dp[j], dp[j - w] + v)

背包 DP 遍历顺序总结

变体	物品循环	容量循环	内层方向	复杂度
0-1 背包	外层	内层	倒序	O(n * C)
完全背包（组合）	外层	内层	正序	O(n * C)
完全背包（排列）	内层	外层	正序	O(n * C)
多重背包	外层（拆分后）	内层	倒序	O(Σcnt * C)
分组背包	外层	内层（中）	倒序	O(G * k * C)

硬币可以选无数次，所以这一题是一个完全背包问题。因此，我们也不需要倒序遍历，直接正序从coin走到底就行。dp[j] 表示凑到 j 所需要的最小硬币数，转移方程 dp[j] = min(dp[j], dp[j-coin] + 1)。初始化dp的时候，用一个很大的数字表示不可达。

def coinChange(self, coins: list[int], amount: int) -> int:
    INF = amount + 1
    dp = [INF] * (amount + 1)
    dp[0] = 0

    for coin in coins:
        for j in range(coin, amount + 1):
            dp[j] = min(dp[j], dp[j - coin] + 1)

    return dp[amount] if dp[amount] != INF else -1

我们写题的时候一定要先捋清楚dp的含义，这样才知道如何写初始化和转移。

LC518 - 零钱兑换 II

这一题零钱兑换，依旧无限硬币，但是求的是凑出amount的方案。我们定义dp[j]为凑出j的方案数，显然全部初始化为0。转移方程为 dp[j] += dp[j-coin] 即可。

def change(self, amount: int, coins: list[int]) -> int:
    dp = [0] * (amount + 1)
    dp[0] = 1
    for coin in coins:
        for j in range(coin,amount+1):
            dp[j] += dp[j-coin]
    return dp[amount]

LC279 - 完全平方数

给你一个整数 n ，返回和为 n 的完全平方数的最少数量。这一题实际上也是完全背包，可以选的从1到无限，求最少和数字为n的个数。我们设dp[j]表示凑出j的最小完全平方数个数，转移方程 dp[j] = min(dp[j-i*i]+1,dp[j])。

但是这一题的候选没给有限的数组，我们可以先求出平方小于等于n的最大数字k（这里如果看出来n就是完全平方数那就直接返回1了），然后从1开始试到k。

def numSquares(n: int) -> int:
    INF = n + 1
    dp = [INF] * (n + 1)
    dp[0] = 0

    for i in range(1, int(n ** 0.5) + 1):
        square = i * i
        for j in range(square, n + 1):
            dp[j] = min(dp[j], dp[j - square] + 1)

    return dp[n]

LC377 - 组合总和 IV

这一题的核心在于“顺序不同算不同方案”，普通的完全背包 dp[j] += dp[j-num] 会默认按照nums顺序调用，无法区分 1+2 和 2+1 。所以，我们要改变格式，将容量放到外层，然后物品放在内层，然后用容量大于物体来判断是否转移：

def combinationSum4(nums, target):
    dp = [0] * (target + 1)
    dp[0] = 1

    for j in range(1, target + 1):
        for num in nums:
            if j >= num:
                dp[j] += dp[j - num]

    return dp[target]

我们注意区分完全背包中的“组合数”和“排列数”，前者物品在外容量在内，后者容量在外物品在内。

多重背包

分组背包

背包 DP 遍历顺序总结

子序列 DP

子序列 DP 的核心理解

子序列 DP 处理的是"从序列中按顺序选一部分"的问题。核心区分两个概念：

子数组/子串（Subarray）：必须连续，dp[i] 通常以 i 结尾
子序列（Subsequence）：可以不连续，dp[i] 需要遍历前面所有位置

连续版转移通常只有一种去向（i-1），不连续版需要枚举前驱。

单序列 DP 的 dp[i] 几乎总是"以 i 结尾"的含义。双序列 DP 则是经典 dp[i][j] 二维表。

单序列 DP

LC300 - 最长递增子序列

这一题最长递增子序列，特别要注意的是，子序列可以不用连续！设 dp[j] 为到为止j位置的最长递增子序列长度，我们需要遍历前面的i，如果满足nums[i] < nums[j]，则转移 dp[j] = max(dp[j], dp[i] + 1)。

def lengthOfLIS(nums):
    n = len(nums)
    dp = [1] * n

    for j in range(n):
        for i in range(j):
            if nums[i] < nums[j]:
                dp[j] = max(dp[j], dp[i] + 1)

    return max(dp)

当然，这一题有更快的解法，即贪心+二分的方法。

def lengthOfLIS(nums):
    tails = []

    for x in nums:
        left, right = 0, len(tails)

        while left < right:
            mid = (left + right) // 2

            if tails[mid] >= x:
                right = mid
            else:
                left = mid + 1

        if left == len(tails):
            tails.append(x)
        else:
            tails[left] = x

    return len(tails)

LC674 - 最长连续递增序列

本题和最大连续子数组和相似，都是继续上一个或者另起，我们设 dp[j] 为到j位置为止的最长递增序列，转移方程为：dp[j] = dp[j - 1] + 1 if nums[j - 1] < nums[j] else 1。

def findLengthOfLCIS(self, nums: list[int]) -> int:
    n = len(nums)
    dp = [1] * n
    for j in range(1,n):
        dp[j] = dp[j - 1] + 1 if nums[j - 1] < nums[j] else 1
    return max(dp)

然后这一题也同样可以使用两个变量解决：

def findLengthOfLCIS(self, nums: list[int]) -> int:
    cur = 1
    ans = 1
    for j in range(1, len(nums)):
        if nums[j - 1] < nums[j]:
            cur += 1
        else:
            cur = 1
        ans = max(ans, cur)
    return ans

LC32 - 最长有效括号

同样是dp[i] = 以 i 位置结尾的某种最优结果，但是这一题更复杂一点，属于更复杂的连续结构。有效括号一定会以右括号结尾，所以左括号对应的dp都是0；而当遇到右括号的时候，有两种情况，一种情况是()，这样可以直接把这两个算成有效，然后按照 dp[i-2]+2 来转移就行；另一种情况是))，这样的话，我们需要先找到前一个括号的有效括号长度（即dp[i-1]），然后找到这段有效括号之前的位置即 pre = i - dp[i-1] - 1，如果这个位置大于0且为 ( 则可以配队，转移为 dp[i] += dp[pre-1] if pre>=1 else 0。

def longestValidParentheses(s: str) -> int:
    n = len(s)
    dp = [0] * n
    ans = 0

    for i in range(1, n):
        if s[i] == ')':
            if s[i - 1] == '(':
                dp[i] = 2 + (dp[i - 2] if i >= 2 else 0)
            else:
                pre = i - dp[i - 1] - 1
                if pre >= 0 and s[pre] == '(':
                    dp[i] = dp[i - 1] + 2 + (dp[pre - 1] if pre >= 1 else 0)

            ans = max(ans, dp[i])

    return ans

LC139 - 单词拆分

判断s能不能拆分成wordDict词表中的单词，一个直观的方法是直接搜索切分。

from functools import cache

def wordBreak(self, s: str, wordDict: list[str]) -> bool:
    wordSet = set(wordDict)
    @cache
    def dfs(start):
        if start == len(s):
            return True
        for end in range(start,len(s)):
            curr = s[start:end+1]
            if curr in wordSet:
                if dfs(end + 1):
                    return True
        return False
    return dfs(0)

加上cache勉强不超时。不过相信也看出来了，这种题目，不要你具体的切分、答案，只问能不能达成状态，搜索一般不是最好的选择。我们可以用dp[j]表示到下标j为止都可以切分，然后思考遍历词表，就有转移方程: dp[j] = dp[j-len(word)] or dp[j] if s[j-len(word)+1:j+1] in wordSet。（你也看出来了，这样比较变扭，两边都+1，所以我们重新定义状态dp[j]为s[0:j]能拆分吧，这样dp多一位，式子更好看）： dp[j] = dp[j-len(word)] or dp[j] if s[j-len(word):j] in wordSet。

不用wordSet，我们可以把word循环放内部，这样转移方程就进一步简化为了如果 s[j-len(word):j] == word 并且 dp[j-len(word)] == True 那么 dp[j] = True。

def wordBreak(self, s: str, wordDict: list[str]) -> bool:
    n = len(s)
    dp = [False] * (n + 1)
    dp[0] = True

    for j in range(1, n + 1):
        for word in wordDict:
            l = len(word)
            if j >= l and dp[j - l] and s[j - l:j] == word:
                dp[j] = True
                break
    return dp[n]

双序列 DP

LC1143 - 最长公共子序列

这道题有两个字符串，求他们的最长公共子序列，我们用dp[i][j]表示到text1的i位置和text2的j位置的最长公共子序列，实际上就是我们遍历判断的时候，有两种情况的转移：

当text1[i] == text2[j]，有dp[i][j] = dp[i-1][j-1] + 1
当不相等的时候，可能是i移动也可能是j移动，所以转移为 dp[i][j] = max(dp[i-1][j], dp[i][j-1])

我们多开一圈，让ij表示选中text1和text2的数量，最后返回的dp[m][n]即可：

def longestCommonSubsequence(self, text1: str, text2: str) -> int:
    m = len(text1)
    n = len(text2)
    dp = [[0]*(n+1) for _ in range(m+1)]
    for i in range(1,m+1):
        for j in range(1,n+1):
            if text1[i-1] == text2[j-1]:
                dp[i][j] = dp[i-1][j-1] + 1
            else:
                dp[i][j] = max(dp[i-1][j], dp[i][j-1])
    return dp[m][n]

注意这里我们通过多开一圈，把“空前缀”的基础状态显式放进 dp 表里；它们本来就应该是 0，而数组默认就是 0，所以不用额外初始化。否则，如果直接用i、j表示下标的话，需要自己初始化边界。

所以，要不要多开一圈，请仔细思考初始化。

LC1035 - 不相交的线

仔细一想，其实就是最长公共子序列的长度啊。演都不演了，直接搬过来就行了：

def maxUncrossedLines(self, nums1: List[int], nums2: List[int]) -> int:
    m = len(nums1)
    n = len(nums2)
    dp = [[0]*(n+1) for _ in range(m+1)]
    for i in range(1,m+1):
        for j in range(1,n+1):
            if nums1[i-1] == nums2[j-1]:
                dp[i][j] = dp[i-1][j-1] + 1
            else:
                dp[i][j] = max(dp[i-1][j], dp[i][j-1])
    return dp[m][n]

LC718 - 最长重复子数组

这一题是最长公共子序列的连续版（子数组），需要更改转移方程。我们可以借鉴以往的经验，选择dp[i][j]为以 nums1[i-1] 和 nums2[j-1] 结尾的最长公共连续子数组长度，初始化为0。如果nums1[i] == nums2[j]，那么dp[i][j] = dp[i-1][j-1] + 1，一样，但是如果出现 nums1[i] != nums[j]，就要直接归0。很容易理解，如果当前两个数不相等，那以它们结尾的公共连续子数组根本不存在，所以长度只能是 0，而不要求连续的题目中才可能去更新尝试任意一个数组回退一位去寻找最大的。

def findLength(nums1, nums2):
    m, n = len(nums1), len(nums2)
    dp = [[0] * (n + 1) for _ in range(m + 1)]
    ans = 0

    for i in range(1, m + 1):
        for j in range(1, n + 1):
            if nums1[i - 1] == nums2[j - 1]:
                dp[i][j] = dp[i - 1][j - 1] + 1
                ans = max(ans, dp[i][j])
    return ans

LC583 - 两个字符串的删除操作

其实吧，这一题可以直接求最长重复子序列，然后多出来都就是都要删除的。比如我们把LC1143拿过来，然后最后返回一个删除的数目：

def minDistance(self, word1: str, word2: str) -> int:
    m = len(word1)
    n = len(word2)
    dp = [[0]*(n+1) for _ in range(m+1)]
    for i in range(1,m+1):
        for j in range(1,n+1):
            if word1[i-1] == word2[j-1]:
                dp[i][j] = dp[i-1][j-1] + 1
            else:
                dp[i][j] = max(dp[i-1][j], dp[i][j-1])
    return m-dp[m][n]+n-dp[m][n]

不过锻炼dp思维，可以重新dp一下。我们用dp[i][j]表示以word1[i-1]和word2[j-1]结尾要想一样需要删除的字符串数目。当两者一样的时候，不用删，也就是dp[i][j] = dp[i-1][j-1]；当两者不一样的时候，可以选择任意一方删除 dp[i][j] = min(dp[i-1][j]+1,dp[i][j-1]+1)。这里最容易想错，你可以理解为当前的dp[i][j]可能是i-1删一个过来或者j-1删一个过来，删就是无条件跳过。

但是这一题需要额外注意的是初始状态，不是全0。当i或j等于0的时候，需要把另外一个删除才行。

def minDistance(self, word1: str, word2: str) -> int:
    m = len(word1)
    n = len(word2)
    dp = [[0]*(n+1) for _ in range(m+1)]

    for i in range(m+1):
        dp[i][0] = i
    
    for j in range(n+1):
        dp[0][j] = j

    for i in range(1,m+1):
        for j in range(1,n+1):
            if word1[i-1] == word2[j-1]:
                dp[i][j] = dp[i-1][j-1]
            else:
                dp[i][j] = min(dp[i-1][j]+1,dp[i][j-1]+1)
    return dp[m][n]

LC72 - 编辑距离

这一题在上一题上更进一步，有三种选择，我们再次尝试思考一下。初始化跟上一题一样，然后，如果word1[i] == word2[j]，则dp[i][j] = dp[i-1][j-1] 不用操作。如果不一样，可能是三种操作造成的，承接这三种情况的状态，分别是：

插入了一个字符，其实就是相对于word1，word2多走一格，即 dp[i][j] = dp[i][j-1]+1 。比如，abce和abcde，当走到c和d的时候，我们word1插入一个d即可，相对而言，就是都选c的dp加上一步操作即可。
删除了一个字符，也就是上一题的情况，word1多了一个字母，状态就是 dp[i][j] = dp[i-1][j] + 1。
替换一个字符，就是 dp[i][j] = dp[i-1][j-1] + 1，直接替换不一样的结尾。

然后，这三种情况选择一个最小的即可。

def minDistance(self, word1: str, word2: str) -> int:
    m, n = len(word1), len(word2)
    dp = [[0]*(n+1) for _ in range(m+1)]
    for i in range(m+1):
        dp[i][0] = i
    for j in range(n+1):
        dp[0][j] = j

    for i in range(1,m+1):
        for j in range(1,n+1):
            if word1[i-1] == word2[j-1]:
                dp[i][j] = dp[i-1][j-1]
            else:
                dp[i][j] = min(
                    dp[i-1][j] + 1,
                    dp[i][j-1] + 1,
                    dp[i-1][j-1] + 1
                )
    return dp[m][n]

LC115 - 不同的子序列

这一题是给两个字符串s和t，统计s的子序列中t出现的个数。我们可以理解成，通过多少种删除操作，可以让s变成t，注意是只能删s。所以，两个不相等的时候，转移就是删一个s的得到 dp[i][j] = dp[i-1][j]；但是如果两个相等，情况不止是直接从dp[i-1][j-1]转移过来，也可能是删了一个重复相等去删一个s的情况（比如rabbb和rabb的时候，虽然相等，但是可以删一个b让后面t出现），所以转移其实是 dp[i][j] = dp[i-1][j-1] + dp[i-1][j]。

删除操作的题目时，如果出现了一样，可以不用管直接从dp[i-1][j-1]转移即可，因为最小删除次数，对保留一对相等字符一定不会多操作。拿rabbb和rabb，就算不删，从这三个b中删除任何一个，都是一次操作，无所谓。但是换成本题，其实有三种删法，也就是答案是3，这就是转移方程差距的来源了。

另外，边界初始化也要更改。当t为空的时候，其实只有一种序列出现在s中，就是空序列，也就是dp[i][0]全1。

def numDistinct(self, s: str, t: str) -> int:
    m = len(s)
    n = len(t)
    dp = [[0]*(n+1) for _ in range(m+1)]

    for i in range(m+1):
        dp[i][0] = 1

    for i in range(1,m+1):
        for j in range(1,n+1):
            if s[i-1] == t[j-1]:
                dp[i][j] = dp[i-1][j-1] + dp[i-1][j]
            else:
                dp[i][j] = dp[i-1][j]
    return dp[m][n]

子序列 DP 常见模板

# 单序列不连续（LIS）
dp = [1] * n
for j in range(n):
    for i in range(j):
        if nums[i] < nums[j]:
            dp[j] = max(dp[j], dp[i] + 1)

# 单序列连续（LCIS）
dp = [1] * n
for j in range(1, n):
    if nums[j-1] < nums[j]:
        dp[j] = dp[j-1] + 1

# 双序列（LCS）
dp = [[0]*(n+1) for _ in range(m+1)]
for i in range(1, m+1):
    for j in range(1, n+1):
        if s[i-1] == t[j-1]:
            dp[i][j] = dp[i-1][j-1] + 1
        else:
            dp[i][j] = max(dp[i-1][j], dp[i][j-1])

回文 DP

回文 DP 的核心理解

回文 DP 定义一个二维布尔数组 dp[i][j] 表示 s[i:j+1] 是否为回文。转移的核心逻辑是两端字符相等时，向里收缩：

s[i] == s[j] 且 j-i <= 2 → 直接是回文（1~3 个字符）
s[i] == s[j] 且 dp[i+1][j-1] 为真 → 是真回文

遍历顺序是 i 倒序（从右到左）、j 正序（从左到右），因为 dp[i][j] 依赖 dp[i+1][j-1]（更靠里的小区间）。也可以按区间长度递增遍历。

回文子序列不要求连续，不相等时可以跳过一端（和 LCS 类似）。

LC5 - 最长回文子串

这一题通常有两种解法，一种是中心扩散，一种是二维dp。中心扩散法时，我们定义一个expand函数，然后分奇偶从每个可能的中心开始调用expand，更新为较长的即可。

def longestPalindrome(self, s: str) -> str:
    def expand(i,j)->tuple[int,int]:
        while i>=0 and j<len(s) and s[i] == s[j]:
            i-=1
            j+=1
        return i+1,j-1
    
    start = end = 0

    for i in range(len(s)):
        l1,r1 = expand(i,i)
        l2,r2 = expand(i,i+1)
        if r1 - l1 > end - start:
            start, end = l1, r1
        if r2 - l2 > end - start:
            start, end = l2, r2
    return s[start:end+1]

而这一题的另一种做法，就是二维dp。我们用dp[i][j] = s[i:j+1] 是否是回文串，如果两端相等，当 j-i<=2 就直接是回文，否则要看里面的 s[i+1:j] 是否是回文。

def longestPalindrome(s: str) -> str:
    n = len(s)
    dp = [[False] * n for _ in range(n)]
    start = 0
    max_len = 1

    for i in range(n - 1, -1, -1):
        for j in range(i, n):
            if s[i] == s[j] and (j - i <= 2 or dp[i + 1][j - 1]):
                dp[i][j] = True
                if j - i + 1 > max_len:
                    start = i
                    max_len = j - i + 1

    return s[start:start + max_len]

这里注意，i是倒序的，因为dp[i][j]依赖dp[i+1][j-1]，所以要先算靠里面的区间。

另外，我们从长度出发，因为两个端点是相互依赖的，所以我们可以循环长度来做。

def longestPalindrome(s: str) -> str:
    # dp[i][j]表示s[i:j+1]是否为回文串
    n = len(s)
    dp = [[False]*n for _ in range(n)]
    for i in range(n):
        dp[i][i] = True

    # 要返回子字符串额外需要的变量
    start = 0
    max_len = 1

    for length in range(2,n+1):
        for i in range(n-length+1):
            j = i + length - 1 
            if s[i] != s[j]:
                dp[i][j] = False
            else:
                if length<=3:
                    dp[i][j] = True
                else:
                    dp[i][j] = dp[i+1][j-1]
            # 拿答案
            (start, max_len) = (i, length) if dp[i][j] and length>max_len else (start, max_len)

    return s[start:start+max_len]

LC647 - 回文子串

这一题，统计回文子串的数目。我们也可以想到用dp来做，同样dp[i][j]表示s[i:j+1]，每次找到回文子串就+1返回ans即可。

def countSubstrings(s: str) -> int:
    n = len(s)
    dp = [[False] * n for _ in range(n)]
    ans = 0

    for i in range(n - 1, -1, -1):
        for j in range(i, n):
            if s[i] == s[j] and (j - i <= 2 or dp[i + 1][j - 1]):
                dp[i][j] = True
                ans += 1

    return ans

LC516 - 最长回文子序列

这一题，回文子串变成了回文子序列，也就是说不要求连续了。我们知道，回到非连续的题，我们在不相等的时候，可以选择任意一遍移动继续去寻找，然后取最大/最小。所以这一题，两端不相等的时候，我们去找 dp[i][j] = max(dp[i + 1][j], dp[i][j - 1])；而两端相等的时候，直接+2即可。

def longestPalindromeSubseq(s: str) -> int:
    n = len(s)
    dp = [[0] * n for _ in range(n)]

    for i in range(n - 1, -1, -1):
        dp[i][i] = 1
        for j in range(i + 1, n):
            if s[i] == s[j]:
                dp[i][j] = dp[i + 1][j - 1] + 2
            else:
                dp[i][j] = max(dp[i + 1][j], dp[i][j - 1])

    return dp[0][n - 1]

这里注意，返回的dp[0][n-1]，也就是整个串。

LC1312 - 让字符串成为回文串的最少插入次数

同理，这一题的转移不相等的时候可以写成 dp[i][j] = min(dp[i+1][j] + 1, dp[i][j-1] + 1)；相等的话dp[i][j] = dp[i+1][j-1]。（右边插入，等效于和左边往前走一步的dp+1一样结果，比如abcb，插入abcba，新dp等效于bcb+1）

def minInsertions(s: str) -> int:
    n = len(s)
    dp = [[0] * n for _ in range(n)]

    for i in range(n - 1, -1, -1):
        for j in range(i + 1, n):
            if s[i] == s[j]:
                dp[i][j] = dp[i + 1][j - 1]
            else:
                dp[i][j] = min(dp[i + 1][j], dp[i][j - 1]) + 1

    return dp[0][n - 1]

回文 DP 常见模板

# 回文子串/子序列 DP，i 倒序 j 正序
for i in range(n-1, -1, -1):
    for j in range(i, n):
        if s[i] == s[j]:
            if j - i <= 2:
                dp[i][j] = True  # 或 j-i+1 (长度)
            else:
                dp[i][j] = dp[i+1][j-1]  # 或 dp[i+1][j-1] + 2

# 回文子序列（不连续）
for i in range(n-1, -1, -1):
    dp[i][i] = 1
    for j in range(i+1, n):
        if s[i] == s[j]:
            dp[i][j] = dp[i+1][j-1] + 2
        else:
            dp[i][j] = max(dp[i+1][j], dp[i][j-1])

股票买卖 DP

股票 DP 的核心理解

股票类 DP 统一使用两个核心状态（状态机）：

hold：今天结束后手里有股票，所能达到的最大利润（买入花掉的钱也算进去，所以通常为负或减少）
cash：今天结束后手里没股票，所能达到的最大利润

每天的转移方程只有两个：

cash = max(cash, hold + price)        # 不动 vs 卖出
hold = max(hold, X - price)           # 不动 vs 买入

所有变体的唯一区别就是买入时用来减的 X 是什么：

题目	X	含义
LC121（限 1 次）	`0`	只能买一次，没有历史利润
LC122（无限次）	`cash`	用累积利润继续买
LC123（限 2 次）	`sell1`	第二次买依赖第一次卖的利润
LC188（限 k 次）	`sell[t-1]`	第 t 次买依赖 t-1 次卖的利润
LC309（冷冻期）	`cash_before_yesterday`	卖出后隔一天才能买
LC714（手续费）	`cash`（同 122）	卖时扣 `fee`

LC121 - 买卖股票的最佳时机

常规解法是维持当前最小值，算所有点的利润。

def maxProfit(self, prices: list[int]) -> int:
    min_price = float("INF")
    max_profit = 0
    for price in prices:
        min_price = price if price<min_price else min_price
        max_profit = max(max_profit,price-min_price)
    return max_profit

那么为什么放在dp里面呢，我们可以将dp[j]定义为在j下标的时候可以获得最大的利润，然后我们可以在每个位置从头开始循环到j，找到 prices[i] < prices[j] 之后，用转移 dp[j] = dp[i] + (prices[j]-prices[i]) 更新利润。

def maxProfit(prices: list[int]) -> int:
    n = len(prices)
    dp = [0] * n
    for j in range(1,n):
        for i in range(j):
            if prices[i] < prices[j]:
                dp[j] = max(dp[i] + (prices[j]-prices[i]),dp[j])
    return max(dp)

不过这个法子太朴素所以直接超时了。这里，我们引入通杀股票问题的股票DP，它定义了两个状态，hold 是“如果我今天收盘手里必须有股票，我最多还能剩多少钱”；cash 是“如果我今天收盘手里必须没股票，我最多已经赚多少钱”。其实就是分开算买股票花的钱和卖股票赚的钱，最后去返回cash即可。

那么，第一天的hold，我赚不了钱，利润只能是 -prices[0]，买入第一天的股票。cash收盘也拿不到现金。

我们举个最小例子，比如[7, 1, 5]。初始持股 hold = -7，cash = 0。遇到价格1的时候，先算这一天直接卖出，cash = max(0, -7+1) = 0，显然不合算，然后再更新hold， hold = max(-7, -1) = -1，也就是说，这一天买入比前一天买入好，所以更新hold 为 -1 ；遇到5的时候，cash = max(0, -1 + 5) = 4，说明卖出可得4元，然后再更新 hold = max(-1, -5) = -1，说明还是捏着-1比较好。

def maxProfit(self, prices: list[int]) -> int:
    hold = -prices[0]
    cash = 0

    for price in prices[1:]:
        new_cash = max(cash, hold + price)
        new_hold = max(hold, -price)

        cash = new_cash
        hold = new_hold

    return cash

LC122 - 买卖股票的最佳时机 II

买卖股票II允许你在持股一个的情况下，每天都可以多次买卖，最后得到的利润总和要最大。所以，我们在定义的时候，cash可以差不多，都是 cash = max(cash, hold + price)，但是hold不能再简单取最小的买入代价。之前，只能交易一次，如果今天买入，说明之前没有交易，收益为0，所以只能结果是 hold = max(hold, 0-price)；而这一题则是可能有cash了，hold = max(hold, cash - price)。

只需要改变一行。

def maxProfit(self, prices: list[int]) -> int:
    hold = -prices[0]
    cash = 0

    for price in prices[1:]:
        new_cash = max(cash, hold + price)
        new_hold = max(hold, cash - price)

        cash = new_cash
        hold = new_hold

    return cash

LC123 - 买卖股票的最佳时机 III

这一题，给定一个数组，它的第 i 个元素是一支给定的股票在第 i 天的价格，且最多只能完成两比交易。所以这一题，我们其实可以看成两个买卖股票I，第二次的buy要承接第一次sell得到的利润，因为不能同时交易，买二必先卖一。

def maxProfit(self, prices: list[int]) -> int:
    buy1 = -prices[0]
    sell1 = 0
    buy2 = -prices[0]
    sell2 = 0

    for price in prices[1:]:
        new_buy1 = max(buy1, -price)
        new_sell1 = max(sell1, buy1 + price)

        new_buy2 = max(buy2, sell1 - price)
        new_sell2 = max(sell2, buy2 + price)

        buy1, sell1, buy2, sell2 = new_buy1, new_sell1, new_buy2, new_sell2

    return sell2

LC188 - 买卖股票的最佳时机 IV

这一题再次升级，最多重复买卖k次，但是依然不能同时交易。其实就是将LC123的四个状态推广成循环，变成“buy[1], sell[1], buy[2], sell[2], ..., buy[k], sell[k]”。

def maxProfit(self, prices: list[int]) -> int:
    n = len(prices)
    if n == 0 or k == 0:
        return 0

    buy = [-10**18] * (k + 1)
    sell = [0] * (k + 1)

    for t in range(1, k + 1):
        buy[t] = -prices[0]

    for price in prices[1:]:
        new_buy = buy[:]
        new_sell = sell[:]

        for t in range(1, k + 1):
            new_buy[t] = max(buy[t], sell[t - 1] - price)
            new_sell[t] = max(sell[t], buy[t] + price)

        buy, sell = new_buy, new_sell

    return sell[k]

LC309 - 买卖股票的最佳时机含冷冻期

这一题给股票买卖带来了冷冻期，卖出股票无法第二天买入。所以，我们的新hold必须要是前天的cash来减。要改的只有这里。

def maxProfit(self, prices: list[int]) -> int:
    n = len(prices)
    if n == 0:
        return 0
    hold = -prices[0]
    cash_before_yesterday = 0
    cash = 0

    for price in prices:
        new_cash = max(cash,hold + price)
        new_hold = max(hold,cash_before_yesterday-price)

        cash_before_yesterday = cash
        cash = new_cash
        hold = new_hold
    return cash

LC714 - 买卖股票的最佳时机含手续费

这一题和LC122（无限次买卖）相比，只是多了一个手续费，更改一下cash的更新即可解决。

def maxProfit(self, prices: list[int], fee: int) -> int:
    n = len(prices)
    if n == 0:
        return 0
    hold = -prices[0]
    cash = 0

    for price in prices:
        new_cash = max(cash,hold + price - fee)
        new_hold = max(hold,cash - price)

        cash = new_cash
        hold = new_hold
    return cash

股票 DP 常见模板

# 通用股票模板（LC122 无限次交易）
hold, cash = -prices[0], 0
for price in prices[1:]:
    cash = max(cash, hold + price)      # 卖出
    hold = max(hold, cash - price)      # 买入
return cash

# k 次交易（LC188）
buy = [-inf] * (k+1); sell = [0] * (k+1)
for t in range(1, k+1):
    buy[t] = -prices[0]
for price in prices[1:]:
    for t in range(1, k+1):
        buy[t] = max(buy[t], sell[t-1] - price)
        sell[t] = max(sell[t], buy[t] + price)
return sell[k]

区间 DP

区间 DP 的核心理解

区间 DP 的状态定义在 [i, j] 这个区间上，大区间的解通过枚举分割点 k，由两个小区间合并得到：

dp[i][j] = min/max(dp[i][k] + dp[k][j] + cost(i,j,k))

遍历顺序：按区间长度从小到大（或 i 倒序 j 正序），确保小区间先算好。

两种常见形式：

两端收缩：dp[i][j] 由 dp[i+1][j] 和 dp[i][j-1] 转移（回文 DP、石子游戏）
中间切分：枚举 k 把 [i,j] 切成两段（戳气球、三角剖分）

LC486 - 预测赢家

预测赢家在dfs中，是标准的对位dfs解法。我们让双方轮流dfs。

from functools import cache

def predictTheWinner(self, nums: list[int]) -> bool:
    # dfs返回的是第一视角下，能赢对手多少分
    @cache
    def dfs(left:int,right:int)->int:
        if left == right:
            return nums[left]
        # 自己加的分 - 对方能多拿的分
        take_left = nums[left] - dfs(left+1,right)
        take_right = nums[right] - dfs(left,right-1)
        return max(take_left,take_right)
    # 先手(玩家1)优势为正数胜利
    return dfs(0,len(nums)-1)>=0

而既然放在这里，那就是使用区间DP的方法来解决。大区间的解，可以通过小区间解决出来。回文 DP（LC5、LC516）其实也算区间 DP 的特例，典型的区间DP是枚举中间切点转移。

我们可以定义 dp[i][j] 为[i,j]上先手能净胜的分数，那么很容易写出转化方程为 dp[i][j] = nums[i] - dp[i+1][j]（对手拿右边你拿左边）, dp[i][j] = nums[j] - dp[i][j-1]（对手拿左边你拿右边），这两者取最大的。显然，又要i倒序j正序。

def predictTheWinner(self, nums: list[int]) -> bool:
    n = len(nums)
    dp = [[0]*n for _ in range(n)] 

    # 初始化（区间成点初始）
    for i in range(n):
        dp[i][i] = nums[i]

    for i in range(n-2,-1,-1):
        for j in range(i+1,n):
            dp[i][j] = max(nums[i]-dp[i+1][j],nums[j]-dp[i][j-1])
    return dp[0][n-1]>=0

LC877 - 石子游戏

这一题先手必赢来着，但是我们还是用dp做一下吧。依旧设dp[i][j]为区间[i,j]下Alice能获得的相对优势，对角线初始化一下。

def stoneGame(self, piles: list[int]) -> bool:
    n = len(piles)
    dp = [[0]*n for _ in range(n)]
    for i in range(n):
        dp[i][i] = piles[i]
    
    for i in range(n-2,-1,-1):
        for j in range(i+1,n):
            dp[i][j] = max(piles[i] - dp[i+1][j], piles[j] - dp[i][j-1])
    return dp[0][n-1]>0

LC312 - 戳气球

如果直接想先去戳哪个气球，很难拆分成子问题。我们将dp[i][j]定义为i、j不戳，中间戳完的收益。显然，区间只剩一个k的时候，左右邻居一定是i和j，得到的收益是nums[i]*nums[k]*nums[j]。

那这又有啥用呢？当然有用，我们可以继续往里面拆分，总会有一个情况只有短区间，k是i、j里面唯一的气球，这样就可以推到外面的了。所以，我们枚举最后一个戳的气球k拆分成两个子问题，转移方程为： dp[i][j] = max(dp[i][k] + dp[k][j] + nums[i] * nums[k] * nums[j])。

然后，我们按照长度从短到长遍历，在固定长度中寻找i、j端点，然后再从其中遍历切割点k，这样就可以做到从里到外覆盖所有情况了。如果你有印象，在最长回文子串的时候我们就这么做过。

def maxCoins(self, nums: list[int]) -> int:
    # 补充哨兵
    vals = [1] + nums + [1]          
    m = len(vals)
    dp = [[0] * m for _ in range(m)]
    for length in range(2, m):
        for i in range(m - length):  
            j = i + length           
            for k in range(i + 1, j): 
                dp[i][j] = max(
                    dp[i][j],
                    dp[i][k] + dp[k][j] + vals[i] * vals[k] * vals[j]
                )
    return dp[0][m - 1]

这个题当然也可以像之前那样遍历，因为dp[i][k]：k < j，同一次外层 i 循环里 j 是正序的，dp[i][k] 已经算过，而dp[k][j]：k > i，i 倒序，所以 dp[k][j] 在上几轮外层已经算过。只不过这题按照长度更直观，不过还是写一下吧：

def maxCoins(self, nums: list[int]) -> int:
    vals = [1] + nums + [1]
    m = len(vals)
    dp = [[0] * m for _ in range(m)]

    for i in range(m - 1, -1, -1):
        for j in range(i + 2, m):
            for k in range(i + 1, j):
                dp[i][j] = max(dp[i][j],
                    dp[i][k] + dp[k][j] + vals[i] * vals[k] * vals[j])

    return dp[0][m - 1]

LC1039 - 多边形三角剖分的最低得分

你有一个凸的 n 边形，其每个顶点都有一个整数值。给定一个整数数组 values ，其中 values[i] 是按顺时针顺序第 i 个顶点的值。

假设将多边形剖分为 n - 2 个三角形。对于每个三角形，该三角形的值是顶点标记的乘积，三角剖分的分数是进行三角剖分后所有 n - 2 个三角形的值之和。

返回多边形进行三角剖分后可以得到的最低分。

我们必须要解释一下这题，不然根本写不好。实际上，这个多边形的三角剖分，可以直接换成选一条(i,j)做底边，然后枚举顶点k组成三角形，最后再把左右两块丢给递归。

我们定义dp[i][j]是切开后选择的底边，然后枚举k作为第三个顶点，那么有单词收益是values[i]*values[k]*values[j]，然后可以继续dp[i][k]+dp[k][j]，直到j-i是2的时候，不用选了只有一种可能。所以，这一题简直是和戳气球一模一样！

def minScoreTriangulation(self, values: list[int]) -> int:
    n = len(values)
    dp = [[0] * n for _ in range(n)]

    for gap in range(2, n):
        for i in range(n - gap):
            j = i + gap
            dp[i][j] = float('inf')
            for k in range(i + 1, j):
                dp[i][j] = min(dp[i][j],
                    dp[i][k] + dp[k][j] + values[i] * values[k] * values[j])

    return dp[0][n - 1]

区间 DP 常见模板

# 按 gap（j-i）遍历
for gap in range(min_gap, n):
    for i in range(n - gap):
        j = i + gap
        for k in range(i + 1, j):    # 枚举分割点
            dp[i][j] = min(dp[i][j], dp[i][k] + dp[k][j] + cost)

# 两端收缩（石子游戏等）
for i in range(n-2, -1, -1):
    for j in range(i+1, n):
        dp[i][j] = max(nums[i] - dp[i+1][j], nums[j] - dp[i][j-1])

用 gap = j - i 而非 length 来迭代，可以统一戳气球（开区间）和回文子串（闭区间）的写法，只改 min_gap（1 是闭区间，2 是开区间）。

树形 DP

树形 DP 的核心理解

树形 DP 是在树上做 DP——子节点的 DP 值算好后，再算父节点，底层逻辑是后序遍历。和线性 DP 的区别只是：状态依赖的不是 dp[i-1]，而是 dp[left.child] 和 dp[right.child]。

树形 DP 的递归 dfs 返回包含所有必要状态的元组，每个节点根据子节点的返回值计算自己的状态，并更新全局答案。

LC543 - 二叉树的直径

还是先来复习这一题本来的做法。我们递归让每个结点都有机会做中转点来更新最长直径，然后我们递归的时候为了方便计算直径只返回以这条边为起点的最长长度。

def diameterOfBinaryTree(self, root: TreeNode):
    max_len = 0
    def dfs(node:TreeNode)->int:
        nonlocal max_len
        if not node:
            return 0
        left_len = dfs(node.left)
        right_len = dfs(node.right)
        # 题目要算的是边数
        max_len = max(left_len + right_len, max_len)
        return max(left_len+1,right_len+1)
    dfs(root)
    return max_len

那到底是什么是树形dp？其实啊，树形 DP 就是在树上做 DP（划掉）。就是子节点的 DP 值算好了，再算父节点的。底层的逻辑就是后序遍历。然后这种dfs其实就是树形dp的标准写法了（除非你想从叶子到根一个一个填）。这也得益于树本身没有重叠子问题，不需要cache也不需要dp优化。

LC124 - 二叉树中的最大路径和

和上一题的区别仅仅在于多了个节点值，相信会了上题也是秒杀的。不过我容易犯错，主要是现在val可能有负数了，加上不一定是正收益，所以我们要即使截断负数（后序的话负数只会作为0传上来）：

class TreeNode:
    def __init__(self, val = 0, left = None, right = None):
        self.val = val
        self.left = left
        self.right = right

def maxPathSum(self, root: TreeNode) -> int:
    max_val = float('-INF')
    def dfs(node:TreeNode)->int:
        nonlocal max_val
        if not node:
            return 0
        left_val = max(dfs(node.left),0)
        right_val = max(dfs(node.right),0)

        max_val = max(left_val+right_val+node.val,max_val)

        return max(left_val,right_val) + node.val
    dfs(root)
    return max_val

LC968 - 监控二叉树

给定一个二叉树，我们在树的节点上安装摄像头。节点上的每个摄影头都可以监视其父对象、自身及其直接子对象。计算监控树的所有节点所需的最小摄像头数量。

这一题是三状态树形dp，被父亲监控、被孩子监控、自己带着监控。

class TreeNode:
    def __init__(self, val = 0, left = None, right = None):
        self.val = val
        self.left = left
        self.right = right

def minCameraCover(self, root: TreeNode) -> int:
    def dfs(node):
        if not node:
            return float('inf'), 0, 0  # 空节点不可能有摄像头

        l_cam, l_by_child, l_by_parent = dfs(node.left)
        r_cam, r_by_child, r_by_parent = dfs(node.right)

        # 放摄像头：左右孩子爱怎样怎样，我已经全覆盖了
        with_cam = 1 + min(l_cam, l_by_child, l_by_parent) + min(r_cam, r_by_child, r_by_parent)

        # 被孩子覆盖：左右孩子至少有一个放摄像头
        by_child = min(l_cam + min(r_cam, r_by_child),r_cam + min(l_cam, l_by_child))

        # 被父节点覆盖：左右孩子不能指望父节点（父被更上层覆盖），只能靠自己或自己孩子
        by_parent = min(l_cam, l_by_child) + min(r_cam, r_by_child)

        return with_cam, by_child, by_parent
    # 根没有父节点
    return min(dfs(root)[:2])

LC337 - 打家劫舍 III

打家劫舍III是树形小区，解法也是树形dp。我们让dfs返回这里偷或者不偷的最高收益，每个节点偷或不偷的收益可以用两种转移方程解决，分别是这个偷左右都不偷和这个不偷，左右偷的较大收益。

def rob(self, root: TreeNode) -> int:
    def dfs(node):
        if not node:
            return (0, 0)

        left_rob, left_not_rob = dfs(node.left)
        right_rob, right_not_rob = dfs(node.right)

        rob_cur = node.val + left_not_rob + right_not_rob
        not_rob_cur = max(left_rob, left_not_rob) + max(right_rob, right_not_rob)

        return (rob_cur, not_rob_cur)

    return max(dfs(root))

树形 DP 常见模板

# 通用树形 DP 框架
ans = 0
def dfs(node):
    nonlocal ans
    if not node:
        return base_case
    left = dfs(node.left)
    right = dfs(node.right)
    ans = max(ans, left + right)      # 用子节点更新全局答案
    return max(left, right) + 1       # 返回当前节点的 DP 值
return ans

# 状态机树形 DP（如 LC968）
def dfs(node):
    if not node:
        return inf, 0, 0  # 空节点不能有摄像头
    l_cam, l_covered, l_not = dfs(node.left)
    r_cam, r_covered, r_not = dfs(node.right)
    cam = 1 + min(l_cam, l_covered, l_not) + min(r_cam, r_covered, r_not)
    covered = min(l_cam + min(r_cam, r_covered), r_cam + min(l_cam, l_covered))
    not_covered = min(l_cam, l_covered) + min(r_cam, r_covered)
    return cam, covered, not_covered
return min(dfs(root)[:2])

树形 DP 天然适合递归写法，树没有重叠子问题，不需要 @cache。

状态压缩 DP

状态压缩的核心理解

当 n 很小（≤ 20~25）且决策只关心"哪些元素已经被用了"，可以把选中集合压缩成一个二进制整数 mask。mask 的第 i 位是 1 表示第 i 个元素已被选用。

核心位运算：

1 << n：状态总数（2^n）
1 << i：只有第 i 位为 1 的面具
mask & (1 << i)：检查第 i 位是否为 1（读）
mask | (1 << i)：将第 i 位设为 1（写）
mask.bit_count()：统计 mask 中有多少个 1

LC698 - 划分为 K 个相等的子集

还记得之前的做法吗，是桶划分。我们要分成k个非空子集，就要去装k个桶。我们先算出k个桶的容积，然后从最大的数开始dfs，放桶，如果第一个都放不下，就没有放的必要了，如果最后放满了桶就成功了。

def canPartitionKSubsets(self, nums: list[int], k: int) -> bool:
    total = sum(nums)

    if total % k != 0:
        return False
    
    target = total // k
    nums.sort(reverse=True)

    if nums[0]>target:
        return False
    
    buckets = [0] * k

    def dfs(index:int)->bool:
        if index == len(nums):
            return all(bucket == target for bucket in buckets)
        num = nums[index]
        for i in range(k):
            if buckets[i] + num > target:
                continue
            buckets[i] += num
            if dfs(index+1):
                return True
            buckets[i] -= num

            # 放空桶都失败了直接裁剪
            if buckets[i] == 0:
                return False
        return False
    return dfs(0)

那么，这一题既然放在状态压缩dp，是什么意思呢？回溯法虽然容易理解，但是每次要做两种选择，剪枝能让它不爆炸但绝不是最优。最优的方式是用n个数字的“用没用”编码成n位二进制数mask，比如n=5，用mask = 01001表示第0个和第3个数已经被选了。

此时，用dp[mask]来表示当前正在处理的桶装了多少，就不用维持很多桶了，因为每个桶的容量一样，我们只看当前选择有没有装满，最后只要判断dp[全1]也就是全部都被选了一遍就可以了。（不熟悉位运算的话，mask & (1 << i)是判断第i位是不是1，mask | (1 << i)是将第i位变成1）

def canPartitionKSubsets(self, nums: list[int], k: int) -> bool:
    total = sum(nums)
    if total % k != 0:
        return False
    target = total // k

    n = len(nums)
    # dp记录状态为mask下当前桶装了多少
    dp = [-1] * (1 << n)   
    dp[0] = 0
    # 1<<n就是2^n个状态，即每个数字选或不选
    for mask in range(1 << n):
        if dp[mask] == -1:  # 不可达，跳过
            continue
        for i in range(n):
            # 检查第i位是不是1
            if mask & (1 << i):
                continue
            cur = dp[mask] + nums[i]
            if cur > target:
                continue
            # cur == target → cur % target == 0：当前桶刚好满，清零，下一个数字进新桶
            # cur < target → cur % target == cur：当前桶还没满，继续往里装
            dp[mask | (1 << i)] = cur % target
    return dp[(1 << n) - 1] == 0

LC473 - 火柴拼正方形

还是先用传统桶dfs来做一下。

def makesquare(self, matchsticks: list[int]) -> bool:
    total = sum(matchsticks)
    n = len(matchsticks)
    if total % 4 != 0:
        return False
    target = total // 4
    buckets = [0]*4
    matchsticks.sort(reverse=True)
    def dfs(i):
        if i == n:
            return all(bucket == target for bucket in buckets)
        matchstick = matchsticks[i]
        for k in range(4):
            if buckets[k]+matchstick>target:
                continue
            buckets[k] += matchstick
            if dfs(i+1):
                return True
            buckets[k] -= matchstick

            # 如果空桶放入失败，则肯定失败
            if buckets[k] == 0:
                return False
        return False
    return dfs(0)

@cache 只在状态完全由函数参数决定时安全。有外部可变变量时，缓存键不包含它，等于把不同状态误判成同一个。所以要先用cache，我们需要将桶也编码进去，但是这样状态数爆炸，还不如mask压缩。

我们尝试用上一题的mask压缩。

def makesquare(self, matchsticks: list[int]) -> bool:
    total = sum(matchsticks)
    n = len(matchsticks)
    if total % 4 != 0:
        return False
    target = total // 4
    dp = [-1] * (1<<n)
    dp[0] = 0
    for mask in range(1<<n):
        if dp[mask] == -1:
            continue
        for i in range(n):
            if mask & (1<<i):
                continue
            curr = matchsticks[i] + dp[mask]
            if curr > target:
                continue
            dp[mask|(1<<i)] = curr % target
    return dp[(1<<n)-1] == 0

LC464 - 我能赢吗

两个玩家可以轮流从公共整数池中抽取，不使用重复数字，达到或超过desiredTotal即胜利。

给定两个整数 maxChoosableInteger （整数池中可选择的最大数）和 desiredTotal（累计和），若先出手的玩家能稳赢则返回 true ，否则返回 false 。假设两位玩家游戏时都表现最佳。

这一题比起维持一个是否选过的数组，更方便的做法是状态压缩，也就是用mask来表示。

from functools import cache

def canIWin(self, maxChoosableInteger: int, desiredTotal: int) -> bool:
    if desiredTotal == 0:
        return True
    # 加起来数字都超不过
    if (1 + maxChoosableInteger) * maxChoosableInteger // 2 < desiredTotal:
        return False
    @cache
    def dfs(mask: int, total: int) -> bool:
        # 对面已经把 total 减到 ≤0 了
        if total <= 0:
            return False
        for i in range(1, maxChoosableInteger + 1):
            # 按下标减少1
            bit = 1 << (i - 1)
            # 用过了
            if mask & bit:
                continue
            # i大于剩下的total，我赢了
            if i >= total:
                return True
            # 我选 i，轮到对手。对手在新局面里输 → 我赢
            if not dfs(mask | bit, total - i):
                return True
        return False
    return dfs(0, desiredTotal)

当然也可以迭代用dp数组，但是说实话没必要，所以算了。

LC526 - 优美的排列

假设有从 1 到 n 的 n 个整数。用这些整数构造一个数组 perm（下标从 1 开始），只要满足下述条件之一，该数组就是一个优美的排列：

perm[i] 能够被 i 整除
i 能够被 perm[i] 整除

给你一个整数 n ，返回可以构造的优美排列的数量。

同样是1-n选一个放在某个下标下，我们可以用压缩工具mask，然后把状态压缩到这个数字中。我们可以将遍历所有位置，如果这个数字能放进当前小标（能被整除或者能整除，取决于大小），就先放进去然后再dfs下一个数字。所以，dfs放mask，并返回满足的数量。

from functools import cache

def countArrangement(self, n: int) -> int:
    @cache
    def dfs(mask: int) -> int:
        # 统计填了多少个1了，+1表示目前要填的位置编号
        pos = mask.bit_count() + 1
        if pos > n:
            return 1
        ans = 0
        for num in range(1, n + 1):
            bit = 1 << (num - 1)
            if mask & bit:
                continue
            if num % pos == 0 or pos % num == 0:
                ans += dfs(mask | bit)
        return ans
    return dfs(0)

状态压缩 DP 常见模板

# 背包式状态压缩（LC698）
dp = [-1] * (1 << n)
dp[0] = 0
for mask in range(1 << n):
    if dp[mask] == -1:
        continue
    for i in range(n):
        if mask & (1 << i):
            continue
        cur = dp[mask] + nums[i]
        if cur > target:
            continue
        dp[mask | (1 << i)] = cur % target
return dp[(1 << n) - 1] == 0

# DFS + cache 式状态压缩（LC464）
@cache
def dfs(mask, total):
    for i in range(1, n + 1):
        bit = 1 << (i - 1)
        if mask & bit:
            continue
        if i >= total:
            return True
        if not dfs(mask | bit, total - i):
            return True
    return False

状态压缩 DP 的 n 上限约 20~25（2^20 ≈ 1M），超过这个范围必须换方法。

计数 DP

计数 DP 的核心理解

计数 DP 求的是方案数，而不是最值。核心区别在于初始化：dp[0] = 1（"什么都不选"算一种方案），而不是 dp[0] = 0。转移通常是加法而不是 max/min。

识别信号：题目问"有多少种方法/方案/排列"。

LC62 - 不同路径

LC62上面也已经解决过了，没什么可以多说的。

LC96 - 不同的二叉搜索树

实际上，这一题就是求一个卡特兰数。先给个公式法：

import math
def numTrees(self, n: int) -> int:
    return math.comb(2*n,n)//(n+1)

不过，不知道结论的话，还是必须从头计数。我们的做法是枚举根节点的位置，dp[j] = 以 1 为根的方案数 + 以 2 为根的方案数 + ... + 以 j 为根的方案数。根选为i的时候，左边i-1个节点都比i小，右边j-i个节点都比i大，左右独立，方案数为 dp[i-1]*dp[j-i]。计数转移为 dp[j] += dp[i-1] * dp[j-i]，注意

def numTrees(self, n: int) -> int:
    dp = [0] * (n + 1)
    # 空树
    dp[0] = 1
    for j in range(1, n + 1):
        for i in range(1, j + 1):
            dp[j] += dp[i - 1] * dp[j - i]

    return dp[n]

LC91 - 解码方法

1对应A，直到26对应Z，进行了编码。现在要你从字符串数字进行有效解码，且存在可能无法解码的字符串。输出解码的总数。

这一题有点像IP划分，让人联想到dfs的划分问题，实际上，好像也确实可以这么做，只要让dfs的逻辑变成累加就行了。

from functools import cache
def numDecodings(self, s: str) -> int:
    n = len(s)
    def valid(sub: str) -> bool:
        if sub[0] == '0':
            return False
        return 1 <= int(sub) <= 26

    @cache
    def dfs(i: int) -> int:
        if i == n:
            return 1
        if s[i] == '0':
            return 0
        # 不用枚举所有end，最多两位
        # 切 1 位，不是前置零一定有效
        ans = dfs(i + 1)
        # 切 2 位
        if i + 1 < n and valid(s[i:i + 2]):
            ans += dfs(i + 2)
        return ans
    return dfs(0)

LC63 - 不同路径 II

已做过。

计数 DP 常见模板

# 计数 DP 通用框架
dp = [0] * (target + 1)
dp[0] = 1  # 什么都不选，一种方案
for item in items:
    for j in range(target, item - 1, -1):  # 0-1 背包倒序
        dp[j] += dp[j - item]                # 加法而非 max
return dp[target]

记忆化搜索与 DP 转换

自顶向下

递归从原问题出发，一路分解到最小子问题（base case），返回时沿途填充缓存。写法直觉、容易调试，适合状态定义还不清晰的探索阶段。

@cache
def dfs(state):
    if is_base_case(state):
        return base_value
    return max(dfs(s1), dfs(s2), ...)

自底向上

从最小的 base case 开始，按依赖顺序（通常是 for 循环）逐格填表，直到原问题的位置。更适合需要空间压缩的场景。

dp = [0] * (n + 1)
dp[0] = base_value
for i in range(1, n + 1):
    dp[i] = max(dp[i-1], dp[i-2] + val)
return dp[n]

递归函数如何改成 DP 数组

三步转换法：

dfs 的参数 → dp 的下标：dfs(i, j) 对应 dp[i][j]
dfs 的返回值 → dp 的值：dp[i][j] 存的就是 dfs 该返回的东西
递归方向 → 循环：递归是从大到小调用，循环就从小到大填表（依赖方向反过来）

dfs(i) = max(dfs(i-1), dfs(i-2) + val)      # 递归
dp[i] = max(dp[i-1], dp[i-2] + val)         # DP

什么时候保留记忆化搜索

状态空间稀疏：很多状态根本不会访问到（如博弈 DP 中的剪枝）
状态转移复杂：难以确定遍历顺序时，递归 + cache 更安全
树形 DP：树天然适合递归，不需要显式填表
面试/博客写题：记忆化搜索通常更短更清晰

什么时候必须转 DP：需要空间压缩、必须严格控制内存（n 很大）、需要显式遍历顺序优化。

动态规划题目的分类判断

拿到一道新题，按以下顺序判断：

看题目是否有重复子问题

暴力解是否存在对同一状态反复计算？如果每个子问题只会遇到一次（如树的每个节点），递归就够了，不需要 DP。

看题目是否求最值、方案数、可行性

最值→ 转移用 max/min，初始化边界值
方案数→ 转移用加法，初始化 dp[0]=1
可行性→ 转移用 or，初始化 dp[0]=True

看状态是否依赖前一个位置

dp[i] 只由 dp[i-1] 推出 → 一维 DP，可能空间压缩到 O(1)。

看状态是否依赖两个序列

两个字符串/数组的匹配问题 → dp[i][j] 双序列 DP（LCS、编辑距离）。

看是否是容量选择问题

给定容量目标，从候选集中选物品 → 背包 DP。判断是 0-1（每物最多一次）还是完全（每物无限次）来决定正序或倒序。

看是否是区间合并问题

问题在数组的一段区间上操作，结果由子区间合并 → 区间 DP（戳气球、三角剖分）。

看是否可以用状态压缩表示集合

n 很小（≤ 20），只需要知道"哪些元素被用了" → 状态压缩 DP（mask 位运算）。

动态规划常见模板

一维 DP 模板

dp = [0] * n; dp[0] = init
for i in range(1, n):
    dp[i] = max(dp[i-1], dp[i-2] + val[i])
return dp[-1]

二维 DP 模板

dp = [[0]*n for _ in range(m)]
dp[0][0] = init
for i in range(1, m): dp[i][0] = ...  # 第一列
for j in range(1, n): dp[0][j] = ...  # 第一行
for i in range(1, m):
    for j in range(1, n):
        dp[i][j] = min(dp[i-1][j], dp[i][j-1]) + cost[i][j]
return dp[-1][-1]

0-1 背包模板

dp = [0] * (C+1)
for w, v in items:
    for j in range(C, w-1, -1):      # 倒序
        dp[j] = max(dp[j], dp[j-w] + v)
return dp[C]

完全背包模板

dp = [0] * (C+1)
for coin in coins:
    for j in range(coin, C+1):       # 正序
        dp[j] = min(dp[j], dp[j-coin] + 1)
return dp[C]

子序列 DP 模板

dp = [[0]*(n+1) for _ in range(m+1)]
for i in range(1, m+1):
    for j in range(1, n+1):
        if s[i-1] == t[j-1]:
            dp[i][j] = dp[i-1][j-1] + 1
        else:
            dp[i][j] = max(dp[i-1][j], dp[i][j-1])
return dp[m][n]

区间 DP 模板

for gap in range(min_gap, n):
    for i in range(n - gap):
        j = i + gap
        for k in range(i+1, j):
            dp[i][j] = min(dp[i][j], dp[i][k] + dp[k][j] + cost)
return dp[0][n-1]

树形 DP 模板

def dfs(node):
    if not node:
        return base
    l, r = dfs(node.left), dfs(node.right)
    ans = max(ans, combine(l, r, node))
    return max(l, r) + 1

状态压缩 DP 模板

dp = [-1] * (1 << n); dp[0] = 0
for mask in range(1 << n):
    if dp[mask] == -1: continue
    for i in range(n):
        if mask & (1 << i): continue
        dp[mask | (1 << i)] = transition(dp[mask], nums[i])
return dp[(1 << n) - 1]

动态规划问题总结

DP 的本质就六个字：拆问题，存结果。不论是一维还是二维，递归还是填表，回溯还是 mask，翻来覆去就是在回答三个问题：

状态是什么？—— 用什么变量能唯一描述一个局面？（dp[i]、dp[i][j]、dp[mask]、树节点）
转移从哪里来？—— 当前状态能从哪些前驱状态一步到达？
答案在哪里？—— 最终要返回的是 dp 表的哪个位置？

DP 没有什么魔力，它就是暴力搜索的缓存优化版。遇到新题，先写出暴力（哪怕是脑子里），找到重复子问题，定义好 dp 含义，剩下的转移、初始化、遍历顺序都可以按模板来。刷够这几十道经典题，分类套路就刻进肌肉记忆了。

算法总结-双指针技巧

Sat, 21 Mar 2026 00:00:00 GMT

介绍

双指针技巧，是一种处理数组和链表相关问题经常用到的技巧。其中，最常用到的无非两种：左右指针和快慢指针。

相向双指针

当数组有序，需要从两端逼近的时候，就可以想到相向双指针。核心特征是我们每次根据条件淘汰一侧，并且不回头

LC167 - 两数之和II

我们假设两个指针的和已经大于target了，如果移动小的那头，那只会更大于，只有移动大的那头才能保证接下来可能出现两数之和。

import ast

def solution(nums:list,target:int)->int:
    left, right = 0,len(nums)-1
    while left<right:
        if nums[left]+nums[right] == target:
            return [left+1,right+1]
        elif nums[left]+nums[right] < target:
            left+=1
        else:
            right-=1
            

if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    target = int(input().strip())
    print(solution(nums,target))

LC11 - 盛最多水的容器

思维方式类似。移动长边一定会减少水量，只有移动短边才可能会增多水量，所以我们要不断移动短边。

import ast

def solution(height:list)->int:
    left, right = 0, len(height)- 1
    max_pool = 0
    while left<right:
        max_pool = max(max_pool,(right - left)*min(height[left],height[right]))
        if height[left]<height[right]:
            left += 1
        else:
            right -= 1 
    return max_pool

if __name__ == "__main__":
    height = ast.literal_eval(input().strip())
    print(solution(height))

LC125 - 验证回文串

给一个句子，删除空格转小写拼接后，判断是否回文。思路很简单，注意python处理清洗就行。

import ast

def solution(s:str)->bool:
    if not s:
        return True
    left, right = 0, len(s)-1
    while left<right:
        if s[left]!=s[right]:
            return False
        else:
            left+=1
            right-=1
        return True

if __name__ == "__main__":
    s = input().strip()
    s_list = []
    for c in s:
        if c.isalnum():
            s_list.append(c.lower())

    s_new = "".join(s_list)
    print(solution(s_new))

LC680 - 验证回文串II

本题也就是由于允许一次试错，立刻想到回溯一下

import ast

# 判断i,j之间的是否是回文串
def solution(i:int,j:int,s:str,flag:int)->bool:
    if i == j:
        return True
    while i<j:
        if s[i]!=s[j] and flag == 0:
            return solution(i+1,j,s,1)or solution(i,j-1,s,1)
        elif s[i]!=s[j] and flag == 1:
            return False
        else:
            i+=1
            j-=1
    return True  

if __name__ == "__main__":
    s = input().strip()
    print(solution(0,len(s)-1,s,0))

LC344 - 反转字符串

除了字符输入处理倒是没什么可注意的。

def solution(s: list[str]) -> list[str]:
    left, right = 0, len(s)-1
    while left<right:
        s[left],s[right] = s[right],s[left]
        left += 1
        right -= 1
    return s

if __name__ == "__main__":
    # 注意这里的输入
    s = [x.strip().strip('"').strip("'") for x in input().split(',')]
    print(solution(s))

LC881 - 救生艇

这题就稍微有难度一点了，要用到贪心的思想。我们先把people按体重排好队，能用最多船的理想方案肯定是轻重搭配，后面按照双指针做就行了。

import ast

def solution(people, limit):
    people.sort()
    left, right = 0, len(people) - 1
    count = 0

    while left <= right:
        if people[left] + people[right] <= limit:
            left += 1
        right -= 1
        count += 1

    return count


if __name__ == "__main__":
    people = ast.literal_eval(input().strip())
    limit = int(input().strip())
    print(solution(people,limit))

同向双指针

同向双指针，其实就是滑动窗口。我们什么时候去使用它。

LC3 - 无重复字符的最长子串

我们需要判断窗口的要素，是元素个数，这是一个与位置无关的属性，因此我们首先想到的就是滑动窗口。

def solution(s:str):
    window = {}
    left , right = 0, 0
    max_len = 0
    while right<len(s):
        c = s[right]
        right += 1
        window[c] = window.get(c,0)+1
        while window[c]>1:
            c2 = s[left]
            left += 1
            window[c2] -= 1
        max_len = max(max_len,right-left)
    return max_len

if __name__ == "__main__":
    s = input().strip()
    print(solution(s))

LC209 - 长度最小的子数组

依旧是满足一个条件的连续序列，条件与位置无关，按照标准滑动窗口思路。

import ast

def solution(target:int,nums:list):
    total = 0
    left,right = 0, 0
    min_len = float('inf')
    while right<len(nums):
        c = nums[right]
        right += 1 
        total += c
        while total>=target:
            # 先判断长度
            min_len = min(min_len,right-left)
            total -= nums[left]
            left += 1
    return min_len if min_len!=float('inf') else 0

if __name__ == "__main__":
    target = int(input().strip())
    nums = ast.literal_eval(input().strip())
    print(solution(target,nums))

LC76 - 最小覆盖子串

import ast

def solution(s:str,t:str)->str:
    window, need = {},{}
    valid = 0
    min_len = float('inf')
    ans = ""
    for c in t:
        need[c] = need.get(c,0) + 1
    left, right = 0, 0 
    while right< len(s):
        c = s[right]
        right += 1
        if c in need:
            window[c] = window.get(c,0)+1
            if window[c] == need[c]:
                valid += 1
        while valid == len(need):
            if right - left < min_len:
                ans  = s[left:right]
                min_len = right - left
            c1 = s[left]
            left += 1
            if c1 in need:
                if window[c1] == need[c1]:
                    valid -= 1
                window[c1] -= 1
    return ans

if __name__ == "__main__":
    s = input().strip()
    t = input().strip()
    print(solution(s,t))

LC438 - 找到字符串中所有字母异位词

这道题和前面的题目不一样，是固定窗口的滑动窗口题目。注意一下收缩valid的控制只有一种写法（先判断，再扣window）就行：

import ast

def solution(s:str,p:str)->list:
    window , need = {}, {}
    left, right =0, 0
    ans = []
    valid = 0
    for c in p:
        need[c] = need.get(c,0) + 1
    while right<len(s):
        c1 = s[right]
        right += 1
        if c1 in need:
            window[c1] = window.get(c1,0) + 1
            if window[c1] == need[c1]:
                valid += 1
        while right - left > len(p):
            c2 = s[left]
            left += 1
            if c2 in need:
                if window[c2] == need[c2]:
                    valid -= 1
                window[c2] -= 1
        if valid == len(need):
            ans.append(left)
    return ans

if __name__ == "__main__":
    s = input().strip()
    p = input().strip()
    print(solution(s,p))

LC567 - 字符串的排列

跟上题一样，是固定窗口滑动.

import ast

def solution(s1:str,s2:str)->list:
    window, need = {}, {}
    valid = 0
    for c in s1:
        need[c] = need.get(c,0) + 1
    left, right = 0, 0
    while right<len(s2):
        c1 = s2[right]
        right += 1
        if c1 in need:
            window[c1] = window.get(c1,0) + 1
            if window[c1] == need[c1]:
                valid += 1
        while right - left > len(s1):
            c2 = s2[left]
            left += 1
            if c2 in need:
                if window[c2] == need[c2]:
                    valid -= 1
                window[c2] -= 1
        # 如果包含，就可以返回了
        if valid == len(need):
            return True
    return False

if __name__ == "__main__":
    s1 = input().strip()
    s2 = input().strip()
    print(solution(s1,s2))

LC904 - 水果成篮

这一题，实际上是在求，满足窗口里面只有两种数字的最大连续窗口长度。但是本题有一个很关键的点，就是window[c] 回退到0的时候，key还是存在的，这样会扰乱 if not in window这样的语句，所以到0的话我们需要用del删除这个键（之前为什么不用呢，因为前面关心的主要是window和need的技术关系，和valid维持满足要求的字符种类数，而不关心len(window)）

import ast

def solution(fruits:list)->int:
    max_len = 0
    type = 0
    window = {}
    left, right = 0, 0
    while right<len(fruits):
        c1 = fruits[right]
        right += 1
        if c1 not in window:
            type += 1
        window[c1] = window.get(c1,0) + 1
        while type > 2:
            c2 = fruits[left]
            left += 1
            if c2 in window:
                window[c2] -= 1
                if window[c2] == 0:
                    type -= 1
                    # 删除很关键
                    del window[c2]
                
        # 种类正好两种
        max_len = max(max_len,right - left)
    return max_len

if __name__ == "__main__":
    fruits = ast.literal_eval(input().strip())
    print(solution(fruits))

另外，其实这题不用维持type了，len(window)本身当做指标，可以让代码更简洁容易：

def solution(fruits: list[int]) -> int:
    window = {}
    left = 0
    max_len = 0

    for right, fruit in enumerate(fruits):
        window[fruit] = window.get(fruit, 0) + 1

        while len(window) > 2:
            left_fruit = fruits[left]
            window[left_fruit] -= 1
            if window[left_fruit] == 0:
                del window[left_fruit]
            left += 1

        max_len = max(max_len, right - left + 1)

    return max_len

LC1004 - 最大连续1的个数III

这一题要是没有最多翻转k个0这事，就可以直接统计了。有了这个条件后，实际上可以转化成滑动窗口来做，用0的数目（也就是k）来当做窗口需要考虑的属性。

import ast

def solution(nums:list,k:int)->int:
    # 统计0、1的数目
    count_1 = 0
    count_0 = 0
    max_len = 0 
    left, right = 0, 0
    while right < len(nums):
        c1 = nums[right]
        right += 1
        if c1 == 1:
            count_1 += 1
        else:
            count_0 += 1
        while count_0 > k:
            c2 = nums[left]
            left += 1
            if c2 == 1:
                count_1 -= 1
            else:
                count_0 -= 1
        max_len = max(max_len,right - left)
    return max_len


if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    k = int(input().strip())
    print(solution(nums,k))

LC713 - 乘积小于K的子数组

需要注意的地方都写在题目里了。滑动窗口要避免一直缩窗的情况出现。

import ast

def solution(nums:list,k:int)->int:
    # 避免一直推窗
    if k<=1:
        return 0
    # 全都是正数，直接滑动
    curr = 1
    left, right = 0, 0
    count = 0
    while right<len(nums):
        c1 = nums[right]
        right += 1
        curr *= c1
        while curr >= k:
            c2 = nums[left]
            left += 1
            curr //= c2
        # 当右端点固定在 right - 1 时，当前窗口 [left, right) 的乘积 < k 就合格，换句话说就是所有以 right - 1 结尾、起点在 left ... right - 1 的子数组都合法，也就是有right - left个
        count += (right-left)
    return count

if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    k = int(input().strip())
    print(solution(nums,k))

快慢指针

快慢指针式链表、数组的经典题目，代表的三类用法，处理环形、做尺子丈量和找出中点。第一种要记住141、142的结论，第二种是倒数第k个节点的无额外空间解，第三个找中点最常用，就是奇偶容易错，建议脑补一下3、4两种节点。

LC141 - 环形链表

# 本题也是经典结论，fast走两步，slow走一步，最终如果相遇则有环
class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

# 这里升级了一下，直接返回头指针+节点列表
def build_linked_list(nums):
    dummy = ListNode()
    cur = dummy
    nodes = []
    for x in nums:
        cur.next = ListNode(x)
        cur = cur.next
        nodes.append(cur)
    return dummy.next, nodes

def solution(head:ListNode)->bool:
    slow,fast = head,head
    while fast and fast.next:
        fast = fast.next.next
        slow = slow.next
        if fast == slow:
            return True
    return False

if __name__ == "__main__":
    nums_line = input().strip()
    pos = int(input().strip())

    # 注意这里有个判空逻辑
    nums = list(map(int, nums_line.split(','))) if nums_line else []
    head, nodes = build_linked_list(nums)

    if pos != -1 and nodes:
        nodes[-1].next = nodes[pos]

    print(solution(head))

或者这样写：

def hasCycle(self, head: Optional[ListNode]) -> bool:
    if not head or not head.next:
        return False
    slow = head
    fast = head.next
    while fast != slow:
        if not fast or not fast.next:
            return False
        slow = slow.next
        fast = fast.next.next
    return True

这种写法有点别扭，一般推荐第一种写法。我们做一点推广，这种判环的最简单写法，归根结底，其实就是这样的模版：

slow = start
fast = start # 或者fast先走一格，一旦next就要判断会不会None.next
while 没有到达“无环结束条件”:
    slow = next(slow)
    fast = next(next(fast))
    if slow == fast:
        说明有环

LC142 - 环形链表II

class ListNode:
    def __init__(self,val = 0,next = None):
        self.val = val
        self.next = next

def solution(self,head:ListNode)->bool:
    fast, slow = head,head
    while fast and fast.next:
        slow = slow.next
        fast = fast.next.next
        if fast == slow:
            break
    # 无环返回
    if not fast or not fast.next:
        return None
    start = head
    while start != slow:
        start = start.next
        slow = slow.next
    return start

LC876 - 链表的中间结点

来到了快慢链表题，这类题目要注意奇偶的情况，本题要求偶数后半或者奇数中点。

def solution(head:ListNode)->bool:
    fast, slow = head,head
    while fast and fast.next:
        fast = fast.next.next
        slow = slow.next
    return slow

拓展：如果是偶数前半呢？答案是让fast的判断范围往前一步，这样就可以早停slow：

def solution(head:ListNode)->bool:
    fast, slow = head,head
    while fast.next and fast.next.next:
        fast = fast.next.next
        slow = slow.next
    return slow

拓展：部分题目中，我们可能需要删除头结点，这样就必须要让fast和slow从dummy开始，否则操作就会不统一，很别扭。

那么，带dummy的找中点前一位，偶数前半，操作其实和之前类似：

dummy = ListNode(0, head)
fast, slow = dummy, dummy
while fast.next and fast.next.next:
    fast = fast.next.next
    slow = slow.next

但是此时，slow会停在中点前面的一个合适位置。对于奇数，会返回slow中点前一个节点，偶数会返回前半，这是为了方便切半链表做进一步判断。

同样，如下写法，是找中点，偶数前半：

dummy = ListNode(0, head)
fast, slow = dummy, dummy
while fast and fast.next:
    fast = fast.next.next
    slow = slow.next

注意，带dummy的两种写法都是偶数前半，区别只是找到中点还是中点前一位。所以，这一题，如果我们写如下的代码也可以通过：

def middleNode(self, head: Optional[ListNode]) -> Optional[ListNode]:
        dummy = ListNode(0, head)
        fast, slow = dummy, dummy
        while fast.next and fast.next.next:
            fast = fast.next.next
            slow = slow.next
        return slow.next

最后还可以补充一句，其实我们可以直接通过fast最终的位置判断奇偶，比如无dummy，while fast and fast.next，如果fast最后停在None，那就是偶数，否则是奇数。其他的跳法脑补一下3、4个结点的情况。

LC19 - 删除链表的倒数第N个结点

这是拿fast和slow当尺子，测倒数第N个结点的方法，方法是让fast先走N步，然后同步前进。由于可能会删除头结点，因此需要dummy。

我们需要停在待删除节点的前一位，可以在脑海中想象一下。所以我们要用fast.next来判断：

def solution(head:ListNode,n:int)->bool:
    dummy = ListNode(0,head)
    p,q = dummy,dummy
    for _ in range(n):
        q = q.next
    while q.next:
        p = p.next
        q = q.next
    p.next = p.next.next
    return dummy.next

LC202 - 快乐数

这题乍一看和双指针没关系，直接用循环和set解决：

class ListNode:
    def __init__(self,val = 0,next = None):
        self.val = val
        self.next = next

def solution(n:int)->bool:
    # 不断计算，如果遇到出现过的数字，那么就是无限循环
    if n == 0:
        return False
    seen = set()
    seen.add(0)
    total = 0
    while n:
        mod = n%10
        total += mod*mod
        n = int(n/10)
    while total not in seen:
        seen.add(total)
        now = 0
        while total:
            mod = total%10
            now += mod*mod
            total = int(total/10)
        if now == 1:
            return True
        else:
            total = now
    return False

if __name__ == "__main__":
    n = int(input().strip())
    print(solution(n))

但是实际上，这题可以抽象成一个Floyd快慢指针题，本质是在“不断跳到下一个状态”的过程中判断有没有环。我们可以写法变成如下：

def get_next(n: int) -> int:
    total = 0
    while n > 0:
        digit = n % 10
        total += digit * digit
        n //= 10
    return total

def solution(n: int) -> bool:
    slow = n
    fast = get_next(n)

    while fast != 1 and slow != fast:
        slow = get_next(slow)
        fast = get_next(get_next(fast))

    return fast == 1

if __name__ == "__main__":
    n = int(input().strip())
    print(solution(n))

Floyd快慢指针法的空间复杂度为O(1)，非常巧妙。

不过我们可以注意到，在这种逻辑判环中，我们不能用fast的位置来判断有没有环，所以我们需要更新一下条件。

然后额外注意要用 fast != slow 时，要让他们起点不一样，不然直接都不循环了。

LC287 - 寻找重复数

同样这题利用下标就可以了，不断将1-n搬到对应的0到n-1位置上，如果已经有了就重复。也就是说这题本来的做法是原地哈希：

def solution(nums: list[int]) -> int:
    i = 0
    while i < len(nums):
        # 当前位置已经是正确数了才调整位置
        if nums[i] == i + 1:
            i += 1
            continue

        correct_idx = nums[i] - 1
        if nums[correct_idx] == nums[i]:
            return nums[i]

        nums[i], nums[correct_idx] = nums[correct_idx], nums[i]

经过前面的几题，你应该知道了这题可以抽象成Floyd环，因为数组长度是 n+1，值域是 [1, n]，说明一定有重复，重复就会导致“指向同一个位置”，于是形成环。得出代码如下：

def solution(nums: list[int]) -> int:
    slow = nums[0]
    fast = nums[0]

    while True:
        slow = nums[slow]
        fast = nums[nums[fast]]
        if slow == fast:
            break

    slow = nums[0]
    while slow != fast:
        slow = nums[slow]
        fast = nums[fast]

    return slow

这实际上就是把寻找环位置值的代码抽象了出来。它同时满足不修改数组和额外空间O(1)，是比原地哈希更好的方法。

读写双指针

读写双指针，是用一根遍历，一根更新的技巧。

LC26 - 删除有序数组中的重复项

def removeDuplicates(self, nums: List[int]) -> int:
    # 删除非严格递增的数组nums，删除重复元素，返回唯一元素个数
    # 两个指针解决问题
    if not nums:
        return 0
    slow = 1
    # 快指针
    for fast in range(1,len(nums)):
        if nums[fast]!=nums[fast-1]:
            # 遇到不一样的搬过来
            nums[slow]=nums[fast]
            slow+=1
    # 慢指针的位置就是所有独一无二的元素长度
    return slow

有一点要注意，这里让fast从1开始是为了不让fast-1越界，并且根据往后看了一格，也全部判断到了。fast还是从0开始比较多，比如写成这样（依旧要判断右边越界）：

def removeDuplicates(self, nums: List[int]) -> int:
        i,j = 0,0 
        while j<len(nums):
            if j+1<len(nums) and nums[j] == nums[j+1]:
                j+=1
                continue
            nums[i] = nums[j]
            i+=1
            j+=1
        return i

LC27 - 移除元素

跟上一题只是判断条件不同，依然是公式写法：

def removeElement(self, nums: list[int], val: int) -> int:
    p,q = 0,0
    while q<len(nums):
        if nums[q] == val:
            q+=1
            continue
        nums[p] = nums[q]
        p+=1
        q+=1
    return p

LC80 - 删除有序数组中的重复项II

由于是有序数组，本题其实只是比LC26多一位判断：

def removeDuplicates(self, nums: list[int]) -> int:
    i,j = 0,0 
    while j<len(nums):
        if j+2<len(nums) and nums[j] == nums[j+1] == nums[j+2]:
            j+=1
            continue
        nums[i] = nums[j]
        i+=1
        j+=1
    return i

LC283 - 移动零

也就是将所有非0元素保留，然后p继续移动置0即可。

def moveZeroes(self, nums: list[int]) -> None:
    i,j = 0, 0
    while j<len(nums):
        if nums[j]!= 0:
            nums[i] = nums[j]
            i+=1
        j+=1
    while i<len(nums):
        nums[i] = 0
        i+=1

这里要注意一个点，非零元素不用在条件里面j+=1，因为j一定要移动的，就直接放最后面统一加，否则会移动两次。要不然，就在条件里面写一个continue，和之前一样。

LC75 - 颜色分类

上面很多题，都是直接覆盖，因为不会丢信息，比如移动0只会覆盖0，后面补0就行；重复元素更不用说，有序重复时才覆盖，覆盖不会丢数字。但是这一题，不允许提前排序，如果还覆盖来写，就会丢信息，所以我们要改为交换元素而不是覆盖元素！

另外还有一个要注意的点，由于我们只是交换元素，所以不能让还没检查过的元素被跳过。尤其是遇到2时，从右侧换回来的元素还不知道是什么，可能还需要继续被判断一次（比如0原本在末尾，被换到了中间，还需要再换到开头）。

import ast

def sortColors(nums: list[int]) -> None:
    # 由于只有三种元素，所以我们遍历将0放前面，2放后面，中间的自然就是1啦
    i,j,k = 0,0,len(nums)-1
    # 注意这里的循环条件有变化！
    while j <= k:
        if nums[j]==0:
            nums[i],nums[j] = nums[j],nums[i]
            i+=1
            j+=1
        elif nums[j]==2:
            nums[k],nums[j] = nums[j],nums[k]
            # 不确定是否还要移动到开头，所以j先不动，等待下次循环再检查是不是0
            k-=1
        else:
            j+=1

if __name__ == "__main__":
    nums = ast.literal_eval(input().strip())
    sortColors(nums)
    print(nums)

本题是大名鼎鼎的荷兰国旗问题，用双指针划分出三个区域。有几处是需要注意的。可以好好看看。

归并型双指针

这种题目常见于链表，一边一个指针，不断将符合条件的加入新结构（也可能是原地）。我们往往需要新指针p来指引新位置。

LC88 - 合并两个有序数组

这一题的关键是原地合并，nums1后面已经天然给出空位，我们可以直接从大到小从后往前填。

def merge(self, nums1: list[int], m: int, nums2: list[int], n: int) -> None:
    p1 = m - 1
    p2 = n - 1
    p = m + n - 1

    while p2 >= 0:
        if p1 >= 0 and nums1[p1] > nums2[p2]:
            nums1[p] = nums1[p1]
            p1 -= 1
        else:
            nums1[p] = nums2[p2]
            p2 -= 1
        p -= 1

顺便拓展一下，如果nums1后面没有空位，我们就需要新结构，用非常简单的双指针逐位判断即可，注意走完之后要将结构加在后面：

def merge(nums1: list[int], nums2: list[int]) -> list[int]:
    i, j = 0, 0
    ans = []

    while i < len(nums1) and j < len(nums2):
        if nums1[i] <= nums2[j]:
            ans.append(nums1[i])
            i += 1
        else:
            ans.append(nums2[j])
            j += 1

    ans.extend(nums1[i:])
    ans.extend(nums2[j:])
    return ans

当然，也可以用递归的方法。其实，归并双指针问题大多数都可以写成递归，这种递归本质还是双指针，只不过把移动指针的过程交给递归调用。（这种传下标的dfs倒是在需要知道所有情况方便回溯的时候常用，这种情况不太常用）。

def merge(nums1: list[int], nums2: list[int]) -> list[int]:
    ans = []

    def dfs(i: int, j: int) -> None:
        if i == len(nums1):
            ans.extend(nums2[j:])
            return
        if j == len(nums2):
            ans.extend(nums1[i:])
            return

        if nums1[i] <= nums2[j]:
            ans.append(nums1[i])
            dfs(i + 1, j)
        else:
            ans.append(nums2[j])
            dfs(i, j + 1)

    dfs(0, 0)
    return ans

LC21 - 合并两个有序链表

非常经典了。

class ListNode:
    def __init__(self,val = 0, next = None):
        self.val = val
        self.next = next
    
def solution(list1:ListNode,list2:ListNode)->ListNode:
    dummy = ListNode()
    p = dummy
    while list1 and list2:
        if list1.val <= list2.val:
            p.next = ListNode(list1.val)
            p = p.next
            list1 = list1.next
        else:
            p.next = ListNode(list2.val)
            p = p.next
            list2 = list2.next            

    p.next = list1 if list1 else list2
    return dummy.next

LC392 - 判断子序列

这题也是一边一个指针，按照规则推进的题目，严格来说不是归并题，不过也放在这里了。

def solution(s:str,t:str)->bool:
    p, q = 0, 0
    # 如果p能走到最后，说明是成立的
    while p<len(s) and q<len(t):
        if s[p] == t[q]:
            p+=1
        q+=1
    return p == len(s)

LC986 - 区间列表的交集

这一题，把单元素换成了一个区间，我们注意相交规则和移动规则。一般，我们移动右边界较小的一侧，因为这样还可能构成更多相交。

def intervalIntersection(self, firstList: list[list[int]], secondList: list[list[int]]) -> list[list[int]]:
    p, q = 0, 0
    ans = []

    while p < len(firstList) and q < len(secondList):
        # 交集题常用
        start = max(firstList[p][0], secondList[q][0])
        end = min(firstList[p][1], secondList[q][1])

        if start <= end:
            ans.append([start, end])

        if firstList[p][1] <= secondList[q][1]:
            p += 1
        else:
            q += 1

    return ans

JZ52 - 两个链表的第一个公共节点

这题头一次想很晕，实际是公式打法，公共路程法：

class ListNode:
    def __init__(self, x):
        self.val = x
        self.next = None

def getIntersectionNode(self, headA: ListNode, headB: ListNode) -> ListNode:
    p,q = headA,headB
    while p != q:
        p = p.next if p else headB
        q = q.next if q else headA
    return p

固定点 + 双指针

固定点双指针题，一般是要在变化的范围内不断用双指针解。

LC15 - 三数之和

这一题注意为了防止重复，确定答案后移动指针要确认不是相同的值，由于排序了所以相同的值在同一段：

def threeSum(self, nums: list[int]) -> list[list[int]]:
    nums.sort()
    ans = []
    for i in range(len(nums)-2):
        if i > 0 and nums[i] == nums[i - 1]:
            continue
        left, right = i + 1, len(nums) - 1
        while left < right:
            s = nums[i] + nums[left] + nums[right]
            # 以0为分界决定移动哪个指针
            if s < 0:
                left += 1
            elif s > 0:
                right -= 1
            else:
                ans.append([nums[i], nums[left], nums[right]])
                left += 1
                right -= 1
                while left < right and nums[left] == nums[left - 1]:
                    left += 1
                while left < right and nums[right] == nums[right + 1]:
                    right -= 1
    return ans

LC16 - 最接近的三数之和

与三数之和的区别只在于找到答案的判定，由于本题只要返回最近和甚至不用去重。

def threeSumClosest(self, nums: list[int], target: int) -> int:
    min_diff = float('inf')
    ans = 0
    nums.sort()
    for i in range(len(nums)-2):
        j = i + 1
        k = len(nums) - 1
        while j<k:
            total = nums[i] + nums[j] + nums[k]
            diff = abs(target-total)
            if diff < min_diff:
                min_diff = diff
                ans = total
            if total < target:
                j+=1
            elif total > target:
                k-=1 
            else:
                return total
    return ans

LC18 - 四数之和

四数之和实际上就是固定两个位置之后再使用双指针即可，跳过的思路几乎和三数之和一样：

def fourSum(self, nums: list[int], target: int) -> list[list[int]]:
    ans = []
    nums.sort()
    for i in range(len(nums)):
        if i>0 and nums[i] == nums[i-1]:
            continue
        for j in range(i+1,len(nums)):
            if j>i+1 and nums[j] == nums[j-1]:
                continue
            p = j + 1
            q = len(nums)-1
            while p<q:
                if nums[i]+nums[j]+nums[p]+nums[q] == target:
                    ans.append([nums[i],nums[j],nums[p],nums[q]])
                    p+=1
                    q-=1
                    while p<q and nums[p] == nums[p-1]:
                        p+=1
                    while p<q and nums[q] == nums[q+1]:
                        q-=1
                elif nums[i]+nums[j]+nums[p]+nums[q] < target:
                    p+=1
                else:
                    q-=1
    return ans

拓展 - N数之和

做一点小扩展，已经解决了两数、三数、四数之和，那么N数之和是不是要固定N-1个数字呢。其实，我们可以通过每次固定一个点，让问题降级，从而跌落到我们熟悉的问题上。

# n数之和，start代表从哪个索引开始计算，这是为了方便递归的设计
def NSum(self, nums: list[int], n:int, start:int, target: int) -> list[list[int]]:
    sz = len(nums)
    res = []
    if n<2 or sz<n:
        return res
    # 2Sum问题
    if n == 2:
        lo, hi = start, sz - 1
        while lo<hi:
            total = nums[lo] + nums[hi]
            left, right = nums[lo], nums[hi]
            if total == target:
                res.append([left,right])
                lo += 1
                hi -= 1
                while lo < hi and nums[lo] == left:
                    lo += 1
                while lo < hi and nums[hi] == right:
                    hi -= 1
            elif total>target:
                hi -= 1
            else:
                lo += 1
        return res
    # 否则，开始递归
    else:
        for i in range(start,sz):
            if i>start and nums[i] == nums[i-1]:
                continue
            subs = self.NSum(nums,n-1,i+1,target-nums[i])
            # (n-1)Sum问题加上nums[i]就是nSum
            for sub in subs:
                sub.append(nums[i])
                res.append(sub)
        return res

LC611 - 有效三角形的个数

这一题可以转化为最小的两个数字的和是否大于第三个数，从而用三数之和变体做，固定最大的数，用双指针看前面的数：

def triangleNumber(self, nums: list[int]) -> int:
    nums.sort()
    count = 0
    for k in range(len(nums) - 1, 1, -1):
        i = 0
        j = k - 1
        while i < j:
            if nums[i] + nums[j] > nums[k]:
                # 此时中间的数字全部满足要求
                count += j - i
                j -= 1
            else:
                i += 1

    return count

链表双指针技巧

LC160 - 相交链表

与两个链表的第一个公共节点一样，不用看了。

LC234 - 回文链表

回文链表是链表指针操作的好题，综合了找中点和翻转：

class ListNode:
    def __init__(self,val = 0,next = None):
        self.val = val
        self.next = next

def solution(self,head:ListNode)->bool:
    if not head:
        return True
    # 先找中点，偶数要中前
    fast,slow = head, head
    while fast.next and fast.next.next:
        fast = fast.next.next
        slow = slow.next
    # 翻转
    curr = slow.next
    prev = None
    while curr:
        curr.next, prev, curr = prev,curr, curr.next
    
    # 比较
    while prev:
        if prev.val != head.val:
            return False
        prev = prev.next
        head = head.next
    return True

LC143 - 重排链表

这一题就是从中间断开，后面翻转，然后合并。本题需要注意的最大问题是，要求原地合并保留原本的head，这样穿针引线可能会绕一点，也要注意保留下一个元素防止丢失。不过，还是推荐直接用如下方法“Z型合并”：

class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

def solution(self, head: ListNode) -> None:
    if not head or not head.next:
        return

    # 1. 找中点
    slow, fast = head, head
    while fast.next and fast.next.next:
        slow = slow.next
        fast = fast.next.next

    # 2. 反转后半段
    second = slow.next
    slow.next = None

    prev = None
    curr = second
    while curr:
        nxt = curr.next
        curr.next = prev
        prev = curr
        curr = nxt

    # 3. 交替合并前半段和反转后的后半段
    first = head
    second = prev

    while second:
        tmp1 = first.next
        tmp2 = second.next

        first.next = second
        second.next = tmp1

        first = tmp1
        second = tmp2

LC24 - 两两交换链表中的节点

本题也是经典题，两种解法，保留下一个节点的循环交换，或者干脆递归。递归的解法比较简洁好想，所以下面直接递归。

class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

def swapPairs(self, head: ListNode) -> ListNode:
    if not head or not head.next:
        return head
    curr = head
    prev = None
    for _ in range(2):
        curr.next, prev, curr = prev,curr, curr.next
    head.next = swapPairs(curr)
    return prev

LC25 - K个一组翻转链表

如果采用递归的策略，跟上一题基本就没区别了，注意退出条件是小于K个剩余节点。

class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

def reverseKGroup(self, head: ListNode,k:int) -> ListNode:
    # 如果剩余少于k个直接退出
    p = head
    for _ in range(k):
        if not p:
            return head
        p = p.next

    curr = head
    prev = None
    for _ in range(k):
        curr.next, prev, curr = prev,curr, curr.next
    head.next = reverseKGroup(curr,k)
    return prev

双指针问题总结

好了，我们刷了这么多双指针题目，可以做一个总结了。相向、同向、快慢、归并、读写、固定点、链表技巧…… 简单梳理一下，该在哪些情况下想到这些解法呢？

双指针不是一种具体代码，而是一类“用两个位置压缩搜索空间”的思想。它的核心不是一定要有两个变量，而是：我们能不能用两个指针维护某种状态，并且每次移动其中一个指针时，都能确定不会错过答案。

所以判断一道题能不能用双指针，可以先问自己三个问题：

题目是不是在处理数组、字符串、链表、区间这类线性结构？
指针移动后，能不能排除一批不可能的情况？
是否存在某种单调性、顺序性、窗口性质、链表距离关系？

如果答案是肯定的，就可以优先往双指针方向想。

1. 相向双指针：两端向中间收缩

相向双指针最典型的形态是：

left, right = 0, len(nums) - 1
while left < right:
    if 条件满足:
        处理答案
    elif 需要变大:
        left += 1
    else:
        right -= 1

这一类题的关键词是：有序、两端、回文、最大面积、两数之和。

典型题目：

LC167 两数之和II
LC11 盛最多水的容器
LC125 验证回文串
LC680 验证回文串II
LC881 救生艇

相向双指针的本质是“每次移动一边，都能排除一批情况”。比如有序数组两数之和中，如果当前和太小，移动右指针只会更小或者不变，没意义，所以只能移动左指针让和变大。

这类题最重要的是想清楚：为什么移动这个指针不会错过答案？

2. 同向双指针：滑动窗口

同向双指针一般就是滑动窗口：

left, right = 0, 0
while right < len(nums):
    # 右边界进窗口
    window_add(nums[right])
    right += 1

    while 窗口不满足条件:
        # 左边界出窗口
        window_remove(nums[left])
        left += 1

    更新答案

这一类题的关键词是：连续子数组、连续子串、最长、最短、包含、至多、恰好。

典型题目：

LC3 无重复字符的最长子串
LC209 长度最小的子数组
LC76 最小覆盖子串
LC438 找到字符串中所有字母异位词
LC567 字符串的排列
LC904 水果成篮
LC1004 最大连续1的个数III
LC713 乘积小于K的子数组

滑动窗口的本质是“维护一个连续区间的状态”。右指针负责扩大窗口，左指针负责在条件不满足时收缩窗口。

这里最容易错的是收缩条件：

求最长：通常在窗口不合法时收缩，合法后更新最大值。
求最短：通常在窗口合法时不断收缩，并在收缩前更新最小值。
固定长度：窗口长度超过目标长度就收缩。

3. 快慢指针：速度差、距离差、判环、中点

快慢指针常见于链表，但不只适用于链表。只要一个状态能不断跳到下一个状态，就可能用快慢指针。

常见模板一，判环：

slow, fast = head, head
while fast and fast.next:
    slow = slow.next
    fast = fast.next.next
    if slow == fast:
        return True
return False

常见模板二，找环入口：

slow, fast = head, head
while fast and fast.next:
    slow = slow.next
    fast = fast.next.next
    if slow == fast:
        break

if not fast or not fast.next:
    return None

p = head
while p != slow:
    p = p.next
    slow = slow.next
return p

常见模板三，找中点：

slow, fast = head, head
while fast and fast.next:
    slow = slow.next
    fast = fast.next.next
return slow

典型题目：

LC141 环形链表
LC142 环形链表II
LC876 链表的中间结点
LC19 删除链表的倒数第N个结点
LC202 快乐数
LC287 寻找重复数

快慢指针的本质是“制造速度差或距离差”。环形链表中，快指针每次多走一步，所以如果有环一定会追上慢指针；删除倒数第N个节点中，先让快指针领先N步，本质是在维护固定距离。

注意，快乐数和寻找重复数虽然看起来不像链表，但都可以抽象成：

状态 x -> 下一个状态 next(x)

只要不断跳转会进入环，就能用 Floyd 快慢指针。

4. 读写双指针：一个读，一个写

读写双指针的模板一般是：

write = 0
for read in range(len(nums)):
    if nums[read] 应该保留:
        nums[write] = nums[read]
        write += 1
return write

这一类题的关键词是：原地删除、原地保留、移动元素、压缩数组。

典型题目：

LC26 删除有序数组中的重复项
LC27 移除元素
LC80 删除有序数组中的重复项II
LC283 移动零
LC75 颜色分类

读写双指针的本质是“读指针扫描旧数组，写指针维护新数组的下一个位置”。它通常适用于可以覆盖旧值的题目。

但是要注意，覆盖不是万能的。移动零可以覆盖，因为所有非零元素先写到前面，后面统一补零，不会丢失信息。颜色分类不能简单覆盖，因为 0、1、2 都是有效信息，直接写前后会把还没处理的元素覆盖掉，所以要用交换，也就是荷兰国旗三路划分。

读写双指针最常见的坑是：

read 每轮都要移动，不要在 if 里面加一次、外面又加一次。
覆盖前要判断这个题能不能丢弃被覆盖的旧值。
有序数组去重可以利用相邻关系，无序数组去重一般不能直接这样做。

5. 归并型双指针：两个序列一起走

归并型双指针通常是一边一个指针：

i, j = 0, 0
ans = []
while i < len(a) and j < len(b):
    if a[i] 更应该被处理:
        ans.append(a[i])
        i += 1
    else:
        ans.append(b[j])
        j += 1

ans.extend(a[i:])
ans.extend(b[j:])

这一类题的关键词是：两个有序数组、两个链表、两个区间列表、两个字符串匹配。

典型题目：

LC88 合并两个有序数组
LC21 合并两个有序链表
LC392 判断子序列
LC986 区间列表的交集
JZ52 两个链表的第一个公共节点

归并型双指针的本质是“两边各维护一个当前位置，每次根据规则推进一边或两边”。合并有序数组、合并链表是最标准的归并；判断子序列更准确地说是匹配型双指针，但它也是两个序列一起推进。

这里要特别记住 LC88：

如果目标数组后面有空位，优先从后往前填。
如果没有空位，通常新建数组从前往后合并。

从后往前的原因是：从前往后会覆盖 nums1 里还没处理的有效元素，而从后往前正好利用尾部空位。

6. 固定点 + 双指针：降维处理

固定点 + 双指针，一般用于 N数之和 或类似计数问题：

nums.sort()
for i in range(len(nums)):
    if i > 0 and nums[i] == nums[i - 1]:
        continue
    left, right = i + 1, len(nums) - 1
    while left < right:
        total = nums[i] + nums[left] + nums[right]
        if total < target:
            left += 1
        elif total > target:
            right -= 1
        else:
            记录答案
            left += 1
            right -= 1

这一类题的关键词是：三数之和、四数之和、N数之和、固定一个数、排序后查找。

典型题目：

LC15 三数之和
LC16 最接近的三数之和
LC18 四数之和
LC611 有效三角形的个数

固定点 + 双指针的本质是“固定一部分变量，把高维问题降成两数问题”。三数之和就是固定一个数，然后在右侧区间里做两数之和；四数之和就是固定两个数，再在剩余区间里做两数之和。

这一类题最容易错的是去重：

固定点要去重。
找到答案后，左右指针也要跳过重复值。
最接近的三数之和不需要去重，因为只返回一个和，不返回所有组合。

有效三角形个数虽然看起来不是求和等于某个值，但它也是固定最大边，然后在左侧用双指针批量计数。它的关键是单调性：如果 nums[i] + nums[j] > nums[k]，那么从 i 到 j - 1 的左边界都能和 j, k 组成三角形，所以可以一次加 j - i。

7. 链表双指针：先断、再反、再接

链表题里的双指针不只是移动速度，还经常和“断链、反转、合并”组合出现。

典型题目：

LC160 相交链表
LC234 回文链表
LC143 重排链表
LC24 两两交换链表中的节点
LC25 K个一组翻转链表

链表题有几个固定意识：

可能操作头节点时，用 dummy。
改 next 之前，先保存后续节点。
切链表时，记得断开，比如 slow.next = None。
反转链表的核心永远是 curr.next, prev, curr = prev, curr, curr.next，但面试里为了可读性，也可以拆成 nxt 三步写。
合并两个旧链表时，不要新建值节点，通常是移动旧节点。

比如重排链表，整体流程就是：

找中点 -> 断开 -> 反转后半段 -> 交替合并

链表题的难点往往不是算法本身，而是指针改动顺序。只要涉及 next 重连，就先把后面要用的节点存起来。

8. 题型判断表

最后给一个简单判断表，方便刷题时快速定位：

题目特征	优先想到
有序数组，两端比较	相向双指针
回文、反转字符串	相向双指针
连续子数组/子串，最长/最短/包含	滑动窗口
原地删除、原地保留、移动元素	读写双指针
链表判环、找中点、倒数第N个	快慢指针
状态不断跳转并可能成环	Floyd快慢指针
合并两个有序结构	归并型双指针
两个字符串按顺序匹配	匹配型双指针
三数、四数、N数之和	固定点 + 双指针
链表重排、回文链表	快慢指针 + 反转 + 合并

9. 最后记忆

双指针题的关键不是背代码，而是抓住“指针含义”和“不漏答案的移动理由”。

每次写双指针，可以先在草稿里写清楚：

left / right / slow / fast / read / write 分别代表什么？
哪个区间已经处理完？
哪个区间还未知？
什么时候移动左指针？
什么时候移动右指针？
移动后会不会漏掉答案？

如果这几个问题都能回答出来，代码就基本不会乱。

我的个人记忆方式是：

两端排除：相向
连续区间：滑窗
一读一写：读写
速度距离：快慢
两个序列：归并
固定降维：N数之和
链表重连：先存 next，再改 next

算法总结-搜索与遍历

Sat, 21 Mar 2026 00:00:00 GMT

搜索与遍历的核心理解

什么是遍历

遍历强调的是“把结构里的节点都走一遍”。树的前中后序、层序遍历，图里的连通块遍历，本质都是按照某种顺序访问节点，并在访问过程中收集信息。

什么是搜索

搜索强调的是“在状态空间中找答案”。它不一定要访问所有节点，而是根据题目的目标、约束和剪枝条件，尝试从当前状态转移到下一个状态。比如找路径、找最短步数、枚举所有方案、判断是否存在某种状态。

遍历和搜索的区别

遍历更像“按结构走完”，搜索更像“带目标地尝试”。很多题二者会重叠：DFS/BFS 既可以是遍历方式，也可以是搜索策略。做题时重点不是纠结名字，而是先判断：状态是什么、选择是什么、什么时候停止、是否需要撤销选择。

DFS 和 BFS 的区别

DFS 是一条路走到底，天然适合递归、回溯、连通性、枚举方案、判断环。BFS 是一层一层扩散，天然适合无权图最短路、最少步数、多源扩散。

什么时候想到 DFS

看到“所有路径”“所有方案”“能不能到达”“连通块数量”“从当前状态继续往下试”“需要回溯撤销选择”，优先考虑 DFS。

什么时候想到 BFS

看到“最短路径”“最少步数”“一圈一圈扩散”“同时从多个源头开始”“无权图距离”，优先考虑 BFS。

搜索题里的状态、选择、路径、剪枝

搜索题可以拆成四个词：

状态：当前递归或队列里保存的信息，比如坐标、节点、当前字符串、剩余目标。
选择：从当前状态能走向哪些下一状态。
路径：从起点走到当前状态经过的内容，回溯题里通常用 path 维护。
剪枝：发现当前状态不可能得到答案时提前返回，比如越界、重复访问、超过目标值、前缀不存在。

visited 的作用

visited 的核心作用是防止重复访问，但要注意它有两种语义：

全局 visited：一个节点访问过就不再访问，常见于图遍历、岛屿淹没。
路径级 visited：只限制当前路径不能重复使用，回溯结束后要撤销，常见于单词搜索、排列。

能不能原地修改数组，本质上取决于修改后会不会破坏题目的判断语义。比如岛屿面积可以把陆地改成水，但岛屿周长不能把访问过的陆地改成水，否则会把相邻陆地误算成水边。

Python 中常用的数据结构

栈/递归：DFS。
deque：BFS 队列。
set：去重、visited、快速判断。
dict：邻接表、映射、Trie 子节点。
list[list[int]]：网格、邻接矩阵、动态维护棋盘。

树的遍历：按结构走完整棵树

二叉树遍历的核心理解

前序遍历

LC144 - 二叉树的前序遍历

三种遍历感觉写过一百遍了，肌肉记忆吧

def solution(root:TreeNode):
    ans = []
    def dfs(node):
        if not node:
            return
        ans.append(node.val)
        dfs(node.left)
        dfs(node.right)
    dfs(root)
    return ans

中序遍历

LC94 - 二叉树的中序遍历

def solution(root:TreeNode):
    ans = []
    def dfs(node):
        if not node:
            return
        dfs(node.left)
        ans.append(node.val)
        dfs(node.right)
    dfs(root)
    return ans

后序遍历

LC145 - 二叉树的后序遍历

def solution(root:TreeNode):
    ans = []
    def dfs(node):
        if not node:
            return
        dfs(node.left)
        dfs(node.right)
        ans.append(node.val)
    dfs(root)
    return ans

层序遍历

LC102 - 二叉树的层序遍历

依旧肌肉记忆

def solution(root:TreeNode):
    if not root:
        return []
    q = deque([root])
    ans = []
    while q:
        sz = len(q)
        level = []
        for _ in range(sz):
            node = q.popleft()
            level.append(node.val)
            if node.left:
                q.append(node.left)
            if node.right:
                q.append(node.right)
        ans.append(level)
    return ans

LC107 - 二叉树的层序遍历 II

直接返回的时候reverse一下。。

LC103 - 二叉树的锯齿形层序遍历

用当len(ans)%2 == 0时候为奇数层，偶数层appendleft。其他不用说了。

LC199 - 二叉树的右视图

每次取队列的-1位置加入答案。就改一行ans.append(level[-1])。

N 叉树遍历

LC589 - N 叉树的前序遍历

稍微推广一下即可。

def solution(root:TreeNode):
    ans = []
    def dfs(node):
        if not node:
            return 
        ans.append(node.val)
        for child in node.children:
            dfs(child)
    dfs(root)
    return ans

LC590 - N 叉树的后序遍历

def solution(root:TreeNode):
    ans = []
    def dfs(node):
        if not node:
            return 
        for child in node.children:
            dfs(child)
        ans.append(node.val)
    dfs(root)
    return ans

LC429 - N 叉树的层序遍历

几乎跟二叉树没啥变化

def solution(root:TreeNode):
    if not root:
        return []
    q = deque([root])
    ans = []
    while q:
        sz = len(q)
        level = []
        for _ in range(sz):
            node = q.popleft()
            level.append(node.val)
            if node.children:
                for child in node.children:
                    q.append(child)
        ans.append(level)
    return ans

树遍历常见模板

树的 DFS 模板核心是：

def dfs(node):
    if not node:
        return
    # 前序位置
    dfs(node.left)
    # 中序位置
    dfs(node.right)
    # 后序位置

树的 BFS 模板核心是：

from collections import deque

q = deque([root])
while q:
    for _ in range(len(q)):
        node = q.popleft()
        if node.left:
            q.append(node.left)
        if node.right:
            q.append(node.right)

DFS 搜索：一条路走到底

DFS 的核心思想

DFS 的核心是“沿着一个方向不断深入，走不动再回退”。递归写法里，每一层函数都代表一个状态，函数内部枚举下一步选择。

递归 DFS

递归 DFS 最重要的是三件事：

递归入口表示什么状态。
递归出口什么时候停止。
当前状态如何转移到下一状态。

迭代 DFS

迭代 DFS 用栈模拟递归。普通遍历可以写，但回溯题里递归通常更自然，因为递归栈天然保存了路径。

DFS 中的 visited

图和网格 DFS 通常需要 visited 或原地标记，否则可能在环里来回走。树结构天然没有回边，一般不需要 visited。

DFS 中的前序位置和后序位置

前序位置适合“进入节点时处理”，比如记录路径、标记访问。后序位置适合“处理完子问题后汇总”，比如树形 DP、课程表 DFS 拓扑排序、回溯撤销选择。

图的连通性搜索

LC841 - 钥匙和房间

我们将每个房间看做一个节点，房间里面的钥匙指向别的房间，相当于一条边。所以这题，其实就是从0号房间开始搜索，看最终能访问到多少个节点。

def canVisitAllRooms(self, rooms: list[list[int]]) -> bool:
    # 如果从一个房间出发，能搜到底，全部加入visited，就返回True
    # 由于房间选择可能不同，使用dfs
    n = len(rooms)
    visited = set()
    def dfs(i):
        # 如果已经访问过了，出口
        if i in visited:
            return 
        # 否则，标记，并且遍历下一个情况
        visited.add(i)
        for room in rooms[i]:
            dfs(room)
    dfs(0)
    return len(rooms) == len(visited)

当然，这一题也可以bfs来做。因为如果要访问完毕所有房间，那么最终路径长度一定是房间长度。所以我们可以bfs到底看看能不能走那么远即可：

from collections import deque

def canVisitAllRooms(self, rooms: list[list[int]]) -> bool:
    n = len(rooms)
    visited = set()
    # 从0开始bfs
    visited.add(0)
    q = deque([0])
    while q:
        curr = q.popleft()
        for key in rooms[curr]:
            # BFS要防止回搜，dfs可以在递归处来防，bfs必须在这里防
            if key not in visited:
                visited.add(key)
                q.append(key)
    return len(visited) == n

LC547 - 省份数量

其实就是给一个邻接矩阵，找连通块数量。最常用方法是统计 DFS 启动次数。

def findCircleNum(self, isConnected: list[list[int]]) -> int:
    n = len(isConnected)
    visited = set()

    def dfs(city: int) -> None:
        visited.add(city)
        for nxt in range(n):
            if isConnected[city][nxt] == 1 and nxt not in visited:
                dfs(nxt)

    count = 0
    for city in range(n):
        if city not in visited:
            dfs(city)
            count += 1

    return count

LC1971 - 寻找图中是否存在路径

听名字就知道要dfs了，它问有一个具有 n 个顶点的双向图，其中每个顶点标记从 0 到 n - 1（包含 0 和 n - 1）。图中的边用一个二维整数数组 edges 表示，其中 edges[i] = [ui, vi] 表示顶点 ui 和顶点 vi 之间的双向边。每个顶点对由最多一条边连接，并且没有顶点存在与自身相连的边。请你确定是否存在从顶点 source 开始，到顶点 destination 结束的有效路径。

我们直接从source走一次dfs即可，如果遇到目标节点就返回True，否则返回False。

这一题考一下邻接表的写法。

def validPath(self, n: int, edges: list[list[int]], source: int, destination: int) -> bool:
    # 建立邻接表
    graph = [[] for _ in range(n)]
    for edge in edges:
        graph[edge[0]].append(edge[1])
        graph[edge[1]].append(edge[0])

    # 写dfs函数
    visited = set()
    def dfs(node):
        if node in visited:
            return 
        visited.add(node)
        for nxt in graph[node]:
            dfs(nxt)
    dfs(source)
    return destination in visited

这一题只要找到就可以返回了，所以可以更利落一点，让dfs直接担任寻找答案的任务：

def validPath(self, n: int, edges: list[list[int]], source: int, destination: int) -> bool:
    # 建立邻接表
    graph = [[] for _ in range(n)]
    for edge in edges:
        graph[edge[0]].append(edge[1])
        graph[edge[1]].append(edge[0])

    # 写dfs函数
    visited = set()
    def dfs(node)->bool:
        if node == destination:
            return True
        if node in visited:
            return False
        visited.add(node)
        for nxt in graph[node]:
            # 只要有一个dfs通了即可
            if dfs(nxt):
                return True
        # 兜底
        return False
    return dfs(source)

所有路径搜索

LC797 - 所有可能的路径

这一题是一道标准的DAG路径所有路径搜索，我们维持一个path，如果到达了终点就将path加入答案。记得path要回溯即可：

def allPathsSourceTarget(self, graph: list[list[int]]) -> list[list[int]]:
    # 本题已给邻接表
    path = []
    path.append(0)
    ans = []
    n = len(graph)
    def dfs(node):
        if node ==  n-1:
            ans.append(path[:])
        for nxt in graph[node]:
            path.append(nxt)
            dfs(nxt)
            path.pop()
    dfs(0)
    return ans

这一版可以写的更优雅一些，每次dfs开始就path加入node，然后再进入递归退出判断。

    ans = []
    path = []
    target = len(graph) - 1
    def dfs(node):
        path.append(node)
        if node == target:
            ans.append(path[:])
        else:
            for nxt in graph[node]:
                dfs(nxt)
        path.pop()
    dfs(0)
    return ans

LC113 - 路径总和 II

本题只要求根节点到叶子结点的总和，直接在dfs中维持一个total，判断到叶子的时候是否等于target就行。（注意到空节点不一定是到了叶子节点后，所以要特判叶子节点）

def pathSum(self, root: TreeNode, targetSum: int) -> list[list[int]]:
    if not root:
        return []
    ans = []
    path = []
    def dfs(node,total):
        if not node:
            return
        
        path.append(node.val)
        total += node.val

        if not node.left and not node.right and total == targetSum:
            ans.append(path[:])
            # 这里不可以return！因为这种写法这里return就会弹不出当前元素
            # return
        else:
            dfs(node.left,total)
            dfs(node.right,total)
        path.pop()
    dfs(root,0)
    return ans

如果在LC上提交这个解法，可以发现非常慢，其实对于这类还有一个小优化，那就是不要传累加和了，直接传剩余和，这样就是100%了：

def pathSum(self, root: TreeNode, targetSum: int) -> list[list[int]]:
    ans = []
    path = []

    def dfs(node, remain):
        if not node:
            return

        path.append(node.val)
        remain -= node.val

        if not node.left and not node.right and remain == 0:
            ans.append(path[:])
        else:
            dfs(node.left, remain)
            dfs(node.right, remain)

        path.pop()

    dfs(root, targetSum)
    return ans

LC257 - 二叉树的所有路径

简单题，直接dfs到叶子节点就行。

class TreeNode:
    def __init__(self, val = 0, left = None, right = None):
        self.val = val 
        self.left = left
        self.right = right

def binaryTreePaths(self, root: TreeNode) -> list[str]:
    path = []
    ans = []
    def dfs(node):
        if not node:
            return
        path.append(str(node.val))
        if not node.left and not node.right:
            ans.append("->".join(path))
        else:
            dfs(node.left)
            dfs(node.right)
        path.pop()
    dfs(root)
    return ans

DFS 常见模板

图 DFS：

def dfs(node):
    if node in visited:
        return
    visited.add(node)
    for nxt in graph[node]:
        dfs(nxt)

回溯 DFS：

def dfs(state):
    if 满足答案条件:
        ans.append(path[:])
        return

    for choice in choices:
        if 不合法:
            continue
        path.append(choice)
        dfs(next_state)
        path.pop()

BFS 搜索：一层一层扩散

BFS 的核心思想

BFS 的核心是“从起点一层一层向外扩散”。队列中的节点按照距离起点由近到远的顺序被处理，所以在无权图中，第一次到达某个状态时就是最短距离。

BFS 为什么能求最短路

因为 BFS 每一轮只走一步，先处理距离为 k 的所有状态，再处理距离为 k + 1 的状态。如果边权都相同，第一次遇到终点时，不可能还有更短路径没被处理。

BFS 中的队列和层数

常见层数写法是：

step = 0
while q:
    for _ in range(len(q)):
        cur = q.popleft()
        ...
    step += 1

也可以把距离和节点一起入队，比如 q.append((node, dist))。

BFS 中的 visited

BFS 的 visited 最好在入队时就标记，而不是出队时再标记。这样可以避免同一个状态被多个父节点重复加入队列。

无权图最短路

LC752 - 打开转盘锁

简单来说，一次操作可以有8种不同的状态转移，询问能不能到达最终状态。但是，这题需要返回最小旋转次数，所以一定是需要bfs一层一层往外数。

from collections import deque

def openLock(self, deadends: list[str], target: str) -> int:
    def update(state: str) -> list[str]:
        res = []
        chars = list(state)
        for i in range(4):
            old = chars[i]

            chars[i] = str((int(old) + 1) % 10)
            res.append("".join(chars))

            chars[i] = str((int(old) + 9) % 10)
            res.append("".join(chars))

            chars[i] = old
        return res

    visited = set(deadends)
    if "0000" in visited:
        return -1
    if target == "0000":
        return 0

    q = deque(["0000"])
    visited.add("0000")
    step = 0

    while q:
        for _ in range(len(q)):
            cur = q.popleft()
            if cur == target:
                return step

            for nxt in update(cur):
                if nxt not in visited:
                    visited.add(nxt)
                    q.append(nxt)

        step += 1

    return -1

注意一下层数统计和去重等操作。

LC773 - 滑动谜题

同样是问多少次，使用广搜，不过注意这里的状态转移可以转化成一维来做。注意去重要tuple。

from collections import deque


def slidingPuzzle(self, board: list[list[int]]) -> int:
    flat = [x for row in board for x in row]
    target = [1, 2, 3, 4, 5, 0]

    def update(state: list[int]) -> list[list[int]]:
        zero_idx = state.index(0)

        match zero_idx:
            case 0:
                nxts = [1, 3]
            case 1:
                nxts = [0, 2, 4]
            case 2:
                nxts = [1, 5]
            case 3:
                nxts = [0, 4]
            case 4:
                nxts = [1, 3, 5]
            case 5:
                nxts = [2, 4]

        res = []
        for nxt in nxts:
            new_state = state[:]
            new_state[zero_idx], new_state[nxt] = new_state[nxt], new_state[zero_idx]
            res.append(new_state)
        return res

    q = deque([flat])
    visited = {tuple(flat)}
    step = 0

    while q:
        for _ in range(len(q)):
            cur = q.popleft()
            if cur == target:
                return step

            for nxt in update(cur):
                nxt_tuple = tuple(nxt)
                if nxt_tuple not in visited:
                    visited.add(nxt_tuple)
                    q.append(nxt)

        step += 1

    return -1

LC1091 - 二进制矩阵中的最短路径

需要找畅通路径的长度，所以用 BFS。其实就是一道起点到终点的最短路题目，先定义好 8 个方向即可。注意 visited 更新、判断位置等，多练。

from collections import deque

def shortestPathBinaryMatrix(self, grid: list[list[int]]) -> int:
    n = len(grid)
    if not grid or grid[0][0] == 1 or grid[n-1][n-1] == 1:
        return -1
    steps = [(1,0),(1,1),(1,-1),(-1,0),(-1,1),(-1,-1),(0,-1),(0,1)]
    q = deque([(0,0)])
    visited = {(0,0)}
    # 途径的单元格总数，所以不包括起点
    count = 1
    while q:
        sz = len(q)
        for _ in range(sz):
            x,y = q.popleft()
            if (x,y) == (n-1,n-1):
                return count
            for dx,dy in steps:
                nx = x + dx
                ny = y + dy
                if 0<=nx<n and 0<=ny<n and grid[nx][ny] == 0 and (nx,ny) not in visited:
                    visited.add((nx,ny))
                    q.append((nx,ny))
        count += 1
    return -1

LC1926 - 迷宫中离入口最近的出口

最近的出口，还是最短路径，直接一个bfs。

from collections import deque

def nearestExit(self, maze: list[list[str]], entrance: list[int]) -> int:
    if not maze:
        return -1
    directions = [(1,0),(-1,0),(0,-1),(0,1)]
    m = len(maze)
    n = len(maze[0])
    visited = set()
    for x in range(m):
        for y in range(n):
            if maze[x][y] == "+":
                visited.add((x,y))
    # 开始bfs，只要移动到变边界就成功
    step = 0
    q = deque([(entrance[0],entrance[1])])
    visited.add((entrance[0],entrance[1]))
    while q:
        sz = len(q)
        for _ in range(sz):
            x, y = q.popleft()
            # 注意题目明确说起点不能作为出口
            if step > 0 and (x == 0 or x == m-1 or y == 0 or y == n-1):
                return step
            for dx, dy in directions:
                nx = x + dx
                ny = y + dy
                if 0<=nx<m and 0<=ny<n and (nx,ny) not in visited:
                    visited.add((nx,ny))
                    q.append((nx,ny))
        step += 1
    return -1

当然，既然是要遍历，其实可以不用先把墙放进visited，而是在入队判断时候加，像这样：

from collections import deque

def nearestExit(self, maze: list[list[str]], entrance: list[int]) -> int:
    if not maze:
        return -1

    m, n = len(maze), len(maze[0])
    directions = [(1, 0), (-1, 0), (0, 1), (0, -1)]

    q = deque([(entrance[0], entrance[1])])
    visited = {(entrance[0], entrance[1])}
    step = 0

    while q:
        for _ in range(len(q)):
            x, y = q.popleft()

            if step > 0 and (x == 0 or x == m - 1 or y == 0 or y == n - 1):
                return step

            for dx, dy in directions:
                nx, ny = x + dx, y + dy
                if 0 <= nx < m and 0 <= ny < n and maze[nx][ny] == '.' and (nx, ny) not in visited:
                    visited.add((nx, ny))
                    q.append((nx, ny))

        step += 1

    return -1

速度上会快点。

多源 BFS

LC994 - 腐烂的橘子

这一题注意维持一个fresh，这样多源bfs之后才知道是否感染完毕。我们准备一个感染队列，先遍历一遍将感染坐标入队，然后开始一层一层感染。

from collections import deque

def orangesRotting(self, grid: list[list[int]]) -> int:
    m = len(grid)
    n = len(grid[0])
    q = deque()
    fresh = 0
    for x in range(m):
        for y in range(n):
            if grid[x][y] == 2:
                q.append((x,y))
            elif grid[x][y] == 1:
                fresh += 1
    # 开始 BFS，检查四个方向有没有新鲜橘子
    directions = [(1,0),(-1,0),(0,1),(0,-1)]
    step = 0
    while q and fresh>0:
        for _ in range(len(q)):
            x,y = q.popleft()
            for dx, dy in directions:
                nx = x + dx
                ny = y + dy
                if 0<=nx<m and 0<=ny<n and grid[nx][ny] == 1:
                    grid[nx][ny] = 2
                    q.append((nx,ny))
                    fresh -= 1
        step += 1
    return step if fresh == 0 else -1

我们可以观察发现，这一题和上一题的返回时机不一样。这是因为，上一题找路径，到达某个路径之后，答案就已经出来了，但是感染橘子就算循环中干扰上了，也还在这一分钟内，要等待step+=1。

LC542 - 01 矩阵

我们定义一个bfs函数，返回step，然后对每一个点调用，这样就能得到新矩阵了。

from collections import deque

def updateMatrix(self, mat: list[list[int]]) -> list[list[int]]:
    m = len(mat)
    n = len(mat[0])
    # 负责输出周围最近的0的距离
    def bfs(x,y)->int:
        directions = [(-1,0),(1,0),(0,1),(0,-1)]
        q = deque([(x,y)])
        step = 0
        visited = set()
        visited.add((x,y))
        while q:
            for _ in range(len(q)):
                x,y = q.popleft()
                if mat[x][y] == 0:
                    return step
                for dx,dy in directions:
                    nx = x + dx
                    ny = y + dy
                    if 0<=nx<m and 0<=ny<n and (nx,ny) not in visited:
                        visited.add((nx,ny))
                        q.append((nx,ny))
            step += 1
        return -1
    
    result = [row[:] for row in mat]

    for i in range(m):
        for j in range(n):
            result[i][j] = bfs(i,j)
    return result

从思路上来说没问题，但是这一题这样写铁超时的，因为我们要每次对一个点做一个bfs。多源bfs的要点是，我们将需要bfs的点先一起入队，然后一起处理。所以，我们应该写成这样：

from collections import deque

def updateMatrix(self, mat: list[list[int]]) -> list[list[int]]:
    m = len(mat)
    n = len(mat[0])
    q = deque()
    dist = [[-1]*n for _ in range(m)]
    for i in range(m):
        for j in range(n):
            if mat[i][j] == 0:
                dist[i][j] = 0
                q.append((i,j))

    directions = [(-1, 0), (1, 0), (0, -1), (0, 1)]

    # 多源bfs
    while q:
        x,y = q.popleft()
        for dx,dy in directions:
            nx,ny = x + dx, y + dy
            # dist兼用visited
            if 0<=nx<m and 0<=ny<n and dist[nx][ny] == -1:
                # 向外扩散
                dist[nx][ny] = dist[x][y] + 1
                q.append((nx,ny))
    return dist

LC286 - 墙与门

这一题和上一题 LC542 - 01 矩阵 几乎是同一种味道，都是典型的多源 BFS。

题目大意如下：

给定一个 m x n 的二维网格 rooms，其中每个位置有三种可能的值：

-1 表示墙或者障碍物
0 表示一扇门
INF 表示一个空房间，这里的 INF = 2147483647

要求你把每个空房间替换成它到最近门的距离。如果无法走到任何门，那么这个位置保持 INF 不变。

例如：

输入：
INF  -1   0  INF
INF INF INF  -1
INF  -1 INF  -1
  0  -1 INF INF

运行之后应变成：

  3  -1   0   1
  2   2   1  -1
  1  -1   2  -1
  0  -1   3   4

这题如果朴素去想，很容易写成“对每个空房间单独做一次 BFS 去找最近的门”，但那样复杂度会很高。更好的方式是：

把所有门 0 一起入队
同时向外扩散
第一次更新到某个空房间时，这个距离就是它到最近门的最短距离

from collections import deque

def wallsAndGates(self, rooms: list[list[int]]) -> None:
    if not rooms or not rooms[0]:
        return

    INF = 2147483647
    m, n = len(rooms), len(rooms[0])
    q = deque()

    for i in range(m):
        for j in range(n):
            if rooms[i][j] == 0:
                q.append((i, j))

    directions = [(1, 0), (-1, 0), (0, 1), (0, -1)]

    while q:
        x, y = q.popleft()
        for dx, dy in directions:
            nx, ny = x + dx, y + dy
            if 0 <= nx < m and 0 <= ny < n and rooms[nx][ny] == INF:
                rooms[nx][ny] = rooms[x][y] + 1
                q.append((nx, ny))

双向 BFS

LC127 - 单词接龙

字典 wordList 中从单词 beginWord 到 endWord 的转换序列是一个按下述规格形成的序列 beginWord -> s1 -> s2 -> ... -> sk：

每一对相邻的单词只差一个字母。
对于 1 <= i <= k 时，每个 si 都在 wordList 中。注意， beginWord 不需要在 wordList 中。
sk == endWord

给你两个单词 beginWord 和 endWord 和一个字典 wordList ，返回从 beginWord 到 endWord 的最短转换序列中的单词数目。如果不存在这样的转换序列，返回 0 。

本题也是求到终点的路径长度，当相差一个字母的时候可以转移，我们通过辅助函数来判断能不能转移。

但是，如果这一题从一头开始搜，因为一个单词可以改26个字母，如果只从一路搜，路数会膨胀得很快。所以我们从两边一起往中间搜，只要遇到了，就存在。

def ladderLength(self, beginWord: str, endWord: str, wordList: list[str]) -> int:
    word_set = set(wordList)
    if endWord not in word_set:
        return 0

    begin_set = {beginWord}
    end_set = {endWord}
    visited = {beginWord, endWord}
    step = 1

    while begin_set and end_set:
        # 始终从更小的一侧扩展，减少分支数
        if len(begin_set) > len(end_set):
            begin_set, end_set = end_set, begin_set

        next_level = set()

        for word in begin_set:
            word_chars = list(word)

            for i in range(len(word_chars)):
                old = word_chars[i]

                for ch in 'abcdefghijklmnopqrstuvwxyz':
                    if ch == old:
                        continue

                    word_chars[i] = ch
                    new_word = ''.join(word_chars)

                    if new_word in end_set:
                        return step + 1

                    if new_word in word_set and new_word not in visited:
                        visited.add(new_word)
                        next_level.add(new_word)

                word_chars[i] = old

        begin_set = next_level
        step += 1

    return 0

BFS 常见模板

单源 BFS：

from collections import deque

q = deque([start])
visited = {start}
step = 0

while q:
    for _ in range(len(q)):
        cur = q.popleft()
        if cur == target:
            return step
        for nxt in get_next(cur):
            if nxt not in visited:
                visited.add(nxt)
                q.append(nxt)
    step += 1

多源 BFS 的差别是：先把所有源点一起入队，并全部标记为已访问。

网格搜索：二维数组上的 DFS 和 BFS

网格搜索的核心理解

网格搜索可以看成图搜索：每个格子是节点，四个方向或八个方向是边。关键是先统一方向数组，再把越界、障碍、访问过这些条件写清楚。

网格 DFS 模板

directions = [(1, 0), (-1, 0), (0, 1), (0, -1)]

def dfs(i, j):
    if not (0 <= i < m and 0 <= j < n):
        return
    if is_blocked(i, j):
        return
    grid[i][j] = VISITED
    for dx, dy in directions:
        dfs(i + dx, j + dy)

网格 BFS 模板

from collections import deque

directions = [(1, 0), (-1, 0), (0, 1), (0, -1)]
q = deque([(start_x, start_y)])
visited = {(start_x, start_y)}

while q:
    x, y = q.popleft()
    for dx, dy in directions:
        nx, ny = x + dx, y + dy
        if 0 <= nx < m and 0 <= ny < n and (nx, ny) not in visited:
            visited.add((nx, ny))
            q.append((nx, ny))

岛屿类问题

LC200 - 岛屿数量

岛屿数量是经典的多源dfs，每次dfs的时候我们将相邻的1全部变为0，二重循环进行dfs，最后统计dfs的次数即可。注意一下dfs的退出条件即可。

def numIslands(self, grid: list[list[str]]) -> int:
    m = len(grid)
    n = len(grid[0])
    def dfs(i,j):
        if not 0<=i<m or not 0<=j<n or grid[i][j] == '0':
            return
        grid[i][j] = '0'
        dfs(i+1,j)
        dfs(i-1,j)
        dfs(i,j+1)
        dfs(i,j-1)

    count = 0
    for i in range(m):
        for j in range(n):
            if grid[i][j] == '1':
                dfs(i,j)
                count += 1
    return count

LC695 - 岛屿的最大面积

岛屿的最大面积，我们直接让dfs返回这次遍历的面积即可，也就是返回的时候加上方向的dfs。

def maxAreaOfIsland(self, grid: list[list[int]]) -> int:
    m = len(grid)
    n = len(grid[0])
    def dfs(i,j):
        if not 0<=i<m or not 0<=j<n or grid[i][j] == 0:
            return 0
        grid[i][j] = 0
        return 1+dfs(i+1,j)+dfs(i-1,j)+dfs(i,j+1)+dfs(i,j-1)

    max_S = 0
    for i in range(m):
        for j in range(n):
            if grid[i][j] == 1:
                S = dfs(i,j)
                max_S = max(S,max_S)
    return max_S

LC1254 - 统计封闭岛屿的数目

这一题的思路是，我们先遍历边界，与边界相邻的大陆必不可能是被包围的岛，所以直接淹掉。然后，就变成了岛屿数目统计，在水中间的都是被包围的。

def closedIsland(self, grid: list[list[int]]) -> int:
        m = len(grid)
        n = len(grid[0])
        def dfs(i,j):
            if not 0<=i<m or not 0<=j<n or grid[i][j] == 1:
                return
            grid[i][j] = 1
            dfs(i+1,j)
            dfs(i-1,j)
            dfs(i,j+1)
            dfs(i,j-1)

        # 加一个淹没边界
        for i in range(m):
            if grid[i][0] == 0:
                dfs(i,0)
            if grid[i][n-1] == 0:
                dfs(i,n-1)
        for j in range(n):
            if grid[0][j] == 0:
                dfs(0,j)
            if grid[m-1][j] == 0:
                dfs(m-1,j)

        count = 0
        for i in range(m):
            for j in range(n):
                if grid[i][j] == 0:
                    dfs(i,j)
                    count += 1
        return count

LC1020 - 飞地的数量

也是边界淹没，然后统计内部面积就行。

def numEnclaves(self, grid: list[list[int]]) -> int:
        m = len(grid)
        n = len(grid[0])
        def dfs(i,j):
            if not 0<=i<m or not 0<=j<n or grid[i][j] == 0:
                return 0
            grid[i][j] = 0
            return 1+dfs(i+1,j)+dfs(i-1,j)+dfs(i,j+1)+dfs(i,j-1)

        # 加一个淹没边界
        for i in range(m):
            dfs(i,0)
            dfs(i,n-1)
        for j in range(n):
            dfs(0,j)
            dfs(m-1,j)

        total = 0
        for i in range(m):
            for j in range(n):
                if grid[i][j] == 1:
                    total += dfs(i,j)     
        return total

LC463 - 岛屿的周长

这一题让dfs返回周长贡献，有三种情况：

某方向越界，说明是外边界，贡献为1
某方向临水，说明露出来，贡献也是1
某方向贴着陆地，贡献就是0了

def islandPerimeter(self, grid: list[list[int]]) -> int:
        m = len(grid)
        n = len(grid[0])
        visited = set()
        def dfs(i,j):
            if not 0<=i<m or not 0<=j<n or grid[i][j] == 0:
                return 1
            if (i,j) in visited:
                return 0
            visited.add((i,j))
            return dfs(i+1,j)+dfs(i-1,j)+dfs(i,j+1)+dfs(i,j-1)

        # 只有一块岛屿
        for i in range(m):
            for j in range(n):
                if grid[i][j] == 1:
                    return dfs(i,j) 
        return 0

注意这一题不能将陆地简单变成水，否则会影响到周长计算，所以我们需要额外的visited统计这里有没有算过，防止回头。

边界反向搜索

LC130 - 被围绕的区域

这一题就是将被X围绕的所有O变成X。我们可以先看边界来dfs，将O先变成#，然后将剩下的O全变成X，再将#变成O。

def solve(self, board: list[list[str]]) -> None:
    if not board or not board[0]:
        return

    m, n = len(board), len(board[0])

    def dfs(i, j):
        if not (0 <= i < m and 0 <= j < n) or board[i][j] != 'O':
            return

        board[i][j] = '#'

        dfs(i + 1, j)
        dfs(i - 1, j)
        dfs(i, j + 1)
        dfs(i, j - 1)

    for i in range(m):
        dfs(i, 0)
        dfs(i, n - 1)

    for j in range(n):
        dfs(0, j)
        dfs(m - 1, j)

    for i in range(m):
        for j in range(n):
            if board[i][j] == 'O':
                board[i][j] = 'X'
            elif board[i][j] == '#':
                board[i][j] = 'O'

LC417 - 太平洋大西洋水流问题

如果每个格子 DFS 两次来判断会比较麻烦，我们可以分别从太平洋和大西洋边界区 DFS，然后每次往高处爬，将能够到的位置全都存入各自的 set 中，最后判断同时在两个 set 中的位置。

def pacificAtlantic(self, heights: list[list[int]]) -> list[list[int]]:
    m, n = len(heights), len(heights[0])
    
    pacific = set()
    atlantic = set()

    def dfs(i, j, visited, prev_height):
        if not (0 <= i < m and 0 <= j < n):
            return
        if (i, j) in visited:
            return
        if heights[i][j] < prev_height:
            return

        visited.add((i, j))

        dfs(i + 1, j, visited, heights[i][j])
        dfs(i - 1, j, visited, heights[i][j])
        dfs(i, j + 1, visited, heights[i][j])
        dfs(i, j - 1, visited, heights[i][j])

    for i in range(m):
        dfs(i, 0, pacific, heights[i][0])
        dfs(i, n - 1, atlantic, heights[i][n - 1])

    for j in range(n):
        dfs(0, j, pacific, heights[0][j])
        dfs(m - 1, j, atlantic, heights[m - 1][j])

    ans = []
    for i in range(m):
        for j in range(n):
            if (i, j) in pacific and (i, j) in atlantic:
                ans.append([i, j])

    return ans

单词与路径搜索

LC79 - 单词搜索

二重循环枚举每个格子作为起点，如果该格子等于单词首字母，就从这里开始 DFS。DFS 中用 pos 表示当前匹配到 word[pos]，用 visited 防止当前路径中重复使用同一个格子。若 pos == len(word)，说明整个单词匹配成功，返回 True。每次递归结束后需要回溯，将当前格子从 visited 中移除；如果所有起点都无法匹配，则返回 False。

def exist(self, board: list[list[str]], word: str) -> bool:
    m, n = len(board), len(board[0])
    visited = set()

    def dfs(i, j, pos):
        if pos == len(word):
            return True

        if not (0 <= i < m and 0 <= j < n):
            return False

        if (i, j) in visited:
            return False

        if board[i][j] != word[pos]:
            return False

        visited.add((i, j))

        found = (
            dfs(i + 1, j, pos + 1)
            or dfs(i - 1, j, pos + 1)
            or dfs(i, j + 1, pos + 1)
            or dfs(i, j - 1, pos + 1)
        )

        visited.remove((i, j))

        return found

    for i in range(m):
        for j in range(n):
            if board[i][j] == word[0] and dfs(i, j, 0):
                return True

    return False

注意这里是路径级别的visited而不是全局，所以每个dfs中会进行回溯。

LC212 - 单词搜索 II

如果这一题按照n次单词搜索来做就会超时，因为当words很多的时候，重复搜索会非常严重。这一题实际上是标准的Trie字典树+DFS回溯。

Trie树是一种用空间换时间的结构，如果你还记得，hot100中有一题就是让构建Trie树。构建好Trie树之后，这一题就是从每个点开始往下搜，搜到了就append答案。

def findWords(self, board: list[list[str]], words: list[str]) -> list[str]:
    class TrieNode:
        def __init__(self):
            self.children = {}
            self.word = None
        
    class Trie:
        def __init__(self):
            self.root = TrieNode()

        def insert(self,word:str):
            node = self.root
            for ch in word:
                if ch not in node.children:
                    node.children[ch] = TrieNode()
                node = node.children[ch]
            node.word = word

    # 初始化Trie树
    T = Trie()
    for word in words:
        T.insert(word)
    
    # 开始检查，从i、j开始，能不能找到单词
    m = len(board)
    n = len(board[0])

    ans = []

    def dfs(i, j, node):
        if not (0 <= i < m and 0 <= j < n):
            return

        ch = board[i][j]

        # 遍历过或者不在后续
        if ch == "#" or ch not in node.children:
            return

        nxt = node.children[ch]
        # 如果找到
        if nxt.word is not None:
            ans.append(nxt.word)
            nxt.word = None

        # 防止回头
        board[i][j] = "#"

        dfs(i + 1, j, nxt)
        dfs(i - 1, j, nxt)
        dfs(i, j + 1, nxt)
        dfs(i, j - 1, nxt)

        # 路径级回溯
        board[i][j] = ch

    for i in range(m):
        for j in range(n):
            dfs(i, j, T.root)

    return ans

网格搜索常见坑点

grid 里到底是字符串 '1' 还是整数 1，要看题目类型。
DFS 能不能原地修改，取决于修改后会不会影响后续判断。
BFS 的 visited 尽量入队时标记。
求最短路优先 BFS，求连通块数量/面积优先 DFS。
边界反向搜索常用于“被边界影响的区域不算答案”的题。

回溯搜索：枚举所有选择

回溯的核心思想

回溯就是 DFS 枚举选择，并在递归返回后撤销选择。它适合解决“所有方案”“所有组合”“所有排列”“所有切割方式”这类题。

回溯和 DFS 的关系

回溯是 DFS 的一种特殊写法。普通 DFS 只关心能不能走到；回溯还要维护路径，并在离开当前选择时恢复现场。

path、choice、used 的含义

path 表示当前已经构造出的方案，choice 表示这一层可选的候选项，used 或 visited 表示哪些元素在当前路径中已经被使用。

子集问题

LC78 - 子集

经典子集问题，默写级别。两种递归，要么递归 i 选不选，要么递归从 start 开始往下枚举选谁，首先是 start 模板：

def subsets(self, nums: list[int]) -> list[list[int]]:
    path = []
    ans = []
    def dfs(start:int):
        ans.append(path[:])
        for i in range(start,len(nums)):
            path.append(nums[i])
            dfs(i+1)
            path.pop()
    dfs(0)
    return ans

这里的 for 循环负责枚举“下一个要选的元素”；而“不再继续选”的情况，由进入 DFS 后立刻 ans.append(path[:]) 表示。所以不用你手动维护不选。

我们再来看看位置的思路，更加自然，但是通用性降低，也就是直接遍历候选，看看选不选。

def subsets(self, nums: list[int]) -> list[list[int]]:
    path = []
    ans = []
    def dfs(i):
        if i == len(nums):
            ans.append(path[:])
            return
        path.append(nums[i])
        dfs(i+1)
        path.pop()
        dfs(i+1)
    dfs(0)
    return ans

LC90 - 子集 II

先sort一下，然后重复元素跳过就行。

def subsetsWithDup(self, nums: list[int]) -> list[list[int]]:
    nums.sort()
    ans = []
    path = []
    def dfs(start):
        ans.append(path[:])
        # 跳过重复元素
        for i in range(start,len(nums)):
            if i>start and nums[i-1] == nums[i]:
                continue
            path.append(nums[i])
            dfs(i+1)
            path.pop()
    dfs(0)
    return ans

组合问题

LC77 - 组合

组合问题，要求返回范围 [1, n] 中所有可能的 k 个数的组合，不能复选。其实判断加入ans的条件就是 len(path) == k，其余的和子集差不多。

from typing import List

def combine(self, n: int, k: int) -> List[List[int]]:
    ans = []
    path = []
    def dfs(start):
        if len(path) == k:
            ans.append(path[:])
            return
        for i in range(start,n+1):
            path.append(i)
            dfs(i+1)
            path.pop()
    dfs(1)
    return ans

LC39 - 组合总和

找出数字和为目标数target的组合，而且可以重复选，而且candidates无重复元素。

from typing import List

def combinationSum(self, candidates: List[int], target: int) -> List[List[int]]:
    ans = []
    path = []
    def dfs(start,target):
        if target<0:
            return
        if target == 0:
            ans.append(path[:])
            return
        for i in range(start,len(candidates)):
            path.append(candidates[i])
            # 可复选，不用i+1
            dfs(i,target - candidates[i])
            path.pop()
    dfs(0,target)
    return ans

LC40 - 组合总和 II

与上一题的区别在于每个数字只能使用一次+组合不允许重复，且candidates中可有重复元素。

from typing import List

def combinationSum2(self, candidates: List[int], target: int) -> List[List[int]]:
    candidates.sort()
    ans = []
    path = []
    def dfs(start,target):
        if target<0:
            return
        if target == 0:
            ans.append(path[:])
            return
        
        for i in range(start,len(candidates)):
            if i>start and candidates[i-1] == candidates[i]:
                continue
            path.append(candidates[i])
            dfs(i+1,target-candidates[i])
            path.pop()
    dfs(0,target)
    return ans

LC216 - 组合总和 III

找出所有相加之和为 n 的 k 个数的组合，且满足下列条件：

只使用数字1到9
每个数字最多使用一次

且不能重复组合。其实就是上一题的简化版，候选变成了1-9。

from typing import List

def combinationSum3(self, k: int, n: int) -> List[List[int]]:
    ans = []
    path = []
    def dfs(start,target):
        if target < 0:
            return
        if target == 0 and len(path) == k:
            ans.append(path[:])
            return
        for i in range(start,10):
            path.append(i)
            dfs(i+1,target-i)
            path.pop()
    dfs(1,n)
    return ans

排列问题

LC46 - 全排列

排列问题中，我们每次都要重头开始数，因为可能后面排在前面。因此，我们还要维护一个数组，来表示对应下标有没有被使用过。

from typing import List

def permute(self, nums: List[int]) -> List[List[int]]:
    n = len(nums)
    seen = [False]*n
    path = []
    ans = []
    def dfs():
        if len(path) == n:
            ans.append(path[:])
            return
        for i in range(n):
            if seen[i]:
                continue
            seen[i] = True
            path.append(nums[i])
            dfs()
            path.pop()
            seen[i] = False
    dfs()
    return ans

LC47 - 全排列 II

给定一个可包含重复数字的序列 nums ，按任意顺序返回所有不重复的全排列。

其实跟刚才是一样的，就是多了个重复元素，排序后跳过。

from typing import List

def permuteUnique(self, nums: List[int]) -> List[List[int]]:
    nums.sort()
    n = len(nums)
    seen = [False]*n
    path = []
    ans = []
    def dfs():
        if len(path) == n:
            ans.append(path[:])
            return
        for i in range(n):
            if seen[i]:
                continue
            # 多了一个判断，如果之前没用，现在也不准用，也就是说不允许有顺序区分
            if i>0 and nums[i] == nums[i-1] and not seen[i-1]:
                continue
            seen[i] = True
            path.append(nums[i])
            dfs()
            path.pop()
            seen[i] = False
    dfs()
    return ans

切割问题

LC131 - 分割回文串

一维分割问题其实就是每次找到一种方案之后再递归下一个位置分割，直到分割完毕保存答案。

from typing import List

def partition(self, s: str) -> List[List[str]]:
    def palindrome(string:str):
        i, j = 0, len(string)-1
        while i<j:
            if string[i]!=string[j]:
                return False
            i += 1
            j -= 1
        return True
    
    ans = []
    path = []

    def dfs(start):
        if start == len(s):
            ans.append(path[:])
            return
        for i in range(start,len(s)):
            curr = s[start:i+1]
            if palindrome(curr):
                path.append(curr)
                dfs(i+1)
                path.pop()
    dfs(0)
    return ans

LC93 - 复原 IP 地址

跟上一题类似的划分类问题，判断每个划分合不合理，出了额外判断最后是不是被分为了4段之外，还有每段不超过3位、前导0等，总体难在各种情况都考虑到。

from typing import List

def restoreIpAddresses(self, s: str) -> List[str]:
    def isValid(string:str):
        if string[0] == '0' and len(string)>1:
            return False
        num = int(string)
        return 0<=num<=255
    
    path = []
    ans = []
    def dfs(start):
        if len(path)>4:
            return
        if start == len(s):
            if len(path) == 4:
                ans.append(".".join(path))
            return
        # 这里要限制最多三位
        for i in range(start,min(start+3,len(s))):
            curr = s[start:i+1]
            if isValid(curr):
                path.append(curr)
                dfs(i+1)
                path.pop()
    dfs(0)
    return ans

棋盘搜索

LC51 - N 皇后

N皇后需要用集合存储一下行、列、主对角、副对角是否被用了。其中主对角和副对角就是用坐标的关系，主对角作差定值，副对角求和定值。

from typing import List

def solveNQueens(self, n: int) -> List[List[str]]:
    col, diag1, diag2 = set(), set(), set()
    # 由于每一行最多放一个，用dfs(i)表示放第i行
    ans = []
    grid = [['.']*n for _ in range(n)]
    def dfs(i):
        if i == n:
            ans.append(["".join(row) for row in grid])
            return
        for j in range(n):
            if j not in col and i+j not in diag1 and i-j not in diag2:
                grid[i][j] = 'Q'
                col.add(j)
                diag1.add(i+j)
                diag2.add(i-j)
                dfs(i+1)
                grid[i][j] = '.'
                col.remove(j)
                diag1.remove(i+j)
                diag2.remove(i-j)
    dfs(0)
    return ans

LC52 - N 皇后 II

基本是N皇后的简化版，只要统计数目。

from typing import List

def totalNQueens(self, n: int) -> int:
    col, diag1, diag2 = set(), set(), set()
    # 由于每一行最多放一个，用dfs(i)表示放第i行
    count = 0
    def dfs(i):
        nonlocal count
        if i == n:
            count += 1
            return
        for j in range(n):
            if j not in col and i+j not in diag1 and i-j not in diag2:
                col.add(j)
                diag1.add(i+j)
                diag2.add(i-j)
                dfs(i+1)
                col.remove(j)
                diag1.remove(i+j)
                diag2.remove(i-j)
    dfs(0)
    return count

LC37 - 解数独

这里有三个要求，首先是行集合，然后是列结合，最后还有一个3x3box内的集合，这个我们用取余实现找到在第几个小方格内。

然后，我们是通过找出所有空位，然后用dfs去一个一个填，看看能不能找到解决问题的答案。

def solveSudoku(self, board: list[list[str]]) -> None:
    rows = [set() for _ in range(9)]
    cols = [set() for _ in range(9)]
    boxes = [set() for _ in range(9)]
    # 先找出所有空位，然后dfs去填
    spaces = []

    for i in range(9):
        for j in range(9):
            if board[i][j] == ".":
                spaces.append((i, j))
            else:
                num = board[i][j]
                rows[i].add(num)
                cols[j].add(num)
                # 还有3x3也要去重合
                boxes[(i // 3) * 3 + j // 3].add(num)

    def dfs(idx: int) -> bool:
        if idx == len(spaces):
            return True

        i, j = spaces[idx]
        box_idx = (i // 3) * 3 + j // 3

        for num in map(str, range(1, 10)):
            if num in rows[i]:
                continue
            if num in cols[j]:
                continue
            if num in boxes[box_idx]:
                continue

            board[i][j] = num
            rows[i].add(num)
            cols[j].add(num)
            boxes[box_idx].add(num)

            if dfs(idx + 1):
                return True

            board[i][j] = "."
            rows[i].remove(num)
            cols[j].remove(num)
            boxes[box_idx].remove(num)

        return False

    dfs(0)

回溯剪枝

剪枝的目标是提前停止没有意义的搜索。常见剪枝包括：

剩余目标小于 0，直接返回。
排序后遇到同层重复元素，跳过。
当前路径长度已经超过限制，返回。
当前前缀在 Trie 中不存在，返回。

剪枝一定要保证不漏答案。比如组合去重里 i > start and nums[i] == nums[i - 1] 是“同层去重”，不能写成所有重复都跳过。

回溯常见模板

组合/子集模板：

def dfs(start):
    ans.append(path[:])
    for i in range(start, len(nums)):
        path.append(nums[i])
        dfs(i + 1)
        path.pop()

排列模板：

def dfs():
    if len(path) == len(nums):
        ans.append(path[:])
        return
    for i in range(len(nums)):
        if used[i]:
            continue
        used[i] = True
        path.append(nums[i])
        dfs()
        path.pop()
        used[i] = False

图的遍历与染色

图的表示方式

常见图表示有两种：

邻接表：graph[u] 存所有从 u 能到达的点，适合稀疏图和大多数 LeetCode 图题。
邻接矩阵：matrix[i][j] 表示 i 和 j 是否相连，适合节点数较少或题目直接给矩阵。

邻接表和邻接矩阵

边列表建邻接表时，无向图要加两条边，有向图只加一条边：

graph = [[] for _ in range(n)]
for u, v in edges:
    graph[u].append(v)
    graph[v].append(u)  # 无向图才需要这一句

有向图和无向图

无向图搜索重点是连通性和二分图。有向图除了连通性，还经常涉及环、依赖关系、拓扑排序。

图遍历中的 visited

无向图一般用 visited 防止回头。有向图判环常用三色标记：0 未访问，1 当前路径中，2 已完成。

二分图判断

LC785 - 判断二分图

二分图是图恰好能分为两边的节点，左边全部指向右边。（如果能将一个图的节点集合分割成两个独立的子集 A 和 B ，并使图中的每一条边的两个节点一个来自 A 集合，一个来自 B 集合，就将这个图称为二分图。）

以下情况可考虑有二分图：

能不能把人/点分成两组，使得有关系的两个点不在同组
相邻节点不能有相同颜色
判断图是否可以用两种颜色染色
图中是否存在奇数环
敌对关系、互斥关系、分组问题

用DFS来判断二分图，可以用color数组给每个节点染色（1/-1），如果一个节点是1，邻居必须是-1，反之亦然。我们用这种方式走一条路径，如果和邻居撞色就失败了。我们从每个还没涂色的点进行dfs。

def isBipartite(self, graph: list[list[int]]) -> bool:
    n = len(graph)
    # 默认都没涂色
    color = [0] * n

    def dfs(node, c):
        color[node] = c

        for nxt in graph[node]:
            if color[nxt] == 0:
                if not dfs(nxt, -c):
                    return False
            elif color[nxt] == c:
                return False

        return True

    for i in range(n):
        if color[i] == 0:
            if not dfs(i, 1):
                return False

    return True

LC886 - 可能的二分法

我们用dislikes建图，然后看看能不能二分就可以了。

from typing import List

def possibleBipartition(self, n: int, dislikes: List[List[int]]) -> bool:
    graph = [[] for _ in range(n)]
    for d in dislikes:
        graph[d[0]-1].append(d[1]-1)
        graph[d[1]-1].append(d[0]-1)

    # 接下来，判断graph是否是二分图即可
    color = [0] * n 
    def dfs(node,c):
        color[node] = c
        for nxt in graph[node]:
            if color[nxt] == 0:
                if not dfs(nxt,-c):
                    return False
            elif color[nxt] == c:
                return False
        return True

    for i in range(n):
        if color[i] == 0:
            if not dfs(i,1):
                return False
    return True

克隆图

LC133 - 克隆图

数据结构的克隆，都是先建立旧节点-新节点的映射字典，然后用新.next = 新（旧.next）来解决。也就是传统做法，两轮法：

class Node:
    def __init__(self,val = 0):
        self.val = val
        self.neighbors = []

def cloneGraph(self, node: Node) -> Node:
    if not node:
        return None

    originToClone = {}
    # DFS 遍历图
    def dfs(node:Node):
        if node in originToClone:
            return
        originToClone[node] = Node(node.val)
        for nxt in node.neighbors:
            dfs(nxt)
    
    dfs(node)

    # 开始克隆关系
    for origin, clone in originToClone.items():
        for nxt in origin.neighbors:
            clone.neighbors.append(originToClone[nxt])
    
    return originToClone[node]

我们可以在一次dfs中一遍创建克隆节点，一遍克隆邻居关系。

class Node:
    def __init__(self, val=0, neighbors=None):
        self.val = val
        self.neighbors = neighbors if neighbors is not None else []


def cloneGraph(self, node: Node) -> Node:
    if not node:
        return None

    originToClone = {}

    # 每层dfs负责创建并返回clone节点，然后在dfs中也克隆关系
    def dfs(node):
        if node in originToClone:
            return originToClone[node]

        clone = Node(node.val)
        originToClone[node] = clone

        for nxt in node.neighbors:
            clone.neighbors.append(dfs(nxt))

        return clone

    return dfs(node)

图遍历常见模板

无向图连通性：

def dfs(node):
    if node in visited:
        return
    visited.add(node)
    for nxt in graph[node]:
        dfs(nxt)

有向图判环：

def dfs(node):
    if state[node] == 1:
        return False
    if state[node] == 2:
        return True
    state[node] = 1
    for nxt in graph[node]:
        if not dfs(nxt):
            return False
    state[node] = 2
    return True

拓扑排序：有向无环图上的遍历

什么是拓扑排序

拓扑排序是把有向图中的节点排成一个线性顺序，使得每条边 u -> v 都满足 u 在 v 前面。它只存在于有向无环图中。

入度表和队列

入度表示有多少条边指向当前节点。BFS 拓扑排序会先把所有入度为 0 的节点入队，然后每弹出一个节点，就把它指向的节点入度减 1。

DFS 拓扑排序

DFS 拓扑排序通常用后序收集。一个节点的所有后继都处理完后，再把当前节点加入答案，最后把答案反转。

BFS 拓扑排序

BFS 拓扑排序就是不断删除入度为 0 的节点。如果最后处理的节点数少于总节点数，说明图中有环。

课程表问题

LC207 - 课程表

这一题实际上就是判断有向图是否有环，我们先构成邻接表，然后一层一层剥下来。

from collections import deque

def canFinish(self, numCourses: int, prerequisites: list[list[int]]) -> bool:
    graph = [[] for _ in range(numCourses)]
    indegree = [0] * numCourses
    for u,v in prerequisites:
        graph[v].append(u)
        indegree[u]+=1

    # 开始拓扑排序
    q = deque()
    for i in range(numCourses):
        if indegree[i] == 0:
            q.append(i)
    
    count = 0
    while q:
        course = q.popleft()
        count += 1
        for nxt in graph[course]:
            indegree[nxt] -= 1
            if indegree[nxt] == 0:
                q.append(nxt)
    
    return count == numCourses

有向图判环，也可以使用DFS染色。我们可以用三种状态来表示节点状态，0没访问、1当前递归路径、2已经访问完成确认安全。

def canFinish(self, numCourses: int, prerequisites: list[list[int]]) -> bool:
    graph = [[] for _ in range(numCourses)]
    for u,v in prerequisites:
        graph[v].append(u)

    # 开始dfs
    visited = [0] * numCourses

    # 不碰到1，碰到2，就算完成任务。然后再给完成任务的节点标记为2。
    def dfs(course):
        if visited[course] == 1:
            return False
        if visited[course] == 2:
            return True
        
        visited[course] = 1

        for nxt in graph[course]:
            if not dfs(nxt):
                return False
        visited[course] = 2
        return True
    
    for i in range(numCourses):
        if visited[i] == 0:
            if not dfs(i):
                return False
    return True

LC210 - 课程表 II

本题需要返回学习完的顺序，其实就是在拓扑排序的时候收集一下答案，把count换成ans即可。

from collections import deque

def findOrder(self, numCourses: int, prerequisites: list[list[int]]) -> list[int]:
    graph = [[] for _ in range(numCourses)]
    indegree = [0] * numCourses
    for u,v in prerequisites:
        graph[v].append(u)
        indegree[u]+=1

    # 开始拓扑排序
    q = deque()
    for i in range(numCourses):
        if indegree[i] == 0:
            q.append(i)
    
    ans = []
    while q:
        course = q.popleft()
        ans.append(course)
        for nxt in graph[course]:
            indegree[nxt] -= 1
            if indegree[nxt] == 0:
                q.append(nxt)
    
    if len(ans) == numCourses:
        return ans
    return []

那么，同理，我们在dfs中多维持一个ans，也可以得到答案。不过顺序是反过来的。

    graph = [[] for _ in range(numCourses)]
    for u,v in prerequisites:
        graph[v].append(u)

    # 开始dfs
    visited = [0] * numCourses
    ans = []

    # 不碰到1，碰到2，就算完成任务。然后再给完成任务的节点标记为2。
    def dfs(course):
        if visited[course] == 1:
            return False
        if visited[course] == 2:
            return True
        
        visited[course] = 1

        for nxt in graph[course]:
            if not dfs(nxt):
                return False
        visited[course] = 2
        # 后序收集
        ans.append(course)
        return True
    
    for i in range(numCourses):
        if visited[i] == 0:
            if not dfs(i):
                return []
    return ans[::-1]

LC802 - 找到最终的安全状态

这一题说白了就是看从一个节点出发，有没有环。我们使用dfs比较方便。

def eventualSafeNodes(self, graph: list[list[int]]) -> list[int]:
    n = len(graph)
    visited = [0] * n
    
    def dfs(node):
        if visited[node] == 1:
            return False
        if visited[node] == 2:
            return True
        
        visited[node] = 1

        for nxt in graph[node]:
            if not dfs(nxt):
                return False
        
        visited[node] = 2
        return True
    
    ans = []
    for i in range(n):
        if dfs(i):
            ans.append(i)
    return ans

拓扑排序常见模板

BFS 拓扑排序：

from collections import deque

graph = [[] for _ in range(n)]
indegree = [0] * n

for u, v in edges:
    graph[u].append(v)
    indegree[v] += 1

q = deque(i for i in range(n) if indegree[i] == 0)
order = []

while q:
    cur = q.popleft()
    order.append(cur)
    for nxt in graph[cur]:
        indegree[nxt] -= 1
        if indegree[nxt] == 0:
            q.append(nxt)

has_cycle = len(order) != n

DFS 判环：

state = [0] * n

def dfs(node):
    if state[node] == 1:
        return False
    if state[node] == 2:
        return True
    state[node] = 1
    for nxt in graph[node]:
        if not dfs(nxt):
            return False
    state[node] = 2
    return True

搜索优化

剪枝

剪枝就是减少无意义分支。最常见的剪枝信号是：越界、已经访问、当前和超过目标、剩余数量不够、同层重复、前缀不存在。

记忆化搜索

当 DFS 中同一个状态会被重复计算时，可以用字典或数组记忆化。典型状态包括 (i, j)、(idx, remain)、node 等。

状态压缩

当状态里包含一组元素是否被使用，可以用二进制位压缩。比如 mask 的第 i 位表示第 i 个元素是否已经使用。

双向搜索

双向搜索适合起点和终点都明确、分支很大的最短路问题，比如单词接龙。从两边同时扩展，可以显著减少搜索层数。

A* 搜索

A* 是带启发式函数的最短路搜索。普通面试里不常考，知道它是在 Dijkstra/BFS 的基础上用估价函数优先探索更可能接近终点的状态即可。

搜索中的复杂度估算

DFS/BFS 的复杂度通常看状态数和转移数。回溯题可以粗略估算为搜索树节点数；图遍历通常是 O(V + E)；网格遍历通常是 O(mn)。

搜索与遍历题目的分类判断

看题目是否要求遍历所有节点

如果题目问数量、面积、连通性，通常要遍历所有可能节点。

看题目是否要求最短步数

无权图最短步数优先 BFS。

看题目是否需要枚举所有方案

所有方案、所有组合、所有路径，一般是 DFS/回溯。

看题目是否存在重复状态

有重复状态就要考虑 visited、记忆化或原地标记。

看题目是否需要撤销选择

如果同一个元素在不同路径里还能被再次使用，需要回溯撤销选择。

看题目是否有方向和依赖关系

有依赖关系通常建有向图；如果还要判断能不能完成，优先想到拓扑排序或 DFS 判环。

搜索与遍历常见模板

二叉树 DFS 模板

def dfs(node):
    if not node:
        return
    dfs(node.left)
    dfs(node.right)

二叉树 BFS 模板

q = deque([root])
while q:
    for _ in range(len(q)):
        node = q.popleft()

图 DFS 模板

def dfs(node):
    if node in visited:
        return
    visited.add(node)
    for nxt in graph[node]:
        dfs(nxt)

图 BFS 模板

q = deque([start])
visited = {start}
while q:
    cur = q.popleft()
    for nxt in graph[cur]:
        if nxt not in visited:
            visited.add(nxt)
            q.append(nxt)

网格 DFS 模板

def dfs(i, j):
    if not (0 <= i < m and 0 <= j < n):
        return
    if is_blocked(i, j):
        return
    grid[i][j] = VISITED
    for dx, dy in directions:
        dfs(i + dx, j + dy)

网格 BFS 模板

q = deque([(sx, sy)])
visited = {(sx, sy)}
while q:
    x, y = q.popleft()
    for dx, dy in directions:
        nx, ny = x + dx, y + dy

回溯模板

def dfs(start):
    if 满足条件:
        ans.append(path[:])
    for i in range(start, len(nums)):
        path.append(nums[i])
        dfs(i + 1)
        path.pop()

拓扑排序模板

q = deque(i for i in range(n) if indegree[i] == 0)
while q:
    cur = q.popleft()
    for nxt in graph[cur]:
        indegree[nxt] -= 1
        if indegree[nxt] == 0:
            q.append(nxt)

搜索与遍历问题总结

搜索与遍历题的本质是：先把题目抽象成节点和边，再决定用 DFS、BFS、回溯还是拓扑排序。DFS 适合深入和枚举，BFS 适合最短路和扩散，回溯适合所有方案，拓扑排序适合有向依赖。写代码时只要抓住状态、选择、出口、去重和剪枝，绝大多数题都能落到固定模板上。

算法总结-栈与队列

Sat, 21 Mar 2026 00:00:00 GMT

栈与队列的核心理解

什么是栈

栈是一种 后进先出（LIFO, Last In First Out）的数据结构。最后放进去的元素，最先被拿出来。

最常见的几个动作是：

push：压栈
pop：弹栈
top / peek：查看栈顶

栈的直觉非常像一摞盘子。你只能从最上面继续放，也只能从最上面拿。

刷题里，栈最常用于解决下面几类问题：

配对与匹配，比如括号匹配
撤销、回退、消消乐
表达式求值
单调栈维护“下一个更大/更小元素”

什么是队列

队列是一种 先进先出（FIFO, First In First Out）的数据结构。最先进入队列的元素，会最先离开。

常见动作是：

push / offer：入队
pop / poll：出队
front / peek：查看队头

队列非常像排队买饭。先来的人先处理，后来的只能排在后面。

刷题里，队列最常用于：

按顺序处理元素
层序遍历
BFS 最短步数问题
滑动窗口
单调队列维护窗口最值

栈和队列的区别

最核心的区别其实只有一句话：

栈：后进先出
队列：先进先出

也正因为这个区别，它们擅长处理的问题也不同：

栈更擅长“最近的、嵌套的、需要回退的”关系
队列更擅长“按到达顺序逐个处理”的关系

所以很多题目不是在考你会不会写 append 和 pop，而是在考你：

这个问题需要的是最近进入的元素，还是最早进入的元素？

什么情况下想到栈

看到下面这些特征，优先想栈：

括号匹配、标签匹配、路径回退
撤销、恢复、消消乐、相邻抵消
表达式求值
需要维护“最近一个比当前大/小”的元素
需要在扫描过程中保存“还没处理完的历史信息”

一句话记忆：

只要题目和“最近的未完成状态”有关，就很容易想到栈。

什么情况下想到队列

看到下面这些味道，优先想队列：

层序遍历
按轮次推进
最少步数、最短操作次数
数据流按顺序进入，旧元素会自然淘汰
滑动窗口

一句话记忆：

只要题目强调“顺序推进、一层一层扩散、最先进入最先处理”，就很容易想到队列。

Python 中的栈、队列、双端队列、优先队列

Python 里最常用的几个容器如下：

普通栈：直接用 list
普通队列 / 双端队列：用 collections.deque
优先队列：用 heapq

其中：

list.append() + list.pop() 就可以当栈用
deque.append() / deque.popleft() 很适合写队列
heapq 默认是小根堆，如果想模拟大根堆，通常存相反数

刷题时其实不用纠结“我是不是在手写一个正式数据结构”，更重要的是：

我现在需要维护哪种顺序？

基础栈题：后进先出

括号匹配

LC20 - 有效的括号

这是最基础的栈应用题，我们只需要用一个栈来决定就行。首先用字典记录右括号对应的左括号，右括号遇到左括号必须弹出，不然就是无效的，最后栈非空也是无效。

def isValid(self, s: str) -> bool:
    pairs = {')': '(', ']': '[', '}': '{'}
    stack = []

    for ch in s:
        if ch not in pairs:
            stack.append(ch)
            continue
        if not stack or stack.pop() != pairs[ch]:
            return False

    return not stack

如果只有一种括号，那么有另外一种思路，用左括号数量去判断有效性。如果要让字符串有效，那么必须每个右括号 ) 的左边必须有一个左括号 ( 和它匹配。所以我们维持一个变量left，遇到左括号+，遇到右括号-，这样中间是否会右括号太多以及最后只要判断是不是正好抵消就行。（其实与栈思路一样，只不过只用了一个变量）。本题不行，因为有三种括号，所以要加大统计量。

LC921 - 使括号有效的最少添加

只有满足下面几点之一，括号字符串才是有效的：

它是一个空字符串，或者
它可以被写成 AB （A 与 B 连接）, 其中 A 和 B 都是有效字符串，或者
它可以被写作 (A)，其中 A 是有效字符串。给定一个括号字符串 s ，在每一次操作中，你都可以在字符串的任何位置插入一个括号
例如，如果 s = "()))" ，你可以插入一个开始括号为 "(()))" 或结束括号为 "())))" 。返回为使结果字符串 s 有效而必须添加的最少括号数。

这一题可以回到需求的解法了，我们维持插入次数res、右括号的需求量need。如果是左括号，need+1即可；如果是右括号，我们不仅要-1，还要判断-1是不是变成刚需左括号了，如果是这样必须立刻补左括号，res+1。这样，我们最终返回res+need就是需要插入的总次数。

总而言之，我们在插入过程中维持有效性。

def minAddToMakeValid(self, s: str) -> int:
    res = 0
    need = 0
    for ch in s:
        if ch == '(':
            need += 1
        if ch == ')':
            need -= 1
            if need == -1:
                res += 1
                need += 1
    return res + need

LC1541 - 平衡括号字符串的最少插入次数

本题和上一题的区别在于，一个left要对应两个右括号了，简单改一下就能出答案。

def minInsertions(self, s: str) -> int:
    res = 0
    need = 0

    for ch in s:
        if ch == '(':
            # 当右括号需求为奇数，需要插入一个右括号到这个左括号前面，避免前面不匹配了。
            if need % 2 == 1:
                res += 1
                need -= 1
            # 插入一个左括号
            need += 2
        else:
            need -= 1
            if need == -1:
                res += 1
                need = 1

    return res + need

LC1249 - 移除无效的括号

这题要求从一个字符串中删除最小数量的括号，让括号有效。字符串中有一些无关小写字母。按照LC20相同的代码，其实我们就可以直接得到需要删除的个数，但是本题要求的是删除后的字符串，需要更多信息。但是其实改动也不多。

def minRemoveToMakeValid(self, s: str) -> str:
    ans = []
    balance = 0  # 当前 ans 里还没匹配掉的 '(' 个数

    for ch in s:
        if ch == '(':
            ans.append(ch)
            balance += 1
        elif ch == ')':
            if balance == 0:
                continue
            ans.append(ch)
            balance -= 1
        else:
            ans.append(ch)

    res = []
    for ch in reversed(ans):
        if ch == '(' and balance > 0:
            balance -= 1
            continue
        res.append(ch)

    return ''.join(reversed(res))

这一题，当然也可以用栈存待会要删除的下标（只存还没匹配的 ( 的下标），来之后构造答案，思路很自然：

def solution(s: str) -> str:
    stack = []
    chars = list(s)

    for i, ch in enumerate(chars):
        if ch == '(':
            stack.append(i)
        elif ch == ')':
            if stack:
                stack.pop()
            else:
                chars[i] = ''

    while stack:
        chars[stack.pop()] = ''

    return ''.join(chars)

综上，结构匹配型我们就用栈来做，数量欠账类的用res/need，构造答案则是两者皆可，用栈来存储更优雅。

表达式与字符串处理

LC150 - 逆波兰表达式求值

逆波兰式式经典应用栈求数值的题目。

def evalRPN(self, tokens: list[str]) -> int:
    stack = []

    for ch in tokens:
        if ch not in {'+', '-', '*', '/'}:
            stack.append(int(ch))
        else:
            a = stack.pop()
            b = stack.pop()

            if ch == '+':
                stack.append(b + a)
            elif ch == '-':
                stack.append(b - a)
            elif ch == '*':
                stack.append(b * a)
            else:
                stack.append(int(b / a))

    return stack[-1]

LC71 - 简化路径

我们通过curr_name来判断目前两个/直接夹的东西，并采用对应的栈操作。

def simplifyPath(self, path: str) -> str:
    stack = []
    # 核心，用来缓冲目前名称
    curr_name=""
    # 末尾添加 / 保证全部出栈
    for ch in path +'/':
        if ch == '/':
            # 如果是..则出栈
            if curr_name=="..":
                if stack:
                    stack.pop()
            # 如果不是废话（空或者.），压栈
            elif curr_name !="" and curr_name!=".":
                stack.append(curr_name)
            # 缓冲部分清空
            curr_name = ""
        # 接下来是普通字符，简单入栈
        else:
            curr_name+=ch
    return "/"+"/".join(stack)

LC227 - 基本计算器 II

这一题，其实是中缀表达式求值，上一题的逆波兰表达式则是后缀表达式。后缀表达式可以轻松用栈解决，中缀则是可以通过栈来转为后缀。思路如下：

遇到操作数直接加入后缀表达式
遇到左括号直接入栈，然后遇到右括号依次弹出栈内运算符并加入后缀表达式，直到弹出 ( 为止。
遇到运算符，则比较栈顶的运算符的优先级，如果比栈顶优先级高/栈顶为 ( /栈为空，则直接加入表达式；否则将栈顶弹出加入表达式，然后重新判断。
重复直到遍历完毕，将栈所有元素弹出，加入后缀表达式

不过对于本题来说，并不存在括号，我们可以这样来处理：遇到加减立刻将数字（取反）压栈，遇到乘除则立刻和栈顶计算：

def calculate(self, s: str) -> int:
    stack = []
    num = 0
    sign = '+'

    for i, ch in enumerate(s):
        # 多位数字
        if ch.isdigit():
            num = num * 10 + int(ch)

        if ch in '+-*/' or i == len(s) - 1:
            if sign == '+':
                stack.append(num)
            elif sign == '-':
                stack.append(-num)
            elif sign == '*':
                stack.append(stack.pop() * num)
            elif sign == '/':
                stack.append(int(stack.pop() / num))

            sign = ch
            num = 0

    return sum(stack)

为什么可以这么做？这是因为，我们用栈调整了运算顺序。如果是优先级较低的+-，我们先记账，留到最后一起加减；如果是乘除，我们就立刻运算。

LC224 - 基本计算器

这一题属于有括号，但只有+-。因此，也是有简化的方式：我们不用处理优先级，只需要看看这一层算到了多少、这一层整体前面带的符号是什么。

用res记录当前层结果
sign记录当前数字前的符号
num组装多位数
遇到 ( 将外层res和sign压栈，进入新的一层
遇到 ) 先结算当前层，再和外层合并

def calculate(self, s: str) -> int:
    stack = []
    res = 0
    num = 0
    sign = 1

    for ch in s:
        if ch.isdigit():
            num = num * 10 + int(ch)
        elif ch == '+':
            res += sign * num
            num = 0
            sign = 1
        elif ch == '-':
            res += sign * num
            num = 0
            sign = -1
        elif ch == '(':
            stack.append(res)
            stack.append(sign)
            res = 0
            sign = 1
        elif ch == ')':
            res += sign * num
            num = 0
            res *= stack.pop()
            res += stack.pop()

    return res + sign * num

LC772 - 基本计算器 III

这一题，不仅有括号，且有+-*/，没有什么比较好的方法遍历一次解决了。一般而言，我们可以用栈按照前面的技巧转为后缀表达式，然后用栈计算答案。但是，这一题更好的写法是“递归+栈”，也就是每一层递归只处理一层的表达式，遇到 ( 就递归进去，拿子表达式的结果当成一个普通数字 num 来继续算。

所以其实这一题可以根据基本计算器 II 加一个递归入口简单改编出来。

from collections import deque

def calculate(self, s: str) -> int:
    def dfs(q):
        num, sign, stk = 0, "+", []
        while q:
            c = q.popleft()
            if c.isdigit():
                num = num * 10 + int(c)
            if c == "(":
                num = dfs(q)
            if c in "+-*/)" or not q:
                match sign:
                    case "+":
                        stk.append(num)
                    case "-":
                        stk.append(-num)
                    case "*":
                        stk.append(stk.pop() * num)
                    case "/":
                        stk.append(int(stk.pop() / num))
                num, sign = 0, c
            if c == ")":
                break
        return sum(stk)

    return dfs(deque(s))

辅助栈与模拟栈

LC155 - 最小栈

最小栈是一种支持push、pop、top操作，并能在常数时间内检索到最小元素的栈，一般的解决思路是用两个栈来实现，一个栈stack来保存元素，然后用另一个栈min_stack[i] 表示主栈 stack[0..i] 这一层时的最小值：

class MinStack:

    def __init__(self):
        self.stack = []
        self.min_stack = []

    def push(self, val: int) -> None:
        # 最小栈为空或者新值不大于旧栈顶
        if not self.min_stack or val <= self.min_stack[-1]:
            self.min_stack.append(val)
        # 否则将最小值再次入栈
        else:
            self.min_stack.append(self.min_stack[-1])
        self.stack.append(val)

    def pop(self) -> None:
        if self.stack:
            self.stack.pop()
        if self.min_stack:
            self.min_stack.pop()

    def top(self) -> int:
        return self.stack[-1]
        

    def getMin(self) -> int:
        return self.min_stack[-1]

LC232 - 用栈实现队列

又是数据设计题，我们可以用两个栈来模拟队列，其中一个是常规栈，另一个用于出栈倒腾顺序：

class MyQueue:
    # 两个栈屁股对屁股实现
    def __init__(self):
        self.st1=[]
        self.st2=[]

    def push(self, x: int) -> None:
        # 入栈操作笔记普通，就是进st1
        self.st1.append(x)

    def pop(self) -> int:
        # 出栈先把st1全倒进st2，然后再出
        # 先调用peek作为前置操作，倒栈写在那里
        self.peek()
        return self.st2.pop()

    def peek(self) -> int:
        if not self.st2:
            # 把 st1 元素压入 st2
            while self.st1:
                self.st2.append(self.st1.pop())
        return self.st2[-1]       

    def empty(self) -> bool:
        return not self.st1 and not self.st2

LC225 - 用队列实现栈

用两个队列来实现栈，思路如下：

push(x)：直接进主队列
pop()：把前 n-1 个元素转移到辅助队列，最后剩下的那个就是栈顶，弹出它
操作结束后交换 q1 和 q2，让 q1 继续做主队列

from collections import deque

class MyStack:

    def __init__(self):
        self.q1 = deque()
        self.q2 = deque()

    def push(self, x: int) -> None:
        # q1正常入队
        self.q1.append(x)

    def pop(self) -> int:
        # 出队前倒腾顺序
        while len(self.q1)>1:
            self.q2.append(self.q1.popleft())
        ans = self.q1.popleft()
        self.q1,self.q2 = self.q2, self.q1
        return ans

    def top(self) -> int:
        while len(self.q1) > 1:
            self.q2.append(self.q1.popleft())
        ans = self.q1.popleft()
        # 多了一句元素归还q2，因为我们不需要真弹出
        self.q2.append(ans)
        self.q1, self.q2 = self.q2, self.q1
        return ans

    def empty(self) -> bool:
        return not self.q1

基础队列题：先进先出

普通队列

LC933 - 最近的请求次数

本题只记录和目前时间差3000以内的数目，所以我们可以直接用一个队列维护，如果队头和入队元素差距超过3000，直接弹出：

class RecentCounter:
    def __init__(self):
        self.q=deque()

    def ping(self, t: int) -> int:
        self.q.append(t)
        while t-self.q[0]>3000:
            self.q.popleft()
        return len(self.q)

LC649 - Dota2 参议院

本题是一个轮流禁言题，也就是循环回合 + 先手淘汰。按照原始顺序流动，每个 R 可以禁言一个 D，每个 D 可以禁言一个 R，直到最后只剩同一阵容胜利。

这一题最好的解法是用两个队列存储还活着的议员下标，然后每次队头下标小的先行动，把对方队头ban掉，然后把自己的下标加上n放到队尾（等下一轮），被ban掉的出队就不会再回来了。

from collections import deque

def predictPartyVictory(self, senate: str) -> str:
    n = len(senate)
    r_queue = deque()
    d_queue = deque()

    for i, ch in enumerate(senate):
        if ch == 'R':
            r_queue.append(i)
        else:
            d_queue.append(i)

    while r_queue and d_queue:
        r = r_queue.popleft()
        d = d_queue.popleft()

        if r < d:
            r_queue.append(r + n)
        else:
            d_queue.append(d + n)

    return "Radiant" if r_queue else "Dire"

双端队列

LC641 - 设计循环双端队列

这一题在 408 里也很常见。我们需要维持一个 front 和一个 rear，把数组想象成一个环，然后对这个环做入队、出队和取模移动。

class MyCircularDeque:

    def __init__(self, k: int):
        self.capacity = k + 1
        self.q = [0] * self.capacity
        self.front = 0
        self.rear = 0

    def insertFront(self, value: int) -> bool:
        if self.isFull():
            return False
        self.front = (self.front - 1 + self.capacity) % self.capacity
        self.q[self.front] = value
        return True

    def insertLast(self, value: int) -> bool:
        if self.isFull():
            return False
        self.q[self.rear] = value
        self.rear = (self.rear + 1) % self.capacity
        return True

    def deleteFront(self) -> bool:
        if self.isEmpty():
            return False
        self.front = (self.front + 1) % self.capacity
        return True

    def deleteLast(self) -> bool:
        if self.isEmpty():
            return False
        self.rear = (self.rear - 1 + self.capacity) % self.capacity
        return True

    def getFront(self) -> int:
        if self.isEmpty():
            return -1
        return self.q[self.front]

    def getRear(self) -> int:
        if self.isEmpty():
            return -1
        return self.q[(self.rear - 1 + self.capacity) % self.capacity]

    def isEmpty(self) -> bool:
        return self.front == self.rear

    def isFull(self) -> bool:
        return (self.rear + 1) % self.capacity == self.front

层序遍历与 BFS

队列常被用来实现层序遍历，所以这一组题也很适合放在这里一起理解。

LC102 - 二叉树的层序遍历

经典层序遍历，需要达到肌肉级别记忆。

from collections import deque

class TreeNode:
    def __init__(self,val =0 ,left = None, right = None):
        self.val = val
        self.left = left
        self.right = right

def levelOrder(self, root: TreeNode) -> list[list[int]]:
    if not root:
        return []
    q = deque([root])
    ans = []
    while q:
        sz = len(q)
        level = []
        for _ in range(sz):
            node = q.popleft()
            level.append(node.val)
            if node.left:
                q.append(node.left)
            if node.right:
                q.append(node.right)
        ans.append(level)
    return ans

LC107 - 二叉树的层序遍历 II

自底向上的层序遍历，和上一题相比只是 ans 改成从左边添加而已。

from collections import deque

def levelOrderBottom(self, root: TreeNode) -> list[list[int]]:
    if not root:
        return []

    q = deque([root])
    ans = deque()

    while q:
        level = []
        for _ in range(len(q)):
            node = q.popleft()
            level.append(node.val)
            if node.left:
                q.append(node.left)
            if node.right:
                q.append(node.right)
        ans.appendleft(level)

    return list(ans)

LC103 - 二叉树的锯齿形层序遍历

我们可以根据ans的长度得到奇数层偶数层，从而决定这个level是append还是appendleft。

from collections import deque

class TreeNode:
    def __init__(self,val =0 ,left = None, right = None):
        self.val = val
        self.left = left
        self.right = right

def zigzagLevelOrder(self, root: TreeNode) -> list[list[int]]:
    if not root:
        return []
    q = deque([root])
    ans = []
    while q:
        sz = len(q)
        level = deque()
        if len(ans)%2 == 0:
            for _ in range(sz):
                node = q.popleft()
                level.append(node.val)
                if node.left:
                    q.append(node.left)
                if node.right:
                    q.append(node.right)
        else:
            for _ in range(sz):
                node = q.popleft()
                level.appendleft(node.val)
                if node.left:
                    q.append(node.left)
                if node.right:
                    q.append(node.right)            
        ans.append(list(level))
    return ans

LC199 - 二叉树的右视图

右视图其实就是每层的最后一个节点，所以在普通层序遍历的基础上，取每个 level[-1] 即可。这题和前面几题的差别不在数据结构，而在“每层要收集哪一个元素”。

图论中的队列

LC994 - 腐烂的橘子

本题用队列来存储腐烂橘子的坐标，弹出的时候让周围的新鲜橘子入队，每层扩散一次，时间 +1。当队列为空时遍历结束，这时候如果还有新鲜橘子就不可能全部腐烂，返回 -1，否则返回分钟数。

from collections import deque

def orangesRotting(self, grid: list[list[int]]) -> int:
    m, n = len(grid), len(grid[0])
    q = deque()
    fresh = 0

    for i in range(m):
        for j in range(n):
            if grid[i][j] == 2:
                q.append((i, j))
            elif grid[i][j] == 1:
                fresh += 1

    if fresh == 0:
        return 0

    minutes = 0
    directions = [(1, 0), (-1, 0), (0, 1), (0, -1)]

    while q and fresh > 0:
        for _ in range(len(q)):
            x, y = q.popleft()
            for dx, dy in directions:
                nx, ny = x + dx, y + dy
                if 0 <= nx < m and 0 <= ny < n and grid[nx][ny] == 1:
                    grid[nx][ny] = 2
                    fresh -= 1
                    q.append((nx, ny))
        minutes += 1

    return minutes if fresh == 0 else -1

LC752 - 打开转盘锁

这一题的目标是最少步数，所以应该用BFS来做，因为BFS是天然的求“无权路最短图”的方法。如果用DFS，会一路走到底，然后要保证路径最短，还要将所有可能路径搜完，再取最小值，复杂度很差，且存在大量重复状态。

我们用bfs的次数就可以统计进行的步数，所以这一题只要把握好状态更新入队即可。

from collections import deque

class Solution:
    def update(self, old: str, i: int) -> tuple[str, str]:
        s1 = list(old)
        s2 = list(old)
        num = int(old[i])
        s1[i] = str((num + 9) % 10)
        s2[i] = str((num + 1) % 10)
        return ''.join(s1), ''.join(s2)

    def openLock(self, deadends: list[str], target: str) -> int:
        visited = set(deadends)
        if '0000' in visited:
            return -1

        q = deque(['0000'])
        visited.add('0000')
        depth = 0

        while q:
            for _ in range(len(q)):
                cur = q.popleft()
                if cur == target:
                    return depth

                for i in range(4):
                    s1, s2 = self.update(cur, i)
                    for state in (s1, s2):
                        if state not in visited:
                            visited.add(state)
                            q.append(state)

            depth += 1

        return -1

LC773 - 滑动谜题

依旧状态更新，依旧最短次数。我们直接一个广搜，用队列存储更新状态。可是，如果每次队列都存储一个二维数组，负担太大了，而且由于我们已经知道是2x3的板子了，可以先预处理好可以相邻下标。

from collections import deque
class Solution:
    # 我们需要先预处理一个邻居表，用于状态转移
    # 一下分别是2x3板子中，0-5对应的相邻索引
    mapping = [
        [1,3],
        [0,4,2],
        [1,5],
        [0,4],
        [3,1,5],
        [4,2]
    ]

    # 辅助函数，交换元素
    def update_status(self,old,i,j):
        new = old[:]
        new[i], new[j] = new[j], new[i]
        return new

    def slidingPuzzle(self, board: List[List[int]]) -> int:
        # BFS不仅是寻路算法，也是一种暴力搜索算法，暴力穷举的问题BFS都可以用
        target = [1,2,3,4,5,0]
        start = []
        for i in range(len(board)):
            for j in range(len(board[0])):
                start.append(board[i][j])

        q = deque()
        visited = set()
        # 从起点BFS开始搜索
        q.append(start)
        visited.add(tuple(start))

        step = 0
        while q:
            sz = len(q)
            for _ in range(sz):
                cur = q.popleft()
                if cur == target:
                    return step
                # 如果不是目标，将所以可能的转移状态写入
                zero_idx = cur.index(0)
                for to_swap in self.mapping[zero_idx]:
                    new = self.update_status(cur,zero_idx,to_swap)
                    if tuple(new) not in visited:
                        q.append(new)
                        visited.add(tuple(new))
            # 一个更新结束（bfs层）
            step += 1
        return -1

单调栈：维护下一个更大或更小

单调栈的核心思想

单调栈本质上还是栈，只不过我们在压栈时额外维护了一个“单调性”：

要么从栈底到栈顶单调递增
要么从栈底到栈顶单调递减

它最擅长解决的问题是：

下一个更大元素
下一个更小元素
上一个更大 / 更小元素
左右第一个打破单调性的位置
区间贡献问题

很多人第一次学单调栈，会觉得它像魔法。其实它做的事情非常朴素：

新元素一来，就把那些已经不可能成为答案的旧元素弹掉。

所以单调栈的关键不在“背模板”，而在想清楚：

栈里到底存的是值还是下标
当前元素来了之后，谁已经失去资格了
弹栈的那一刻，我能不能顺便结算答案

下一个更大元素

LC496 - 下一个更大元素 I

要找下一个更大元素，单调栈就是非常自然的解法。我们可以用哈希表记录每个元素下一个更大元素。

def nextGreaterElement(self, nums1: list[int], nums2: list[int]) -> list[int]:
    stack = []
    next_map = {}

    for num in nums2:
        while stack and stack[-1] < num:
            next_map[stack.pop()] = num
        stack.append(num)

    return [next_map.get(num, -1) for num in nums1]

LC503 - 下一个更大元素 II

这一题要求 nums 中每个元素的下一个更大元素，但是本题数组是循环数组。这一题的解法实际上只要做两个处理：

让循环范围扩大确保每个元素都判断一次是否是下一个元素
然后让下标定位时取余即可

def nextGreaterElements(self, nums: list[int]) -> list[int]:
    n = len(nums)
    ans = [-1] * n
    stack = []  # 存下标
    for i in range(2 * n):
        x = nums[i % n]
        while stack and nums[stack[-1]] < x:
            ans[stack.pop()] = x
        # 额外判断是不是第一次遍历，要不要加下标了
        if i < n:
            stack.append(i)
    return ans

LC739 - 每日温度

一道很规整的单调栈题目，存下标，算距离存入。

def dailyTemperatures(self, temperatures: list[int]) -> list[int]:
    n = len(temperatures)
    ans = [0]*n
    st = []
    for i in range(n):
        while st and temperatures[st[-1]]<temperatures[i]:
            idx = st.pop()
            ans[idx] = i - idx
        st.append(i)
    return ans

找左右边界

LC84 - 柱状图中最大的矩形

本质上，也是在寻找左右两侧第一个比当前矩形矮的，然后这时候就可以得出当前矩形能贡献出来的最大矩形。

def largestRectangleArea(self, heights: list[int]) -> int:
    heights = [0] + heights + [0]
    st = []
    max_S = 0
    for i,val in enumerate(heights):
        while st and st[-1][1]>val:
            _,curr_val = st.pop()
            left_idx = st[-1][0]
            right_idx = i
            max_S = max(max_S,(right_idx-left_idx-1)*curr_val)
        st.append((i,val))
    return max_S

LC85 - 最大矩形

这一题，实际上是枚举每一行作为底边，来做多个一维柱状图最大矩形问题。

class Solution:
    def largestRectangleArea(self, heights: list[int]) -> int:
        heights = [0] + heights + [0]
        stack = []
        ans = 0

        for i, h in enumerate(heights):
            while stack and heights[stack[-1]] > h:
                cur_h = heights[stack.pop()]
                left = stack[-1]
                width = i - left - 1
                ans = max(ans, cur_h * width)
            stack.append(i)

        return ans

    def maximalRectangle(self, matrix: list[list[str]]) -> int:
        if not matrix or not matrix[0]:
            return 0

        rows, cols = len(matrix), len(matrix[0])
        heights = [0] * cols
        ans = 0

        for i in range(rows):
            for j in range(cols):
                if matrix[i][j] == '1':
                    heights[j] += 1
                else:
                    # 如果有中断，就不能再计算
                    heights[j] = 0

            ans = max(ans, self.largestRectangleArea(heights))

        return ans

LC901 - 股票价格跨度

设计一个算法收集某些股票的每日报价，并返回该股票当日价格的跨度。当日股票价格的跨度被定义为股票价格小于或等于今天价格的最大连续日数（从今天开始往回数，包括今天）。

这一题和普通“找下一个更大元素”的题有一点不一样。它不是一次性给完整数组，而是数据流在线输入，所以不能等全部输入完再统一求。

思路是维护一个单调递减栈，栈里存 (price, span)。如果当前价格比栈顶大，那么栈顶那一整段跨度都能被当前价格吞掉，于是我们把它们的跨度累加起来。这就是这一题看起来“多了一个累加量”的原因。

class StockSpanner:

    def __init__(self):
        self.stack = []  # (price, span)

    def next(self, price: int) -> int:
        span = 1

        while self.stack and self.stack[-1][0] <= price:
            span += self.stack.pop()[1]

        self.stack.append((price, span))
        return span

单调栈变形

LC853 - 车队

这一题属于“排序 + 单调栈”的变形。把车按位置从左到右排序后，每辆车都有一个到终点的时间 time = (target - pos) / speed。如果后车到终点所需时间小于等于前车，那么它最终一定会追上前车，合并成同一个车队。

所以我们只需要维护一个单调的到达时间栈，能合并的就弹掉，最后栈里剩下的就是车队数量。

def carFleet(self, target: int, position: list[int], speed: list[int]) -> int:
    cars=sorted(zip(position,speed))
    stack=[]
    for pos,spd in cars:
        time=(target-pos)/spd
        while stack and stack[-1]<=time:
            stack.pop()
        stack.append(time)
    return len(stack)

区间贡献问题

LC907 - 子数组的最小值之和

这一题如果直接暴力二重循环弄出所有子数组，会超时。所以必须要转化思路，核心思想是算每个 arr[i] 作为最小值时，能贡献多少个子数组。

实际上，我们依旧要回到单调栈的原本思想，我们要看 arr[i] 左边第一个比它小的位置、右边第一个小于等于它的位置在哪。left[i] = 从 i 往左，最多能选多少个起点；right[i] = 从 i 往右，最多能选多少个终点；那么，arr[i] 的贡献 = arr[i] * left[i] * right[i]。

比如，[3,1,2,4]，3左边没有更小的，所以左侧可选一个起点；右侧第一个小于等于它的是1，所以只能是[3]。而1左侧没有比它更小的，起点可以选3或者1，右侧是没有小于等于它的，可以选1、2、4，一共贡献 123 = 6。

def sumSubarrayMins(self, arr: list[int]) -> int:
    # 思路是对每个数找左、右第一个比它小的。
    # left[i] = 从 i 往左，最多能选多少个起点。换言之，就是找到第一个比它小的，之间的都可以当做起点。
    n = len(arr)
    left = [0] * n 
    st = []
    for i in range(n):
        while st and arr[st[-1]] > arr[i]:
            st.pop()
        # 空栈说明arr[i]已经是最小的
        left[i] = i - st[-1] if st else i + 1
        st.append(i)

    # right[i] = 从 i 往右，最多能选多少个终点。由于左边没有等于，我们知道等于也是可以的，选一侧用等于。
    # 操作几乎和左边对称
    right = [0] * n
    st = []
    for i in range(n-1,-1,-1):
        while st and arr[st[-1]] >= arr[i]:
            st.pop()
        right[i] = st[-1] - i if st else n-i
        st.append(i)

    MOD = 10**9 + 7
    ans = 0
    for i in range(n):
        ans = (ans + arr[i]*left[i]*right[i])%MOD
    return ans

LC2104 - 子数组范围和

返回所有连续子数组最小元素和最大元素差值，在上一题中，我们已经求过了最小值贡献，改一下不等于号方向就可以求最大值贡献了。然后，用最大值贡献-最小值贡献，就是本题的答案。

def subArrayRanges(self, nums: list[int]) -> int:
    n = len(nums)
    left_min = [0] * n
    right_min = [0] * n
    left_max = [0] * n
    right_max = [0] * n
    
    # 开始四遍单调栈求解
    st = []
    for i in range(n):
        while st and nums[st[-1]]>nums[i]:
            st.pop()
        left_min[i] = i - st[-1] if st else i+1
        st.append(i)

    st = []
    for i in range(n):
        while st and nums[st[-1]]<nums[i]:
            st.pop()
        left_max[i] = i - st[-1] if st else i+1
        st.append(i)

    st = []
    for i in range(n-1,-1,-1):
        while st and nums[st[-1]]>=nums[i]:
            st.pop()
        right_min[i] = st[-1] - i if st else n-i
        st.append(i)

    st = []
    for i in range(n-1,-1,-1):
        while st and nums[st[-1]]<=nums[i]:
            st.pop()
        right_max[i] = st[-1] - i if st else n-i
        st.append(i)
    
    # 现在，用最大值贡献-最小值贡献
    ans = [0] * n 
    for i in range(n):
        ans[i] = nums[i]*left_max[i]*right_max[i] - nums[i]*left_min[i]*right_min[i]

    return sum(ans)

本题其实可以细细品味，包含着单调栈的核心思想。

单调栈模板

最常见的三个模板其实可以这样记：

# 1. 正向扫描，当前元素去结算前面的人
stack = []
for i, x in enumerate(nums):
    while stack and nums[stack[-1]] < x:
        idx = stack.pop()
        # 在这里结算 idx 的答案
    stack.append(i)

# 2. 反向扫描，当前元素直接找自己的答案
stack = []
for i in range(len(nums) - 1, -1, -1):
    while stack and stack[-1] <= nums[i]:
        stack.pop()
    ans[i] = stack[-1] if stack else -1
    stack.append(nums[i])

# 3. 左右边界模板
heights = [0] + heights + [0]
stack = []
for i, h in enumerate(heights):
    while stack and heights[stack[-1]] > h:
        cur = stack.pop()
        left = stack[-1]
        width = i - left - 1
        # 在这里结算 cur 的贡献
    stack.append(i)

单调队列：维护滑动窗口最值

单调队列的核心思想

单调队列本质上是 deque + 维护单调性。

和单调栈相比，它最大的不同在于：单调队列往往服务于滑动窗口。所以除了维护单调性，还要解决一个额外问题：

队头这个元素过期了吗？

于是单调队列的经典操作一般有两步：

新元素进来时，从队尾弹出所有“不如它”的元素
窗口左端移动时，判断队头是否已经滑出窗口

所以单调队列最擅长的就是：

滑动窗口最大值 / 最小值
窗口合法性判定
前缀和 + 最优左端点筛选

滑动窗口最值

LC239 - 滑动窗口最大值

这是单调队列最经典的使用题。我们用deque，保持队头始终是当前窗口的最大值，然后每次验证队头是否过期即可。

from collections import deque

def maxSlidingWindow(self, nums: list[int], k: int) -> list[int]:
    q = deque()
    ans = []
    for i,val in enumerate(nums):
        while q and nums[q[-1]] <= val:
            q.pop()
        q.append(i)

        # 判断过期
        if q[0] <= i - k:
            q.popleft()
        
        # 判断是否可以录用
        if i >= k - 1:
            ans.append(nums[q[0]])
        
    return ans

前缀和 + 单调队列

LC862 - 和至少为 K 的最短子数组

给你一个整数数组 nums 和一个整数 k ，找出 nums 中和至少为 k 的最短非空子数组，并返回该子数组的长度。如果不存在这样的子数组，返回 -1 。(子数组连续)

我们知道，要想求任意子数组的和，用前缀和就可以解决。这题不能使用滑动窗口，因为 LC862 里可能有负数。有负数时，窗口右扩后，和不一定变大；左缩后，和也不一定变小，所以普通双指针失效。

构造好前缀和之后，用单调队列维护一批最有希望成为左端点的前缀和下标。为了让和尽量大，我们让最小的前缀和始终保持在队顶，然后遍历的时候每次和当前 pre[i] 做差得到和，大于k之后，将ans更新为较小的坐标长度。

from collections import deque
from itertools import accumulate

def shortestSubarray(self, nums: list[int], k: int) -> int:
    prefix = [0] + list(accumulate(nums))
    q = deque()
    n = len(nums)
    ans = n+1
    for i in range(n+1):
        while q and prefix[i] - prefix[q[0]] >= k:
            ans = min(ans,i-q.popleft())

        while q and prefix[q[-1]]>=prefix[i]:
            q.pop()
        q.append(i)
    return ans if ans<=n else -1

这一题代码虽然很短，但思路转化并不直观，所以一定要把“前缀和 + 单调队列”的套路记住。

LC1438 - 绝对差不超过限制的最长连续子数组

依旧是滑动窗口最值，这次既要最大又要最小，那么好，用两个队列就可以满足。

这一题包含比较通用的滑动窗口最值求解，请仔细阅读：

def longestSubarray(self, nums: list[int], limit: int) -> int:
    max_q = deque()
    min_q = deque()
    left = 0
    ans = 0

    for right, x in enumerate(nums):
        while max_q and nums[max_q[-1]] <= x:
            max_q.pop()
        max_q.append(right)

        while min_q and nums[min_q[-1]] >= x:
            min_q.pop()
        min_q.append(right)

        # 过期机制
        while nums[max_q[0]] - nums[min_q[0]] > limit:
            if max_q[0] == left:
                max_q.popleft()
            if min_q[0] == left:
                min_q.popleft()
            left += 1

        ans = max(ans, right - left + 1)

    return ans

单调队列模板

单调队列最常见的模板其实就是下面这版：

from collections import deque

q = deque()  # 存下标

for i, x in enumerate(nums):
    while q and nums[q[-1]] <= x:
        q.pop()
    q.append(i)

    if q[0] <= i - k:
        q.popleft()

    if i >= k - 1:
        ans.append(nums[q[0]])

如果同时需要维护最大值和最小值，就开两个队列：

一个单调递减，维护最大值
一个单调递增，维护最小值

而如果题目是 LC862 这种“前缀和 + 最短子数组”，那么队列里存的就不是原数组元素，而是前缀和下标。这一点要单独记。

优先队列：动态维护最值

优先队列的核心思想

优先队列的题，核心味道其实非常明显：

候选集会动态变化，但每一步只关心其中的一个最值。

这时就很容易想到堆。

常见信号包括：

一边扫描，一边动态加入候选
每次只需要当前最大 / 当前最小
Top K
多路归并
数据流维护第 k 大 / 中位数

在 Python 里，刷题时通常直接用 heapq：

默认是小根堆
想要大根堆，就存相反数

Top K 问题

LC215 - 数组中的第 K 个最大元素

Top K问题，可以通过快速选择算法来解决。我们这里先复习一下优化重复元素性能的三路快选。

import random

def findKthLargest(self, nums: list[int], k: int) -> int:
    target = len(nums) - k

    def partition(left: int, right: int) -> tuple[int, int]:
        pivot_idx = random.randint(left, right)
        pivot = nums[pivot_idx]

        nums[pivot_idx], nums[right] = nums[right], nums[pivot_idx]

        lt = left
        i = left
        gt = right

        while i <= gt:
            if nums[i] < pivot:
                nums[lt], nums[i] = nums[i], nums[lt]
                lt += 1
                i += 1
            elif nums[i] > pivot:
                nums[i], nums[gt] = nums[gt], nums[i]
                gt -= 1
            else:
                i += 1

        return lt, gt

    left, right = 0, len(nums) - 1

    while left <= right:
        lt, gt = partition(left, right)

        if lt <= target <= gt:
            return nums[target]
        elif target < lt:
            right = lt - 1
        else:
            left = gt + 1

然后，我们就进入这一题的优先队列写法。一般优先队列题优先用heapq即可，堆就是优先队列的常见实现方式。我们通过取反模拟大根堆，然后弹出k-1个之后得到第k个最大元素。

import heapq

def findKthLargest(self, nums: list[int], k: int) -> int:
    pq = [-x for x in nums]
    heapq.heapify(pq)

    for _ in range(k - 1):
        heapq.heappop(pq)

    return -heapq.heappop(pq)

另一种做法是固定大小的小根堆，这样会一直保留最小的k个，如果新元素比堆顶大，就换堆顶，到最后堆顶就会变成最大的k个中的最小的，也就是第k个最大元素。

import heapq

def findKthLargest(self, nums: list[int], k: int) -> int:
    pq = []
    for num in nums:
        heapq.heappush(pq,num)
        if len(pq)>k:
            heapq.heappop(pq)
    return pq[0]

LC347 - 前 K 个高频元素

这一题最符合直觉的做法是哈希表+小根堆，我们维持大小为k的小根堆，遇到大的就替换掉堆顶，最终就会剩余前k个高频元素。

import heapq
from collections import Counter

def topKFrequent(self, nums: list[int], k: int) -> list[int]:
    freq_map = Counter(nums)
    pq = []
    for num, freq in freq_map.items():
        heapq.heappush(pq, (freq, num))
        if len(pq) > k:
            heapq.heappop(pq)
    
    # 此时只剩下了频率最高的K个元组
    ans = [x[1] for x in pq]
    return ans

LC703 - 数据流中的第 K 大元素

import heapq

class KthLargest:

    def __init__(self, k: int, nums: list[int]):
        self.pq = []
        self.k = k
        for num in nums:
            self.add(num)

    def add(self, val: int) -> int:
        heapq.heappush(self.pq,val)
        if len(self.pq)>self.k:
            heapq.heappop(self.pq)
        return self.pq[0]

合并多个有序结构

LC23 - 合并 K 个升序链表

之前合并k个升序链表是通过分治归并法解决，这里可以使用堆来解决这个问题。我们将所有链表当前节点放在最小堆里，每次取出堆顶构造。

def mergeKLists(self, lists: list[ListNode]) -> ListNode:
    pq = []

    for i, head in enumerate(lists):
        if head:
            heapq.heappush(pq, (head.val, i, head))

    dummy = ListNode()
    p = dummy

    while pq:
        _, i, node = heapq.heappop(pq)
        p.next = node
        p = p.next

        if node.next:
            heapq.heappush(pq, (node.next.val, i, node.next))

    return dummy.next

需要注意的是，我们必须要防止 Python 直接比较 node，因为链表节点本身不能比较大小。所以我们要存 node.val 和 node 的元组。但是题目中 node.val 还是可能会相等，然后顺位又去比较 node，所以我们还要在中间塞一个 idx，来保证永远比不到 node。

LC373 - 查找和最小的 K 对数字

最简单的写法就是二重循环全部入大小k的大根堆，每次超限踢出最大的，剩下的就是最小的K个。

import heapq

def kSmallestPairs(self, nums1: list[int], nums2: list[int], k: int) -> list[list[int]]:
    pq = []

    for num1 in nums1:
        for num2 in nums2:
            total = num1 + num2
            heapq.heappush(pq, (-total, num1, num2))
            if len(pq) > k:
                heapq.heappop(pq)

    return [[a, b] for _, a, b in pq]

但是，这么写显然丢失了题目中的重要信息，即有序。假设nums1和nums2都有三个，我们可以写出3x3的矩阵，每一行都可以看成一个有序链表，比如1、7、11；2、4、6：

        2   4   6
1   ->  3   5   7
7   ->  9  11  13
11  -> 13  15  17

显然，我们就可以套用 LC23 的思路，先把每一行第一个数字入堆，然后弹出当前最小对，再继续看这一行的下一个，直到取满 k 个。

import heapq

def kSmallestPairs(self, nums1: list[int], nums2: list[int], k: int) -> list[list[int]]:
    if not nums1 or not nums2 or k == 0:
        return []

    pq = []
    ans = []
    # 如果len(nums1)甚至不如k，那么后面的不用看了
    for i in range(min(k, len(nums1))):
        heapq.heappush(pq,(nums1[i]+nums2[0],i,0))

    while pq and len(ans)<k:
        _,i,j = heapq.heappop(pq)
        ans.append([nums1[i],nums2[j]])

        if j+1<len(nums2):
            heapq.heappush(pq,(nums1[i]+nums2[j+1],i,j+1))

    return ans

数据流与对顶堆

LC295 - 数据流的中位数

注意，没说输入的数据是按顺序的，虽然样例是按顺序的。这一题的解法是用两个堆，天然拿出左半边最大的和右半边做小的，注意做好奇偶处理。

import heapq

class MedianFinder:

    def __init__(self):
        self.max_heap = []
        self.min_heap = []

    def addNum(self, num: int) -> None:
        # 偏小的最大堆：max_heap；偏大的最小堆：min_heap
        heapq.heappush(self.max_heap,-num)
        lower_biggest = -heapq.heappop(self.max_heap)
        heapq.heappush(self.min_heap,lower_biggest)
        # 要始终满足 len(max_heap) >= len(min_heap)最多只多 1 个
        # 关键点就在于来回倒腾的往往不是一个数，但是维持了数量关系
        if len(self.min_heap) > len(self.max_heap):
            upper_smallest = heapq.heappop(self.min_heap)
            heapq.heappush(self.max_heap,-upper_smallest)


    def findMedian(self) -> float:
        if len(self.max_heap) > len(self.min_heap):
            return -self.max_heap[0]
        return (-self.max_heap[0]+self.min_heap[0]) / 2.0

贪心 + 优先队列

有时候，我们需要一边扫描，一边动态加入候选，并且反复取当前最大/最小。

LC253 - 会议室 II

堆维护“现在占着资源的人”

给一个安排时间的数组，每个会议时间包含开始和结束，返回所需会议室最小数量，也就是： [[0,30],[5,10],[15,20]] -> 2。

这一题，是通过最小堆+优先队列实现的，堆里的元素表示要占用到哪个时间点。这样，新元素如果大于最小堆的最早结束时间，说明可以重复使用这个会议室，我们移除堆顶然后入堆即可：

import heapq

def minMeetingRooms(intervals): 
    if not intervals:
        return 0
    rooms = []
    intervals.sort(key = lambda x:x[0])
    heapq.heappush(rooms,intervals[0][1])

    for i in intervals[1:]:
        if i[0]>=rooms[0]:
            heapq.heappop(rooms)
        
        heapq.heappush(rooms,i[1])

    return len(rooms)

LC871 - 最低加油次数

堆维护“过去留下来的备选资源”

这一题的标准思路是，我们维持一个大根堆，用fuel表示最远能到哪里，按顺序扫描所有加油站，把所有”已经能到达的站“的油量放入一个大根堆。如果当前的油不够去下一站/终点，就从大根堆里面拿一个最大的油补上，每弹一次堆，表示加油一次。

所以，这一题实际上是贪心用最大油量加，从而让加油量尽量少。为了实现这个贪心借助了堆结构。

def minRefuelStops(self, target: int, startFuel: int, stations: list[list[int]]) -> int:
    pq = []
    fuel = startFuel
    i = 0
    n = len(stations)
    ans = 0
    while fuel < target:
        while i < n and stations[i][0] <= fuel:
            heapq.heappush(pq, -stations[i][1])
            i += 1
        if not pq:
            return -1
        fuel += -heapq.heappop(pq)
        ans += 1
    return ans

Python heapq 使用要点

这里把 Python 里最常用的几个点单独记一下：

import heapq

pq = []
heapq.heappush(pq, 3)
heapq.heappush(pq, 1)
heapq.heappush(pq, 2)
top = pq[0]              # 堆顶最小值
x = heapq.heappop(pq)    # 弹出最小值

几个高频注意点：

heapq 默认是小根堆
heapq.heapify(nums) 是原地建堆，返回值是 None
想模拟大根堆，通常存相反数
处理链表节点、对象、元组时，要注意比较规则
如果元组前几位可能相等，后面又是不可比较对象，需要补一个 idx

一句话记忆：

Python 里优先队列几乎就是 list + heapq。

栈与队列设计题

栈的设计题

LC155 - 最小栈

核心是“普通栈存值 + 辅助栈同步最小值”。难点不在 API，而在于要不要让 min_stack 和主栈等长。本文前面用的是最稳妥的等长写法。

LC225 - 用队列实现栈

核心是让队列模拟“最后进来的先出去”。最稳定的写法是双队列倒腾，把最后一个元素单独留下来当栈顶。

设计题的核心不是套模板，而是想清楚“我要额外维护什么信息”。

这两题分别对应：

LC155：普通栈 + 同步最小值栈
LC225：用两个队列模拟“最后进入的先出来”

队列的设计题

LC232 - 用栈实现队列

核心是让一个栈负责输入、另一个栈负责输出。只有在输出栈为空时，才把输入栈整体倒过去。

LC622 - 设计循环队列

核心是循环数组 + 取模。建议统一采用“浪费一个位置”的写法，这样空和满的判断最清楚。

LC641 - 设计循环双端队列

比 LC622 多的只是“两头都能操作”，本质仍然是循环数组和指针含义的统一。

队列设计题常见就三类：

普通队列：先进先出
循环队列：用取模节省空间
双端队列：两头都能插入和删除

这类题一定要先把指针含义定死，不然特别容易写着写着把自己绕晕。最推荐的定义方式是：

front 指向队头元素
rear 指向队尾后一个空位
空队列：front == rear
满队列：浪费一个位置，判断 (rear + 1) % capacity == front

栈与队列题目的分类判断

一看到括号匹配、消消乐、撤销操作，就想栈

因为这类题都在维护“最近一个还没处理完的状态”。括号要和最近的左括号配对，消消乐要和最近的字符比，撤销也总是撤销最近一步。

一看到层序遍历、按顺序处理、最短步数，就想队列

因为队列天然按顺序推进，而 BFS 又天然按层扩散。凡是“从起点最少几步到终点”“一轮一轮蔓延”的题目，优先就该想到队列。

一看到下一个更大元素、找左右边界，就想单调栈

这类题本质都在找“第一个打破单调性的位置”。只要当前元素一来，前面一批元素的答案就能被结算，这就是单调栈最典型的信号。

一看到滑动窗口最大值、窗口最小值，就想单调队列

因为窗口在移动，而我们又需要实时拿到窗口最值。暴力 max/min 会超时，于是就要用单调队列维护窗口内部的有效候选。

一看到动态最值、Top K、多路归并，就想优先队列

堆的关键词不是“排序”，而是“动态维护”。候选集一直在变，但每一步只要其中一个最值，这时优先队列就很自然。

栈与队列常见模板

普通栈模板

stack = []

for x in nums:
    stack.append(x)

while stack:
    x = stack.pop()

普通队列模板

from collections import deque

q = deque([start])

while q:
    cur = q.popleft()
    for nxt in neighbors(cur):
        q.append(nxt)

双端队列模板

from collections import deque

dq = deque()
dq.append(x)
dq.appendleft(y)
dq.pop()
dq.popleft()

括号匹配模板

pairs = {')': '(', ']': '[', '}': '{'}
stack = []

for ch in s:
    if ch not in pairs:
        stack.append(ch)
    else:
        if not stack or stack.pop() != pairs[ch]:
            return False

return not stack

单调栈模板

stack = []

for i, x in enumerate(nums):
    while stack and nums[stack[-1]] < x:
        idx = stack.pop()
        # 结算 idx
    stack.append(i)

单调队列模板

from collections import deque

q = deque()

for i, x in enumerate(nums):
    while q and nums[q[-1]] <= x:
        q.pop()
    q.append(i)

    if q[0] <= i - k:
        q.popleft()

优先队列模板

import heapq

pq = []

for x in nums:
    heapq.heappush(pq, x)

while pq:
    x = heapq.heappop(pq)

栈与队列问题总结

这一篇内容看起来很多，但其实核心只有几句话：

栈解决最近、嵌套、回退
队列解决顺序推进、层序扩散、最短步数
单调栈解决“第一个更大/更小”和边界
单调队列解决滑动窗口最值
优先队列解决动态候选集里的最值问题

如果要把整篇再压缩成一句话，那就是：

不要先背题，而是先判断题目需要维护哪一种顺序。

当你开始能从“维护顺序”的角度看题时，栈、队列、单调栈、单调队列、优先队列这几个专题就会越来越像一家人，而不是零散的很多模板。

算法总结-递归

Sat, 21 Mar 2026 00:00:00 GMT

递归的核心理解

什么是递归

递归问题是指子问题和最终问题相似时，且子问题容易解决时，可以先递到子问题，然后归到原问题来求解。

更直白地说，递归就是“函数自己调用自己”。但是刷题里真正重要的不是这个定义，而是要能看出来：当前问题能不能拆成一个或多个和原问题形式相同、规模更小的问题。

比如求链表长度：

def length(head):
    if not head:
        return 0
    return 1 + length(head.next)

这个函数的意思不是“我脑子里一层一层模拟调用栈”，而是：

当前链表长度 = 1 + 后面链表的长度

所以写递归最重要的习惯是：相信递归函数已经能解决子问题。我们只需要想清楚当前层要做什么，以及什么时候停止。

递归三要素

递归一般可以拆成三个问题：

1. 递归函数的定义是什么？
2. 递归出口是什么？
3. 当前层如何利用子问题结果？

第一点最重要。很多递归写乱，本质上不是不会写代码，而是一开始没有定义清楚函数到底返回什么、负责什么。

比如二叉树最大深度：

def maxDepth(root):
    if not root:
        return 0
    return max(maxDepth(root.left), maxDepth(root.right)) + 1

这里递归函数的定义是：

maxDepth(root) 返回以 root 为根节点的树的最大深度

有了这个定义后，代码就自然了：

当前树最大深度 = 左子树最大深度 和 右子树最大深度 的较大值 + 1

所以以后写递归时，可以先写一句中文定义：

这个函数接收什么？
这个函数返回什么？
这个函数处理的是哪一段/哪一棵树/哪一个状态？

递归函数的定义方式

递归函数通常有几种定义方式。

第一种，定义为“处理某个结构”：

def dfs(root):
    # 处理以 root 为根的整棵树

二叉树题最常见，比如最大深度、翻转二叉树、判断相同的树。

第二种，定义为“处理某个区间”：

def dfs(left, right):
    # 处理 [left, right] 这一段

分治题、构造树、归并排序、快排经常这样写。

第三种，定义为“从某个位置开始处理”：

def dfs(index):
    # 处理从 index 开始的后续问题

组合、切割、字符串匹配、动态规划递归版经常这样写。

第四种，定义为“当前路径/当前选择状态”：

def backtrack(path, used):
    # 当前已经选了 path，used 表示哪些元素用过

排列、N皇后、数独、分桶问题经常这样写。

第五种，定义为“两个对象之间的关系”：

def dfs(p, q):
    # 判断 p 和 q 之间是否满足某种关系

比如对称二叉树、相同的树、最长公共子序列、编辑距离。

递归函数定义得越准，后面的出口和递推关系就越容易写。

递归出口

递归出口就是最小子问题，也就是不用再继续拆的问题。没有递归出口，就会无限递归。

常见出口有几类。

结构为空：

if not root:
    return 0

区间非法：

if left > right:
    return None

位置到头：

if index == len(nums):
    return

目标达成：

if target == 0:
    ans.append(path[:])
    return

状态已经算过：

if state in memo:
    return memo[state]

递归出口要和函数定义保持一致。比如函数定义是“返回链表长度”，空链表就应该返回 0；如果函数定义是“返回是否存在路径”，走到目标就应该返回 True。

这里最容易错的是出口返回值。出口不是随便 return，而是要返回一个能被上一层正确使用的值。

递归返回值

递归函数可以有返回值，也可以没有返回值。

有返回值时，通常是子问题的答案要交给上一层使用：

def maxDepth(root):
    if not root:
        return 0
    left = maxDepth(root.left)
    right = maxDepth(root.right)
    return max(left, right) + 1

没有返回值时，通常是靠外部变量或者参数里的 path 收集答案：

def backtrack(start):
    ans.append(path[:])
    for i in range(start, len(nums)):
        path.append(nums[i])
        backtrack(i + 1)
        path.pop()

所以可以这样判断：

如果当前层需要子问题结果，就让递归函数 return。
如果只是枚举所有可能并收集答案，可以不 return，用 path 和 ans。

当然，回溯也可以有返回值，比如搜索是否存在一条路径时，找到后直接返回 True，可以提前剪枝。

递归前序位置与后序位置

递归里经常说前序位置、后序位置，其实就是“递归调用前做事”还是“递归调用后做事”。

def dfs(root):
    if not root:
        return

    # 前序位置：刚进入当前节点
    dfs(root.left)
    # 中序位置：左子树处理完，右子树还没处理
    dfs(root.right)
    # 后序位置：左右子树都处理完

前序位置适合自顶向下传递信息，比如当前路径和、当前深度、当前选择。

path.append(root.val)
dfs(root.left)
dfs(root.right)
path.pop()

后序位置适合自底向上汇总信息，比如树的高度、节点数量、是否平衡、最大路径和。

left = dfs(root.left)
right = dfs(root.right)
return max(left, right) + 1

可以简单记：

要把信息带下去，用前序。
要从子树收结果，用后序。

递归调用栈

递归调用不是“魔法”，它本质上是系统帮我们维护了一个调用栈。每调用一次函数，就会把当前函数的局部变量、执行位置、参数保存起来，等子函数返回后再继续执行。

比如：

def f(n):
    if n == 0:
        return
    print("before", n)
    f(n - 1)
    print("after", n)

调用 f(3) 的输出是：

before 3
before 2
before 1
after 1
after 2
after 3

这就是“递”和“归”：

递：一路进入更小的问题
归：从最小问题开始一层一层返回

所以很多题不建议一开始就把每一层调用全部脑补完，这样很容易晕。更好的方式是先相信函数定义，再看当前层如何组合答案。

递归和循环的关系

递归和循环都能表达重复过程。

循环更适合线性、明确次数的问题：

for i in range(n):
    ...

递归更适合天然有层级结构、分支结构的问题：

dfs(root.left)
dfs(root.right)

比如遍历数组，用循环更自然；遍历二叉树，用递归更自然。

从本质上说，递归可以转成循环，只是需要我们自己维护栈：

stack = [root]
while stack:
    node = stack.pop()
    ...

而递归就是系统帮我们维护这件事。所以递归代码通常更短、更贴合问题结构，但代价是会消耗调用栈空间，数据规模太大时可能爆栈。

递归、分治、回溯、动态规划的区别

这几个概念很容易混在一起。我的理解是：递归是一种写法，分治、回溯、动态规划是几种不同的问题思想，它们都可以用递归来实现。

递归：

函数自己调用自己。

分治：

把一个大问题拆成几个互相独立的小问题，分别解决后合并。

典型例子是归并排序：

排序左半边 -> 排序右半边 -> 合并两个有序数组

回溯：

在一棵选择树上做选择，走不通就撤销选择，换下一条路。

典型例子是全排列、组合、N皇后。

动态规划：

有重复子问题，并且可以通过保存子问题结果避免重复计算。

递归版动态规划通常叫记忆化搜索。

可以用一个判断方式区分：

子问题互相独立，最后合并：分治。
需要枚举选择，选完还要撤销：回溯。
子问题大量重复，需要缓存：动态规划。
只是顺着结构自然往下走：普通递归。

比如二叉树最大深度，是普通结构递归；归并排序是分治递归；全排列是回溯递归；斐波那契加 memo 是记忆化搜索。

结构递归：顺着数据结构往下走

链表递归

LC206 - 反转链表

正常而言，这一题可以使用简单的三指针翻转解决，但是既然本专栏是递归专题，肯定是用递归的方法来做。我们思考，如果我们需要翻转的链表，实际上就是需要一个函数每次返回翻转后的链表的头结点。这样，我们就能定义一个递归函数，自己调用自己来完成任务。

# 定义函数为返回翻转后的链表的头结点
def reverseList(self, head: ListNode) -> ListNode:
    if not head or not head.next:
        return head
    new_head = self.reverseList(head.next)
    # 原本的head.next现在在末尾
    head.next.next = head
    # 断开原本链接防止成环
    head.next = None
    return new_head

这道题的递归思路稍微有点绕，而且时空也不优秀，但是麻雀虽小，武藏巨拳。

LC24 - 两两交换链表中的节点

在双指针专题中，我们写的就是递归写法，也是这类题目最简单的写法：

class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

def swapPairs(self, head: ListNode) -> ListNode:
    if not head or not head.next:
        return head
    curr = head
    prev = None
    for _ in range(2):
        curr.next, prev, curr = prev,curr, curr.next
    head.next = swapPairs(curr)
    return prev

LC25 - K个一组翻转链表

class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

def reverseKGroup(self, head: ListNode,k:int) -> ListNode:
    # 如果剩余少于k个直接退出
    p = head
    for _ in range(k):
        if not p:
            return head
        p = p.next

    curr = head
    prev = None
    for _ in range(k):
        curr.next, prev, curr = prev,curr, curr.next
    head.next = reverseKGroup(curr,k)
    return prev

LC21 - 合并两个有序链表

双指针合并自然是最简单的方式，但是，我们也可以利用递归结构来代替指针移动。

def mergeTwoLists(list1: ListNode, list2: ListNode) -> ListNode:
    if not list1:
        return list2
    if not list2:
        return list1

    if list1.val <= list2.val:
        list1.next = mergeTwoLists(list1.next, list2)
        return list1
    else:
        list2.next = mergeTwoLists(list1, list2.next)
        return list2

双指针：自己维护 p，一步步接节点。递归：每一层只决定当前头节点是谁，后面的合并交给递归。

不过这样做的话，空间复杂度更差了。一般两个链表的合并，我们还是直接用双指针。

LC23 - 合并K个升序链表

涉及到了k个升序链表合并，就必须要用递归去做了（其实也可以用堆）。为了让递归树尽量平衡，我们应该每次在中间断开拆解子问题。当只有两个链表的时候，自然而然使用合并两个升序链表。

class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

def merge2Lists(list1:ListNode,list2:ListNode)->ListNode:
    dummy = ListNode()
    p = dummy
    while list1 and list2:
        if list1.val<=list2.val:
            p.next = list1
            list1 = list1.next
        else:
            p.next = list2
            list2 = list2.next
        p = p.next
    p.next = list1 if list1 else list2
    return dummy.next

# 合并k个有序链表
def mergeKLists(lists:ListNode[ListNode])->ListNode:
    k = len(lists)
    if k == 0:
        return None
    if k == 1:
        return lists[0]
    if k == 2:
        return merge2Lists(lists[0],lists[1])
    # 大于两个链表开始递归处理
    mid = k//2
    left = mergeKLists(lists[:mid])
    right = mergeKLists(lists[mid:])
    return merge2Lists(left,right)

LC234 - 回文链表

这一题最简单的做法是找中点、（断开）、翻转、判断。但是，也可以使用递归的方式来做。

我们知道，递归可以“反向”访问到链表的元素，因此我的思路是，先递归一路走到链表尾部，然后回来的时候，从后往前访问节点，同时用left从前往后走。如果这个过程left.val和right.val都相等，那就是回文链表。

class ListNode:
    def __init__(self, val=0, next=None):
        self.val = val
        self.next = next

def isPalindrome(self, head: ListNode) -> bool:
    left = head
    def dfs(right:ListNode) -> bool:
        nonlocal left
        if not right:
            return True
        # 这里我们要将最后失败的结果一路传回来，所以不能简单递归dfs(right.next)，还要return一个值
        if not dfs(right.next):
            return False
        # 递归完成，从最后一位往前看
        if left.val != right.val:
            return False
        left = left.next
        return True
    return dfs(head)

这样写的话，空间上更差一点，但是好在不会破坏原本的链表的结构。

二叉树递归

LC104 - 二叉树的最大深度

树本身就是递归定义的，所以很多题目树的题目都可以回归本质用递归做：

def solution(root:TreeNode)->int:
    def dfs(node):
        if not node:
            return 0
        return 1+max(dfs(node.left),dfs(node.right))
    return dfs(root)

LC111 - 二叉树的最小深度

这类问题代表的是多出口的递归，不一定要一直递归到底返回，以为本题要求的答案不一定会到叶子节点才结算。

class TreeNode:
    def __init__(self, val = 0, left = None,right = None):
        self.val = val
        self.left = left
        self.right = right 

def solution(root:TreeNode)->int:
    def dfs(node):
        if not node:
            return 0
        if not node.left and not node.right:
            return 1
        if not node.left:
            return 1+dfs(node.right)
        if not node.right:
            return 1+dfs(node.left)
        return 1+min(dfs(node.left),dfs(node.right))
    return dfs(root)

LC226 - 翻转二叉树

递归返回的时候从下往上调转左右即可：

def invertTree(self, root: TreeNode) -> TreeNode:
    def dfs(node):
        if not node:
            return 
        dfs(node.left)
        dfs(node.right)
        # 递归完成，从后往前翻转
        node.left,node.right = node.right,node.left
    dfs(root)
    return root

LC100 - 相同的树

代表两边同时进行递归判断的题目：

def isSameTree(self, p: TreeNode, q: TreeNode) -> bool:
    def dfs(p,q)->bool:
        if not p and not q:
            return True
        if not p and q:
            return False
        if p and not q:
            return False
        if p.val!=q.val:
            return False
        return dfs(p.left,q.left) and dfs(p.right,q.right)
    return dfs(p,q)

LC101 - 对称二叉树

两个指针同时进行递归判断，一个向左一个向右，值和形状应该始终保持一致。

def isSymmetric(self, root: TreeNode) -> bool:
    def dfs(p,q):
        if not p and not q:
            return True
        if not p and q:
            return False
        if p and not q:
            return False
        if p.val != q.val:
            return False
        return dfs(p.left,q.right) and dfs(p.right,q.left)
    if not root:
        return True
    return dfs(root.left,root.right)

LC543 - 二叉树的直径

本题属于递归维持、返回的量，和题目要求的量不一样。但是递归可以保证一定可以考虑到最优解的情况（实际上就是遍历了），所以我们维持一个全局量来更新，然后dfs即可。

放在本题，直接想二叉树直径很难，可以将问题降级为“从node出发的最大节点数”，只要知道了这个量，任意节点都可以看自己的左右孩子的这个量，来判断需不需要更新最大路径。

def diameterOfBinaryTree(self, root: TreeNode) -> int:
    # 递归函数为从node开始最长的节点数
    max_path = 0
    def dfs(node:TreeNode)->int:
        nonlocal max_path
        if not node:
            return 0
        left_path = dfs(node.left)
        right_path = dfs(node.right)

        # 因为边数等于节点数少1，题目求的是边数，所以不用+1
        max_path = max(max_path,
        left_path+right_path)

        return 1 + max(left_path,right_path)
    
    dfs(root)
    return max_path

LC110 - 平衡二叉树

平衡二叉树是左右高度之差之中不大于1，对所有子树都有这约束。这道题是通过递归传递多种信息的典型。我们通过传递的量不仅要表示子树高度为多少，还要表达子树是否已经不平衡，于是不平衡传递-1，告诉上层也不用继续算了。

def isBalanced(self, root: TreeNode) -> bool:
    def dfs(node: TreeNode) -> int:
        if not node:
            return 0

        left = dfs(node.left)
        if left == -1:
            return -1

        right = dfs(node.right)
        if right == -1:
            return -1

        if abs(left - right) > 1:
            return -1
        # 记录左右最大高度
        return max(left, right) + 1

    return dfs(root) != -1

LC236 - 二叉树的最近公共祖先

同样是通过递归传递信息，这题需要传递的信息是“是否找到p/q”。如果找到了，就要返回自身。如果没找到，就不要返回。

def lowestCommonAncestor(self, root: TreeNode, p: TreeNode, q: TreeNode) -> TreeNode:
    if not root or root == p or root == q:
        return root
    left = self.lowestCommonAncestor(root.left,p,q)
    right = self.lowestCommonAncestor(root.right,p,q)

    # 如果都取到了非空值，就找到了
    if left and right:
        return root
    # 否则只上交一边
    return left if left else right

LC235 - 二叉搜索树的最近公共祖先

上一题的逻辑适用于所有树的情况，这一题既然已经是BST，就可以利用值的性质。即如果p、q都是左子树，则答案一定在左边；反之一定在右边；如果一左一右，则root就是答案。

def lowestCommonAncestor(self, root: TreeNode, p: TreeNode, q: TreeNode) -> TreeNode:
    if p.val < root.val and q.val < root.val:
        return self.lowestCommonAncestor(root.left, p, q)

    if p.val > root.val and q.val > root.val:
        return self.lowestCommonAncestor(root.right, p, q)
    # 如果一左一右，则root就是答案
    return root

二叉搜索树递归

LC98 - 验证二叉搜索树

需要注意的是，BST是全局性质，因此递归过程中要维持一个上下界。

def isValidBST(self, root: TreeNode) -> bool:
    def dfs(lo, hi, node):
        if not node:
            return True
        if not lo < node.val < hi:
            return False
        return dfs(lo, min(hi, node.val), node.left) and dfs(max(lo, node.val), hi, node.right)

    return dfs(float('-inf'), float('inf'), root)

LC700 - 二叉搜索树中的搜索

正常的思路，注意递归的分支和返回即可。

def searchBST(self, root: TreeNode, val: int) -> TreeNode:
    def dfs(node) -> TreeNode:
        if not node:
            return None
        if node.val == val:
            return node
        elif node.val < val:
            return dfs(node.right)
        else:
            return dfs(node.left)
    return dfs(root)

LC701 - 二叉搜索树中的插入操作

带条件的递归，我们根据 BST 的大小关系一路递归到空位置，在空位置创建新节点；回溯时把插入后的子树逐层接回原树，最后返回根节点。

说白了，这是一题修改子树的递归题，而不是以前那样的找结果的递归题，所以感觉上可能有点稍微的差距，倒是和链表有点相似，就是返回修改过的部分。

def insertIntoBST(self, root: TreeNode, val: int) -> TreeNode:
    def dfs(node):
        if not node:
            return TreeNode(val)
        # 根据值的位置选择要调整的半边
        if node.val < val:
            node.right = dfs(node.right)
        else:
            node.left = dfs(node.left)
        return node
    
    return dfs(root)

LC450 - 删除二叉搜索树中的节点

和上一题一样，需要调整子树。

def deleteNode(self, root: TreeNode, key: int) -> TreeNode:
    def dfs(node):
        if not node:
            return None

        # 找到需要调整的半边
        if key < node.val:
            node.left = dfs(node.left)
            return node

        if key > node.val:
            node.right = dfs(node.right)
            return node

        # 找到要删除的节点
        if not node.left:
            return node.right

        if not node.right:
            return node.left

        # 左右子树都存在：右子树顶上来，左子树接到右子树最小节点下面
        p = node.right
        while p.left:
            p = p.left
        p.left = node.left

        return node.right

    return dfs(root)

LC230 - 二叉搜索树中第K小的元素

直接中序遍历即可：

def kthSmallest(self, root: TreeNode, k: int) -> int:
    ans = None
    def dfs(node):
        nonlocal k,ans
        if not node or ans is not None:
            return
        dfs(node.left)
        k-=1
        if k==0:
            ans = node.val
            return
        dfs(node.right)
    dfs(root)
    return ans

N叉树递归

LC559 - N叉树的最大深度

N叉树的结局方法，和二叉树其实差不多，用一个循环解决即可。

def maxDepth(self, root: 'Node') -> int:
    def dfs(node):
        if not node:
            return 0
        max_children = 0
        for i in node.children:
            max_children = max(max_children,dfs(i))
        return 1+max_children
    return dfs(root)

LC589 - N叉树的前序遍历

公式递归。

def preorder(self, root: 'Node') -> list[int]:
    ans = []
    def dfs(node):
        if not node:
            return 
        ans.append(node.val)
        for child in node.children:
            dfs(child)
    dfs(root)
    return ans

LC590 - N叉树的后序遍历

公公又式式

def postorder(self, root: 'Node') -> list[int]:
    ans = []
    def dfs(node):
        if not node:
            return 
        for child in node.children:
            dfs(child)
        ans.append(node.val)
    dfs(root)
    return ans

分治递归：把问题拆成左右两半

分治的基本模板

分治递归的关键，不只是“拆开”，更是“怎么合并”。很多题递归本身不难，难的是左右子问题的答案如何拼回当前问题。

一个标准的分治题，通常都可以先问自己四个问题：

1. 这个问题能不能拆成左右两半？
2. 左半边要返回什么信息？
3. 右半边要返回什么信息？
4. 当前层如何利用左右信息合并答案？

一个基础模板如下：

def divide_and_conquer(left, right):
    # 递归出口
    if left == right:
        return 单个区间的答案

    mid = (left + right) // 2

    left_info = divide_and_conquer(left, mid)
    right_info = divide_and_conquer(mid + 1, right)

    # 合并左右子问题答案
    return merge(left_info, right_info)

如果是排序类题目，merge 真的就是合并有序结果；如果是统计类题目，merge 还会顺手统计贡献；如果是区间最值类题目，merge 则是在左右子区间答案的基础上，再考虑是否存在“跨中点”的情况。

归并排序

LC912 - 排序数组

这一题就是大名鼎鼎的归并排序。每次切半，直到不能切为止，然后组装起来。

def merge(nums1,nums2):
    nums = []
    i, j = 0, 0
    while i<len(nums1) and j<len(nums2):
        if nums1[i]<=nums2[j]:
            nums.append(nums1[i])
            i+=1
        else:
            nums.append(nums2[j])
            j+=1
    nums.extend(nums1[i:] if i<len(nums1) else nums2[j:])
    return nums

def sortArray(nums: list[int]) -> list[int]:
    n = len(nums)
    if n<= 1:
        return nums
    mid = n//2
    left = sortArray(nums[:mid])
    right = sortArray(nums[mid:])
    return merge(left,right)

后面有很多题目会在同一个函数中解决问题，因此我们学着利用python的特性，把分解与归并排序操作放在函数体内的同一个函数merge_sort中，这样更清晰：

def solution(nums:list):
    def merge_sort(left,right):
        # 注意要写退出条件
        if left==right:
            return [nums[left]]
        mid = (left + right) // 2
        left_arr = merge_sort(left,mid)
        right_arr = merge_sort(mid+1,right)

        # 到这里，拆分已经完成，开始归并
        # 归并的过程，就是两个有序数组合并了
        merged = []
        i, j = 0, 0
        while i<len(left_arr) and j<len(right_arr):
            if left_arr[i]<=right_arr[j]:
                merged.append(left_arr[i])
                i += 1
            else:
                merged.append(right_arr[j])
                j += 1
        merged.extend(left_arr[i:])
        merged.extend(right_arr[j:])
        return merged
    
    if not nums:
        return []

    return merge_sort(0,len(nums)-1)

LC148 - 排序链表

同样的归并排序：

def merge(list1:ListNode,list2:ListNode)->ListNode:
    dummy = ListNode()
    p = dummy
    while list1 and list2:
        if list1.val <= list2.val:
            p.next = list1
            list1 = list1.next
        else:
            p.next = list2
            list2 = list2.next
        p = p.next
    p.next = list1 if list1 else list2
    return dummy.next

def sortList(head: ListNode) -> ListNode:
    if not head or not head.next:
        return head
    slow, fast = head, head
    while fast.next and fast.next.next:
        fast = fast.next.next
        slow = slow.next
    second = slow.next
    slow.next = None
    left = sortList(head)
    right = sortList(second)
    return merge(left,right)

同理单函数版：

class ListNode:
    def __init__(self, val = 0, next = None):
        self.val = val
        self.next = next

def solution(head:ListNode):
    def merge_sort(head:ListNode):
        # 只有一个节点或者空的时候不用切了
        if not head or not head.next:
            return head
        fast, slow = head, head
        while fast.next and fast.next.next:
            fast = fast.next.next
            slow = slow.next
        second = slow.next
        slow.next = None
        leftList = merge_sort(head)
        rightList = merge_sort(second)

        # 切分完毕，开始合并
        dummy = ListNode()
        p = dummy
        l, r = leftList, rightList
        while l and r:
            if l.val <= r.val:
                p.next = l
                l = l.next
            else:
                p.next = r
                r = r.next
            p = p.next
        p.next = l if l else r
        return dummy.next
    
    if not head:
        return None
    return merge_sort(head)

LC23 - 合并K个升序链表

跟上一题基本没啥区别，降到两两合并即可：

def merge2Lists(list1:ListNode,list2:ListNode)->ListNode:
    dummy = ListNode()
    p = dummy
    while list1 and list2:
        if list1.val<=list2.val:
            p.next = list1
            list1 = list1.next
        else:
            p.next = list2
            list2 = list2.next
        p = p.next
    p.next = list1 if list1 else list2
    return dummy.next

# 合并k个有序链表
def mergeKLists(lists:ListNode[ListNode])->ListNode:
    k = len(lists)
    if k == 0:
        return None
    if k == 1:
        return lists[0]
    if k == 2:
        return merge2Lists(lists[0],lists[1])
    # 大于两个链表开始递归处理
    mid = k//2
    left = mergeKLists(lists[:mid])
    right = mergeKLists(lists[mid:])
    return merge2Lists(left,right)

快速排序

快速排序是非常经典的板子，大部分自带排序函数底层都是快排实现的，因为其效率很高。

快排模板

快排的本质，就是通过一次 partition，把 pivot 放到最终位置；再递归处理 pivot 左右两边。

先选一个 pivot，常见写法是默认选最后一个元素；用 i 标记“小于等于 pivot 区域”的下一个写入位置；用 j 从左到右扫描；遇到 <= pivot 的数，就和 nums[i] 交换，然后 i 往后走；最后把 pivot 和 nums[i] 交换。

def quick_sort(nums: list[int]) -> list[int]:
    def partition(left: int, right: int) -> int:
        pivot = nums[right]
        i = left

        for j in range(left, right):
            if nums[j] <= pivot:
                nums[i], nums[j] = nums[j], nums[i]
                i += 1

        nums[i], nums[right] = nums[right], nums[i]
        return i

    def dfs(left: int, right: int) -> None:
        if left >= right:
            return

        pivot_idx = partition(left, right)

        dfs(left, pivot_idx - 1)
        dfs(pivot_idx + 1, right)

    dfs(0, len(nums) - 1)
    return nums

LC215 - 数组中的第K个最大元素

利用快速选择的性质，可以在不用完全排序前找到第k大的元素，这个方法也叫快速选择排序，可以在O(n)内解决这个问题。

def findKthLargest(nums: list[int], k: int) -> int:  
    target = len(nums) - k

    # 将最后一个元素作为枢纽，返回正确位置
    def partition(left,right):
        pivot = nums[right]
        i = left
        for j in range(left,right):
            if nums[j] <= pivot:
                nums[i],nums[j] = nums[j], nums[i]
                i += 1
        nums[i], nums[right] = nums[right], nums[i]
        return i


    left = 0
    right = len(nums) - 1

    def quick_select(left: int, right: int) -> int:
        pivot_idx = partition(left, right)

        if pivot_idx == target:
            return nums[pivot_idx]

        if pivot_idx < target:
            return quick_select(pivot_idx + 1, right)
        else:
            return quick_select(left, pivot_idx - 1)

    return quick_select(0, len(nums) - 1)

然而，这样写，力扣上会时间超限。这就很难受了，因为快选平均才能On，最坏要On方。我们有时候会加入随机来保证枢纽随便选：

# 随机选枢纽
random_idx = random.randint(left,right)
nums[random_idx], nums[right] = nums[right], nums[random_idx]
pivot = nums[right]

但是，这样还是会超时。这个写法在有大量重复元素的时候会发生退化。最好的方式，是把<=和else的两路划分，变成三路划分，如下：

import random

def findKthLargest(nums: list[int], k: int) -> int:
    target = k - 1  # 降序后的第 k 大下标

    def quick_select(left: int, right: int) -> int:
        pivot = nums[random.randint(left, right)]

        lt = left      # nums[left:lt] > pivot
        i = left       # nums[lt:i] == pivot
        gt = right     # nums[gt+1:right+1] < pivot

        while i <= gt:
            if nums[i] > pivot:
                nums[lt], nums[i] = nums[i], nums[lt]
                lt += 1
                i += 1
            elif nums[i] < pivot:
                nums[i], nums[gt] = nums[gt], nums[i]
                gt -= 1
            else:
                i += 1

        # 现在：
        # [left, lt - 1] 都 > pivot
        # [lt, gt] 都 == pivot
        # [gt + 1, right] 都 < pivot

        if target < lt:
            return quick_select(left, lt - 1)
        elif target > gt:
            return quick_select(gt + 1, right)
        else:
            return nums[target]

    return quick_select(0, len(nums) - 1)

没错，这就是经典的荷兰国旗问题啊，三路划分让快排可以有效处理很多重复元素，直接把lt到gt之间的元素忽略掉。

二分递归

LC704 - 二分查找

经典二分查找，我们先直接写二分查找的板子：

def search(self, nums: list[int], target: int) -> int:
    # 小于target往右找
    left, right = 0, len(nums)
    while left<right:
        mid = (left+right)//2
        if nums[mid]<target:
            left = mid + 1
        else:
            right = mid
    if left <len(nums) and nums[left] == target:
        return left
    else:
        return -1

但是放在了二分递归的板子里，是为了告诉你，这题也是非常符合递归的题：

def binary_search(nums, target):
    def dfs(left, right):
        if left > right:
            return -1

        mid = (left + right) // 2

        if nums[mid] == target:
            return mid
        elif nums[mid] < target:
            return dfs(mid + 1, right)
        else:
            return dfs(left, mid - 1)

    return dfs(0, len(nums) - 1)

本质上和迭代写法等效，就是去两边找，但是迭代的写法更容易理解，且没有空间消耗，所以尽量写迭代吧。

LC35 - 搜索插入位置

def searchInsert(self, nums: list[int], target: int) -> int:
    left, right = 0, len(nums)
    while left<right:
        mid = (left + right)//2
        if nums[mid]<target:
            left = mid + 1
        else:
            right = mid
    return left

LC69 - x的平方根

def mySqrt(self, x: int) -> int:
    left, right = 0, x
    while left < right:
        mid = (left + right) // 2
        if mid*mid < x:
            left = mid + 1
        else:
            right = mid
    if left*left == x:
        return left
    return left-1

LC50 - Pow(x, n)

这一题，是运用了快速幂的思想，将时间复杂度从O(n)降低到了O(logn)：

def myPow(x: float, n: int) -> float:
    def dfs(n: int) -> float:
        if n == 0:
            return 1

        half = dfs(n // 2)

        if n % 2 == 0:
            return half * half
        else:
            return half * half * x

    if n >= 0:
        return dfs(n)
    else:
        return 1 / dfs(-n)

分治统计

LC169 - 多数元素

本题属于答案一定在左或右，需要二次判断左右给出的信息。

多数元素的最优解法是投票法，我们让相同加票数，不同减票数，最后剩下的候选人就是多数元素。

def majorityElement(self, nums: List[int]) -> int:
    candidate = None
    count = 0

    for num in nums:
        if count == 0:
            candidate = num
            count = 1
        elif num == candidate:
            count += 1
        else:
            count -= 1

    return candidate

不过就当是锻炼思维，这一题也是可以用分治法来做的。分治的思路是递归左半边的多数元素、右半边的多数元素，如果结果相同就直接返回，否则就在当前区间内分别统计它们出现次数，返回次数更多的那个。

def majorityElement(nums: list[int]) -> int:
    def count_in_range(target: int, left: int, right: int) -> int:
        count = 0
        for i in range(left, right + 1):
            if nums[i] == target:
                count += 1
        return count

    def dfs(left: int, right: int) -> int:
        if left == right:
            return nums[left]

        mid = (left + right) // 2

        left_major = dfs(left, mid)
        right_major = dfs(mid + 1, right)

        if left_major == right_major:
            return left_major

        left_count = count_in_range(left_major, left, right)
        right_count = count_in_range(right_major, left, right)

        return left_major if left_count > right_count else right_major

    return dfs(0, len(nums) - 1)

LC53 - 最大子数组和

本题属于答案可能在左、右或跨中点的归并题。

这一题，每个数字要么接着前面的结果继续，要么另起炉灶，所以很容易就能想到动态规划来做。

def maxSubArray(self, nums: list[int]) -> int:
    # 我们让dp[i]表示以i结尾的最大数组和
    n = len(nums)
    dp = [0] * n
    dp[0] = nums[0]
    for i in range(1,n):
        dp[i] = max(dp[i-1]+nums[i],nums[i])
    return max(dp)

这就是最好的方法了，但是，这题同样可以使用分治统计来做。最大子数组只有三种可能，要么最大子数组完全在左半边，要么完全在右半边，要么跨过中点。

def maxSubArray(nums: list[int]) -> int:
    def dfs(left: int, right: int) -> int:
        if left == right:
            return nums[left]

        mid = (left + right) // 2

        left_max = dfs(left, mid)
        right_max = dfs(mid + 1, right)

        left_sum = float("-inf")
        curr = 0
        for i in range(mid, left - 1, -1):
            curr += nums[i]
            left_sum = max(left_sum, curr)

        right_sum = float("-inf")
        curr = 0
        for i in range(mid + 1, right + 1):
            curr += nums[i]
            right_sum = max(right_sum, curr)

        cross_max = left_sum + right_sum

        return max(left_max, right_max, cross_max)

    return dfs(0, len(nums) - 1)

这个方法的空间复杂度logn，时间复杂度nlogn。

然后，这个递归仍然可以优化，让时间变成on。需要返回每个区间返回四个信息：区间总和sum、区间最大后缀和prefix、区间最大后缀和suffix、区间最大子数组和best。

def maxSubArray(nums: list[int]) -> int:
    def dfs(left: int, right: int):
        if left == right:
            x = nums[left]
            return x, x, x, x
            # total, prefix, suffix, best

        mid = (left + right) // 2

        l_sum, l_pre, l_suf, l_best = dfs(left, mid)
        r_sum, r_pre, r_suf, r_best = dfs(mid + 1, right)

        total = l_sum + r_sum
        prefix = max(l_pre, l_sum + r_pre)
        suffix = max(r_suf, r_sum + l_suf)
        best = max(l_best, r_best, l_suf + r_pre)

        return total, prefix, suffix, best

    return dfs(0, len(nums) - 1)[3]

剑指Offer 51 - 数组中的逆序对

在数组中的两个数字，如果前面一个数字大于后面的数字，则这两个数字组成一个逆序对。输入一个数组，求出这个数组中的逆序对的总数。

本题是归并的时候统计贡献，难度适合入门。合并的过程中不断判断left是否超过right，如果超过就是逆序。这里的i、j本身也就是合并有序数组的意思（本身这题就是归并排序的同时去做统计），然后一旦发现left[i]大于right[j]，那么left后面所有的数字都能和right[j]构成逆序对，所以可以直接加个数为len(left)-i。

def reversePairs(nums: list[int]) -> int:
    count = 0

    def merge_sort(arr: list[int]) -> list[int]:
        nonlocal count

        if len(arr) <= 1:
            return arr

        mid = len(arr) // 2
        left = merge_sort(arr[:mid])
        right = merge_sort(arr[mid:])

        merged = []
        i, j = 0, 0

        while i < len(left) and j < len(right):
            if left[i] <= right[j]:
                merged.append(left[i])
                i += 1
            else:
                # left[i] > right[j]
                # left[i:] 都能和 right[j] 构成逆序对
                count += len(left) - i
                merged.append(right[j])
                j += 1

        merged.extend(left[i:])
        merged.extend(right[j:])

        return merged

    merge_sort(nums)
    return count

LC315 - 计算右侧小于当前元素的个数

本题依然属于归并过程中统计贡献题，比上一题难度高一点，核心思想是，在归并排序合并两个有序区间时，统计右半边有多少个数已经被放到当前左半边元素前面。

因为右半边的元素原本就在当前元素右侧。如果某些右半边元素比左半边当前元素小，并且已经先被合并走了，那它们就应该计入答案。

注意为了保留原始下标，我们不能只排序数字，而要排序(value,index)，本题还是归并排序。

def countSmaller(nums: list[int]) -> list[int]:
    n = len(nums)
    ans = [0] * n
    arr = [(num, i) for i, num in enumerate(nums)]

    def merge_sort(left: int, right: int) -> list[tuple[int, int]]:
        if left == right:
            return [arr[left]]

        mid = (left + right) // 2
        left_part = merge_sort(left, mid)
        right_part = merge_sort(mid + 1, right)

        merged = []
        i, j = 0, 0
        right_smaller_count = 0

        while i < len(left_part) and j < len(right_part):
            if right_part[j][0] < left_part[i][0]:
                merged.append(right_part[j])
                # 记录先归并右边的元素个数
                right_smaller_count += 1
                j += 1
            else:
                value, idx = left_part[i]
                # 归并左边时加上已经归并过的右侧的记数
                ans[idx] += right_smaller_count
                merged.append(left_part[i])
                i += 1

        # 归并后续剩余元素

        while i < len(left_part):
            value, idx = left_part[i]
            ans[idx] += right_smaller_count
            merged.append(left_part[i])
            i += 1

        while j < len(right_part):
            merged.append(right_part[j])
            j += 1

        return merged

    if nums:
        merge_sort(0, n - 1)

    return ans

有人可能会疑惑，只在归并左侧元素时更新 ans 足够吗？其实是足够的。只有这种情况会对答案造成贡献：

当前元素在左半边；
更小的元素在右半边；
右半边元素先于它被合并。

而拆分过程中，元素最终会被切成一个一个的元素，不会经过这个判断的，也只有右侧最后一个元素，而这个元素右侧小于它的数字个数必定是0，所以是完全足够的。

选择递归：每一步做选择

子集问题

LC78 - 子集

子集，实际上是一个每个元素可选可不选的问题，我们可以直接进行按位置的dfs。

def subsets(self, nums: list[int]) -> list[list[int]]:
    ans = []
    path = []
    def dfs(i):
        if i == len(nums):
            ans.append(path[:])
            return
        # 选择
        path.append(nums[i])
        dfs(i+1)
        # 回溯
        path.pop()
        # 不选择
        dfs(i+1)
    dfs(0)
    return ans

除了这种递归方法之外，我们还可以遍历数组递归，以开头元素为基准dfs出所有情况。为了不回头看，用start来调整对应的位置即可：

def subsets(self, nums: list[int]) -> list[list[int]]:
    ans = []
    path = []
    def dfs(start):
        ans.append(path[:])
        for i in range(start,len(nums)):
            path.append(nums[i])
            dfs(i+1)
            path.pop()
    return ans

总结一下，子集问题有两种常见递归视角。第一种是选/不选，每个元素都做一次二选一，答案在叶子节点收集。第二种是枚举下一个选择，从 start 开始向后选择一个元素加入 path，答案在每个递归节点收集。对于没有重复元素的 LC78，两种都可以；对于有重复元素的 LC90，for + start 写法更适合同层去重。

LC90 - 子集II

子集II与子集问题只有轻微不同，给的数组nums可能包含重复元素，但解集不能包含重复的子集，所以一个简单的想法，先排序，然后开始暴力求子集，并去重：

def subsetsWithDup(self, nums: list[int]) -> list[list[int]]:
    nums.sort()
    ans = set()
    path = []
    def dfs(i):
        if i == len(nums):
            ans.add(tuple(path[:]))
            return
        # 选择
        path.append(nums[i])
        dfs(i+1)
        # 回溯
        path.pop()
        # 不选择
        dfs(i+1)
    dfs(0)
    return [list(t) for t in ans]

但是，这样写的效率很低，有很多次无用递归。如果学到了NSum对于去重的方法，那么这一题就不会这么生硬去重，我们排序后，对于每次选择同样元素开始dfs的，直接跳过。

组合问题

LC77 - 组合

给定两个整数 n 和 k，返回范围 [1, n] 中所有可能的 k 个数的组合。

换句话说，不重复的1-n，让你选长度为k的子集。这么说就明白了，跟子集问题几乎没区别：

def combine(self, n: int, k: int) -> list[list[int]]:
    path = []
    ans = []
    def dfs(start):
        if len(path) == k:
            ans.append(path[:])
            return
        for i in range(start,n+1):
            path.append(i)
            dfs(i+1)
            path.pop()
    dfs(1)
    return ans

LC39 - 组合总和

给你一个无重复元素的整数数组 candidates 和一个目标整数 target ，找出 candidates 中可以使数字和为目标数 target 的所有不同组合，并以列表形式返回。你可以按任意顺序返回这些组合。

candidates 中的同一个数字可以无限制重复被选取。如果至少一个数字的被选数量不同，则两种组合是不同的。

抓住两点：无重复、可复选。其他的dfs的条件变一下就行。

def combinationSum(self, candidates: list[int], target: int) -> list[list[int]]:
    path = []
    ans = []
    total = 0
    def dfs(start):
        nonlocal total
        if total > target:
            return 
        if total == target:
            ans.append(path[:])
            return
        for i in range(start,len(candidates)):
            path.append(candidates[i])
            total += candidates[i]
            dfs(i)
            path.pop()
            total -= candidates[i]
    dfs(0)
    return ans

这么写是对的，不过效率还是可以继续提升，参考剪枝的方案，我们依旧先排序，然后再判断目前是否已经超过target。如果超过了，都不用继续递归进去。

def combinationSum(self, candidates: list[int], target: int) -> list[list[int]]:
    candidates.sort()
    path = []
    ans = []

    def dfs(start: int, total: int):
        if total == target:
            ans.append(path[:])
            return

        for i in range(start, len(candidates)):
            if total + candidates[i] > target:
                break

            path.append(candidates[i])
            dfs(i, total + candidates[i])
            path.pop()

    dfs(0, 0)
    return ans

LC40 - 组合总和II

组合总和II和I相比，多了每个数字仅能使用一次，然后少了数字不重复。因此，我们要对重复元素进行剪枝：

def combinationSum2(self, candidates: list[int], target: int) -> list[list[int]]:
    candidates.sort()
    path = []
    ans = []
    def dfs(start,total):
        if total == target:
            ans.append(path[:])
            return
        for i in range(start,len(candidates)):
            if i>start and candidates[i] == candidates[i-1]:
                continue
            if total + candidates[i] > target:
                break
            path.append(candidates[i]) 
            dfs(i+1,total+candidates[i])
            path.pop()
    dfs(0,0)
    return ans

这里进行了两种剪枝，continue那里是去重剪枝，虽然这个数不能选，但是后面的可能可以选；而break是超过目标剪枝，因为已经排序完成了，如果超过target，后面肯定不能选了，直接break掉就行。

LC216 - 组合总和III

找出所有相加之和为 n 的 k 个数的组合，且满足下列条件：

只使用数字1到9
每个数字最多使用一次返回所有可能的有效组合的列表。该列表不能包含相同的组合两次，组合可以以任何顺序返回。

翻译一下，用1-9（没有重复元素），不能重复用。其实很简单：

def combinationSum3(self, k: int, n: int) -> list[list[int]]:
    path = []
    ans = []
    def dfs(start,total):
        if total == n and len(path)==k:
            ans.append(path[:])
        for i in range(start,10):
            if total+i>n:
                break
            path.append(i)
            dfs(i+1,total+i)
            path.pop()
    dfs(1,0)
    return ans

排列问题

LC46 - 全排列

全排列和子集问题的差距在于，可以回头选元素了。所以也不用维护start，每次都从头找。但是要额外维持一个seen，防止复选。

def permute(self, nums: list[int]) -> list[list[int]]:
    n = len(nums)
    seen = [False]*n
    path = []
    ans = []
    def dfs():
        if len(path) == n:
            ans.append(path[:])
            return
        
        for i in range(n):
            if seen[i]:
                continue
            seen[i] = True
            path.append(nums[i])
            dfs()
            path.pop()
            seen[i] = False
    dfs()
    return ans

LC47 - 全排列II

给定一个可包含重复数字的序列 nums ，按任意顺序返回所有不重复的全排列。

也就是说，我们依旧是要进行去重了。但是，每一层都要从头扫，因为任意没用过的数都可能被选，所以我们不能能用start去重了，要改一下思路。

于是我们利用used去重，如果i-1的位置没有被使用，且i位置和i-1位置数字一样，那么这个数字也不能先用 -- 换句话说，就是相同数字之间必须保持按原本顺序使用！所以就不会出现颠倒的两种情况。

def permuteUnique(self, nums: list[int]) -> list[list[int]]:
    nums.sort()
    ans = []
    path = []
    used = [False] * len(nums)

    def dfs():
        if len(path) == len(nums):
            ans.append(path[:])
            return

        for i in range(len(nums)):
            if used[i]:
                continue

            if i > 0 and nums[i] == nums[i - 1] and not used[i - 1]:
                continue

            used[i] = True
            path.append(nums[i])

            dfs()

            path.pop()
            used[i] = False

    dfs()
    return ans

切割问题

LC131 - 分割回文串

本题可以通过dfs，考虑到所有区间切分的情况，从而将所有符合条件的子区间加入到答案当中。

def partition(self, s: str) -> list[list[str]]:
    def ishuiwen(nums):
        i,j = 0, len(nums)-1
        while i<j:
            if nums[i] != nums[j]:
                return False
            i+=1
            j-=1
        return True
    
    ans = []
    path = []

    def dfs(start):
        if start == len(s):
            ans.append(path[:])
            return 
        
        for end in range(start,len(s)):
            sub = s[start:end+1]
            if not ishuiwen(sub):
                continue
            path.append(sub)
            dfs(end+1)
            path.pop()
            
    dfs(0)
    return ans

看起来，挺像每个位置依次去试，保证能覆盖所有字串。（下一个从end+1开始查）。从 start 位置开始，枚举下一刀切在哪里。如果 s[start:i+1] 是回文，就把这一段加入 path，然后递归处理 i+1 后面的部分。当 start == len(s)，说明整个字符串切完了，得到一个合法方案。

如果只用二重循环，得到的是“局部合法片段”，只有dfs到底，才能得到全局合法方案。

LC93 - 复原IP地址

这题同样是切分问题，判断每个数字是否在0-255之间，在的话才能加入列表，然后用.连接加入答案即可。

    path = []
    ans = []

    def dfs(start: int):
        if len(path) == 4:
            if start == len(s):
                ans.append(".".join(path))
            return

        for end in range(start, min(start + 3, len(s))):
            sub = s[start:end + 1]

            if len(sub) > 1 and sub[0] == "0":
                break

            if int(sub) > 255:
                break

            path.append(sub)
            dfs(end + 1)
            path.pop()

    dfs(0)
    return ans

但是其实细看代码，还是有许多需要注意的逻辑点。首先，我们长度控制在三位及以内，我们应该将这个条件写在end循环中比较好；另外直接转为int，可能会有前导0问题，所以遇到前导0多位数的情况就可以不用继续往后判断了，直接删掉break。

棋盘问题

LC51 - N皇后

N皇后也是在试验每个皇后能放在哪，最终能放完所有皇后。但是与之前相比，变成了二维实验。

当然，由于每一行最多只能放一个皇后，所以不用二重循环，用dfs(row)表示给第row行放皇后即可。

一个典型的想法是维持visited数组，每次回溯。但是这样会更复杂一些，不如另一种方法优雅：我们直接用坐标关系，来判断是不是一个竖行、正对角线、副对角线，然后用集合来判断某竖、正负对角是否被用过即可。

def solveNQueens(n: int) -> list[list[str]]:
    ans = []
    board = [["."] * n for _ in range(n)]

    cols = set()
    diag1 = set()  # row - col
    diag2 = set()  # row + col

    def dfs(row: int):
        if row == n:
            ans.append(["".join(r) for r in board])
            return

        for col in range(n):
            if col in cols:
                continue
            if row - col in diag1:
                continue
            if row + col in diag2:
                continue

            board[row][col] = "Q"
            cols.add(col)
            diag1.add(row - col)
            diag2.add(row + col)

            dfs(row + 1)

            board[row][col] = "."
            cols.remove(col)
            diag1.remove(row - col)
            diag2.remove(row + col)

    dfs(0)
    return ans

LC52 - N皇后II

N皇后2只要统计解决方案的个数即可，正好可以再练一次手。

def totalNQueens(self, n: int) -> int:
    cols = set()
    diag1 = set()
    diag2 = set()
    count = 0
    def dfs(row):
        nonlocal count
        if row == n:
            count += 1
        for col in range(n):
            if row-col in diag1:
                continue
            if row+col in diag2:
                continue
            if col in cols:
                continue
            diag1.add(row-col)
            diag2.add(row+col)
            cols.add(col)
            dfs(row+1)
            diag1.remove(row-col)
            diag2.remove(row+col)
            cols.remove(col)
    dfs(0)
    return count

LC37 - 解数独

和上一题类似，我们用两个集合，rows字典和cols字典。我们可以先将所有需要填写的位置用一个数组存起来，然后再dfs去填写：

def solveSudoku(self, board: list[list[str]]) -> None:
    rows = [set() for _ in range(9)]
    cols = [set() for _ in range(9)]
    boxes = [set() for _ in range(9)]
    # 先找出所有空位，然后dfs去填
    spaces = []

    for i in range(9):
        for j in range(9):
            if board[i][j] == ".":
                spaces.append((i, j))
            else:
                num = board[i][j]
                rows[i].add(num)
                cols[j].add(num)
                # 还有3x3也要去重合
                boxes[(i // 3) * 3 + j // 3].add(num)

    def dfs(idx: int) -> bool:
        if idx == len(spaces):
            return True

        i, j = spaces[idx]
        box_idx = (i // 3) * 3 + j // 3

        for num in map(str, range(1, 10)):
            if num in rows[i]:
                continue
            if num in cols[j]:
                continue
            if num in boxes[box_idx]:
                continue

            board[i][j] = num
            rows[i].add(num)
            cols[j].add(num)
            boxes[box_idx].add(num)

            if dfs(idx + 1):
                return True

            board[i][j] = "."
            rows[i].remove(num)
            cols[j].remove(num)
            boxes[box_idx].remove(num)

        return False

    dfs(0)

搜索路径问题

LC79 - 单词搜索

搜索类问题通常需要向多个方向进行dfs，如果能搜到底就成立。单词搜索的开头不固定，所以我们就二重循环定起点，然后开始dfs。

def exist(self, board: list[list[str]], word: str) -> bool:
    m, n = len(board), len(board[0])
    # dfs(i,j,k)表示当前在ij，要匹配word[k]开始的后缀
    def dfs(i: int, j: int, k: int) -> bool:
        # 特别注意dfs的返回
        # 越界返回
        if i < 0 or i >= m or j < 0 or j >= n:
            return False
        # 非需要字母返回
        if board[i][j] != word[k]:
            return False
        # 长度达标返回True
        if k == len(word) - 1:
            return True

        # 标记，防止重复使用
        ch = board[i][j]
        board[i][j] = "#"

        found = (
            dfs(i - 1, j, k + 1)
            or dfs(i + 1, j, k + 1)
            or dfs(i, j - 1, k + 1)
            or dfs(i, j + 1, k + 1)
        )

        board[i][j] = ch
        return found

    # 多起点dfs
    # 本题不需要path，匹配完成就是满足的
    for i in range(m):
        for j in range(n):
            if dfs(i, j, 0):
                return True

    return False

LC200 - 岛屿数量

进入dfs的入口写在外面，dfs的次数就代表联通区域：

def numIslands(self, grid: list[list[str]]) -> int:
    if not grid:
        return 0

    m, n = len(grid), len(grid[0])
    ans = 0

    def dfs(i: int, j: int) -> None:
        # 走到水里或越界
        if i < 0 or i >= m or j < 0 or j >= n or grid[i][j] != "1":
            return

        # dfs各种走四个方向
        grid[i][j] = "0"
        dfs(i - 1, j)
        dfs(i + 1, j)
        dfs(i, j - 1)
        dfs(i, j + 1)

    # 找到一块陆地，就dfs把附近的路都水淹掉（标记为0）
    for i in range(m):
        for j in range(n):
            if grid[i][j] == "1":
                ans += 1
                dfs(i, j)

    return ans

LC695 - 岛屿的最大面积

求面积要将所有方向的dfs都加起来，然后在求岛模版上加一个最大面积判断即可。

def maxAreaOfIsland(self, grid: list[list[int]]) -> int:
    if not grid:
        return 0

    m, n = len(grid), len(grid[0])

    def dfs(i: int, j: int) -> int:
        if i < 0 or i >= m or j < 0 or j >= n or grid[i][j] != 1:
            return 0

        grid[i][j] = 0

        # 几个方向都走到头
        return (
            1
            + dfs(i - 1, j)
            + dfs(i + 1, j)
            + dfs(i, j - 1)
            + dfs(i, j + 1)
        )

    max_area = 0

    for i in range(m):
        for j in range(n):
            if grid[i][j] == 1:
                max_area = max(max_area, dfs(i, j))

    return max_area

LC130 - 被围绕的区域

这题也是多源 DFS，但思路要反过来。不要从每个 O 出发判断它是否被 X 包围，而是从边界上的 O 出发，把所有与边界连通的 O 标记为安全。因为只要一个 O 能连到边界，它所在的整个连通块就不能被翻转。最后遍历全图，仍然是 O 的位置说明无法连到边界，改成 X；被标记过的安全位置再改回 O。

def solve(self, board: list[list[str]]) -> None:
    if not board or not board[0]:
        return

    m, n = len(board), len(board[0])

    def dfs(i: int, j: int) -> None:
        if i < 0 or i >= m or j < 0 or j >= n:
            return
        if board[i][j] != "O":
            return

        board[i][j] = "#"

        dfs(i - 1, j)
        dfs(i + 1, j)
        dfs(i, j - 1)
        dfs(i, j + 1)

    # 从边界 O 出发，标记所有安全 O
    for i in range(m):
        dfs(i, 0)
        dfs(i, n - 1)

    for j in range(n):
        dfs(0, j)
        dfs(m - 1, j)

    # 没被标记的 O 是被包围的；# 是安全的
    for i in range(m):
        for j in range(n):
            if board[i][j] == "O":
                board[i][j] = "X"
            elif board[i][j] == "#":
                board[i][j] = "O"

dp的结果就从起点开始一直到终止条件，但是上面几题你可以看出来dp的设计很灵活，需要仔细体会。

LC417 - 太平洋大西洋水流问题

分桶与划分问题

LC698 - 划分为K个相等的子集

这一题和数组连续划分的区别在于，这一题要考虑任意子集划分，所以要使用的方法是分桶划分。

def canPartitionKSubsets(self, nums: list[int], k: int) -> bool:
    total = sum(nums)

    if total % k != 0:
        return False

    target = total // k
    nums.sort(reverse=True)

    if nums[0] > target:
        return False

    buckets = [0] * k

    def dfs(index: int) -> bool:
        if index == len(nums):
            return all(bucket == target for bucket in buckets)

        num = nums[index]

        for i in range(k):
            if buckets[i] + num > target:
                continue

            buckets[i] += num

            if dfs(index + 1):
                return True

            buckets[i] -= num

            # 如果当前数字放进空桶都失败了，放进其他空桶也等价
            if buckets[i] == 0:
                return False

        return False

    return dfs(0)

这个思想也很直接，我们从0号桶开始放，放不下了尝试后面的。如果都能放满，就返回True，否则这个方案就不行。剪枝点在于空桶都放不下的话，那直接False。

另外桶划分中，最好让失败趁早发生，也就是说，我们用快排，先把最长的元素塞进桶，早失败早退出。

LC473 - 火柴拼正方形

写了上一题就知道，这一题实际上还是四桶问题。可以直接写写看。

def makesquare(self, matchsticks: list[int]) -> bool:
    matchsticks.sort(reverse=True)
    total = sum(matchsticks)
    if total % 4 != 0:
        return False
    target = total // 4
    buckets = [0] * 4

    # idx是火柴下标
    def dfs(idx):
        if idx == len(matchsticks):
            return all(bucket == target for bucket in buckets)
        matchstick = matchsticks[idx]

        # 遍历桶
        for i in range(4):
            # 放不下就下一个
            if buckets[i] + matchstick > target:
                continue

            # 放进去，就递归，如果递归到底返回True，这里就返回True
            buckets[i] += matchstick
            if dfs(idx + 1):
                return True

            # 回溯
            buckets[i] -= matchstick

            # 剪枝
            if buckets[i] == 0:
                return False
        return False    
        
    return dfs(0)

状态递归：递归函数表示一个状态

斐波那契与爬楼梯

LC509 - 斐波那契数

斐波那切数和爬楼梯应该是很多人动态规划开始的地方。所以我们在这里也写一下dp的方案。

def fib(self, n: int) -> int:
    if n <= 1:
        return n
    dp = [0] * (n+1)
    dp[0] = 0
    dp[1] = 1
    for i in range(2,n+1):
        dp[i] = dp[i-1] + dp[i-2]
    return dp[n]

其实，dp就是打表的递归问题，从而避免计算重复问题。会写dp，自然也会写递归：dp初始状态就是递归出口，状态转移公式就是递归函数，直接变化如下：

def fib(self, n: int) -> int:
    def dfs(n):
        if n <= 1:
            return n
        return dfs(n-1) + dfs(n-2)
    return dfs(n)

递归解法由于会重复计算，效率小于dp。为了不进行裸递归，我们可以使用python的缓存装饰器@cache，从而自动进行记忆化搜索。

def fib(self, n: int) -> int:
    @cache
    def dfs(n):
        if n <= 1:
            return n
        return dfs(n-1) + dfs(n-2)
    return dfs(n)

LC70 - 爬楼梯

跟斐波那契几乎一样。

from functools import cache

def climbStairs(self, n: int) -> int:
    @cache
    def dfs(n):
        if n <= 2:
            return n
        return dfs(n-1)+dfs(n-2)
    return dfs(n)

LC746 - 使用最小花费爬楼梯

和上一题类似，但是这题是看上楼梯的价值。我们尝试递归。

from functools import cache

def minCostClimbingStairs(self, cost: list[int]) -> int:
    # dfs表示到达下标n的最小费用
    @cache
    def dfs(n):
        if n <= 1:
            return 0
        return min(dfs(n-2)+cost[n-2],dfs(n-1)+cost[n-1])
    return dfs(len(cost))

dp写法如下：

def minCostClimbingStairs(self, cost: list[int]) -> int:
    n = len(cost)
    dp = [0] * (n+1)
    for i in range(2,n+1):
        dp[i] = min(dp[i-2]+cost[i-2],dp[i-1]+cost[i-1])
    return dp[n]

关键在于，这题上完所有楼梯之后还要登顶，等跳出所有楼梯再结算而不是上到最后一级台阶。

网格路径

LC62 - 不同路径

这类题目，同样最先想到的是二维dp，是二维dp的启蒙题。

def uniquePaths(self, m: int, n: int) -> int:
    dp = [[1]*n for _ in range(m)]
    # 只能向右或向下，初始化边界
    for i in range(1,m):
        dp[i][0] = 1
    for j in range(1,n):
        dp[0][j] = 1

    for i in range(1,m):
        for j in range(1,n):
            dp[i][j] = dp[i-1][j] + dp[i][j-1]
    
    return dp[m-1][n-1]

dp的题本质上是记忆化递归，所以肯定也能写成递归形式。

from functools import cache

def uniquePaths(self, m: int, n: int) -> int:
    @cache
    def dfs(i,j):
        if i == 0 or j == 0:
            return 1
        return dfs(i-1,j) + dfs(i,j-1)
    return dfs(m-1,n-1)

LC63 - 不同路径II

与不同路径对比，多了一个障碍物的设计，路径不能从障碍物来，同样也不能到障碍物。

def uniquePathsWithObstacles(self, obstacleGrid: list[list[int]]) -> int:
    m = len(obstacleGrid)
    n = len(obstacleGrid[0])
    # 这里要用0，因为不是全网格都默认1，所以还要初始化起点
    dp = [[0]*n for _ in range(m)]
    # 起点或终点本身是石头，无路可走
    if obstacleGrid[0][0] == 1 or obstacleGrid[-1][-1] == 1:
            return 0
    dp[0][0] = 1
    # 只能向右或向下，初始化边界
    for i in range(1,m):
        # 遇到障碍物直接此路不通
        if obstacleGrid[i][0] == 1:
            break
        dp[i][0] = 1
    for j in range(1,n):
        if obstacleGrid[0][j] == 1:
            break
        dp[0][j] = 1

    for i in range(1,m):
        for j in range(1,n):
            if obstacleGrid[i][j] == 0:
                dp[i][j] = dp[i-1][j] + dp[i][j-1]
    
    return dp[m-1][n-1]

效率一样的情况下，这一题记忆递归效率更高，注意递归的时候要先判断下标越界再访问下标。

from functools import cache

def uniquePathsWithObstacles(self, obstacleGrid: list[list[int]]) -> int:
    m = len(obstacleGrid)
    n = len(obstacleGrid[0])
    @cache
    def dfs(i,j):
        if i < 0 or j < 0:
            return 0
        if obstacleGrid[i][j] == 1:
            return 0
        if i == 0 and j == 0:
            return 1
        return dfs(i-1,j) + dfs(i,j-1)
    return dfs(m-1,n-1)

LC64 - 最小路径和

同样往下或者往右走，我们用 dfs(i,j) 来求解位置i、j的最大小路径。

from functools import cache

def minPathSum(self, grid: list[list[int]]) -> int:
    @cache
    def dfs(i,j):
        if i<0 or j<0 :
            return float('inf')
        if i == 0 and j == 0:
            return grid[0][0]
        return grid[i][j] + min(dfs(i-1,j),dfs(i,j-1))
    return dfs(len(grid)-1,len(grid[0])-1)

代码更简洁，但是要注意花费应该什么时候被计算，这是很重要的，跟收费楼梯又是不一样的逻辑，还有就是越界到底应该怎么返回、传入的下标。这些都是容易爆的地方。

背包递归

0-1背包

完全背包

LC416 - 分割等和子集

分割成K个子集，是多桶问题，而这里的分割成两个等和子集，其实就是找出是不是有等于和一半的子集，可以将其理解为0-1背包，每个元素选或不选，最终能否达到target。

from functools import cache

def canPartition(self, nums: list[int]) -> bool:
    total = sum(nums)
    if total % 2 != 0:
        return False
    
    target = total // 2
    
    # 将状态作为参数传入：i 表示当前下标，curr_sum 表示当前的累加和
    @cache
    def dfs(i, curr_sum):
        # 1. 成功条件：凑齐了！
        if curr_sum == target:
            return True
            
        # 2. 失败/终止条件：超重了，或者所有的数字都选完了
        if curr_sum > target or i == len(nums):
            return False
            
        # 3. 状态转移：选当前数字 OR 不选当前数字
        return dfs(i + 1, curr_sum + nums[i]) or dfs(i + 1, curr_sum)
        
    return dfs(0, 0)

一开始用nonlocal来做curr_sum，实际上可以直接写在函数体内。然后就是第一次写用了nonlocal的flag，来表示有没有找到，这样没办法及时剪枝，从而报了TLE。我们需要用dfs来判断当前位置、当前和开始，能不能找到和为target的划分 ，用一个or连接，失败的条件是target或i超限，这是最好最干净的思路。

LC494 - 目标和

其实就是用dfs判断每一位是加还是减。

from functools import cache

def findTargetSumWays(self, nums: list[int], target: int) -> int:
    @cache
    def dfs(i,total):
        if i == len(nums) and total == target:
            return 1
        if i == len(nums):
            return 0
        return dfs(i+1,total-nums[i]) + dfs(i+1,total+nums[i])
    return dfs(0,0)

字符串递归

LC72 - 编辑距离

本题是经典的二维dp题，我们用dp(i,j)表示处理到了word1/2的位置（前面已经相等），但是有三种操作，分别是插入、删除、替换。删除之前需要i-1对上j，所以对应的操作是 dp[i-1][j] + 1；插入需要j-1位置对应上i，也就是 dp[i][j-1] + 1；替换需要i-1和j-1都对应上，也就是操作数 dp[i-1][j-1] + 1。我们取三者中的最小值，就能解决了。

def minDistance(self, word1: str, word2: str) -> int:
    m, n = len(word1), len(word2)
    # dp[i][j] 代表 word1 中前 i 个字符，变换到 word2 中前 j 个字符，最短需要操作的次数
    dp = [[0] * (n+1) for _ in range(m+1)]
    # 基础情况
    for i in range(1,m+1):
        dp[i][0] = i
    for j in range(1,n+1):
        dp[0][j] = j

    for i in range(1,m+1):
        for j in range(1,n+1):
            if word1[i - 1] == word2[j - 1]:
                dp[i][j] = dp[i-1][j-1]
            else:
                dp[i][j] = min(
                    dp[i-1][j] + 1,
                    dp[i][j-1] + 1,
                    dp[i-1][j-1] + 1
                )
    return dp[m][n]

本题用dp比较好想。

LC1143 - 最长公共子序列

我们在一维中经常做到这样的题目，现在要求两个字符串的最长公共子序列，我们依旧可以直接二维dp。

def longestCommonSubsequence(self, text1: str, text2: str) -> int:
    # dp[i][j]为text1第i位和text2第j位的最长公共子串。转移方法是当text1[i]和text2[j]相等的时候，dp[i][j] = dp[i-1][j-1] + 1
    m = len(text1)
    n = len(text2)
    dp = [[0] * (n+1) for _ in range(m+1)]
    for i in range(1,m+1):
        for j in range(1,n+1):
            # Case1、字母相同，直接加到公共子序列
            if text1[i-1] == text2[j-1]:
                dp[i][j] = dp[i-1][j-1] + 1
            else:
                # 如果不相等，看看谁前进一格能让dp更大
                dp[i][j] = max(dp[i-1][j],dp[i][j-1])
    return dp[m][n]

递归解法：

from functools import cache

def longestCommonSubsequence(self, text1: str, text2: str) -> int:
    # 递归写法
    @cache
    def dfs(i,j):
        if i < 0 or j < 0 :
            return 0
        if text1[i] == text2[j]:
            return dfs(i-1,j-1)+1
        return max(dfs(i-1,j),dfs(i,j-1))
    return dfs(len(text1)-1,len(text2)-1)

LC115 - 不同的子序列

子序列问题，判断s子序列中出现t的个数。我们可以直接对s进行dfs，判断符合条件的子序列：

def numDistinct(s: str, t: str) -> int:
    m = len(s)
    n = len(t)
    path = []
    count = 0
    # 用dfs(i)表示第i位选不选，得到t的方案个数
    def dfs(i):
        nonlocal count
        if len(path) == n and "".join(path) == t:
            count += 1
            return
        if i == m:
            return
        # 选
        path.append(s[i])
        dfs(i+1)
        path.pop()

        # 不选
        dfs(i+1)

    dfs(0)
    return count

然而，无脑dfs，必然超时了。这一题其实也是二维dp做法，加一个cache。我们可以将 dp[i][j] 定义为 s 从下标 i 开始的子串，能够匹配出多少个 t 从下标 j 开始的子串。

现在，我们来思考一下转移，这种问题我们要只考虑一个字母。首先，如果两个字母对上了，即 s[i] == t[j]，那么我们有两种选择，要么直接从这开始匹配，dp[i][j] = dp[i+1][j+1]，要么还是不选他，因为后面可能还有，所以是 dp[i][j] = dp[i][j+1]。至于不匹配，那就直接 dp[i][j] = dp[i+1][j+1]。（不过填表的过程需要你用当前dp看之前的dp，写成减号）。

我们来试试按照递归的思路来做，从最后一位开始看。逻辑和上述一样，初始状态是j回退到了0则为1，然后s回退到0即为0

from functools import cache

class Solution:
    def numDistinct(self, s: str, t: str) -> int:
        @cache
        def dfs(i,j):
            if j < 0: 
                return 1
            if i < 0:
                return 0
            if s[i] == t[j]:
                return dfs(i-1,j-1) + dfs(i-1,j)
            else:
                return dfs(i-1,j)
    
        return dfs(len(s)-1,len(t)-1)

LC10 - 正则表达式匹配

本题依旧是基于双指针的dp或者记忆化搜索。基础的规则，如果遇到相同的元素，我们 dp[i][j] = dp[i+1][j+1] ，这是很容易想到的。但是这一题多了.和*。

class Solution:
    def isMatch(self, s: str, p: str) -> bool:
        m, n = len(s), len(p)
        # dp[i][j] 表示 s 的前 i 个字符，和 p 的前 j 个字符是否匹配
        dp = [[False] * (n + 1) for _ in range(m + 1)]
        
        # Base Case 1：两个空字符串，完美匹配
        dp[0][0] = True
        
        # Base Case 2：s 是空字符串，p 不是空字符串。
        # 只有当 p 是类似 "a*b*c*" 这种可以全部“消除”成空串的结构时，才能匹配
        for j in range(1, n + 1):
            if p[j-1] == '*':
                # 如果遇到星号，它的状态等同于把前面那个字符也一起消除掉之前的状态
                dp[0][j] = dp[0][j-2]
                
        # 正向填表
        for i in range(1, m + 1):
            for j in range(1, n + 1):
                # 情况 1：普通字符或者 '.'，直接看上一个状态
                if s[i-1] == p[j-1] or p[j-1] == '.':
                    dp[i][j] = dp[i-1][j-1]
                
                # 情况 2：遇到星号
                elif p[j-1] == '*':
                    # 动作 A：消除器（把 p 的末尾字符和 * 一起当空气）
                    # 状态继承自 dp[i][j-2]
                    erase = dp[i][j-2]
                    
                    # 动作 B：克隆器（前提：s 的最后一个字符必须和 p 中星号前面的字符匹配）
                    # 如果匹配，状态继承自 dp[i-1][j] (客人走了一个，规则还在)
                    clone = False
                    if s[i-1] == p[j-2] or p[j-2] == '.':
                        clone = dp[i-1][j]
                        
                    dp[i][j] = erase or clone
                    
        return dp[m][n]

简单来说，待匹配元素为0来初始化dp表，然后.是一定放行，*分为两种情况，消除前面一位或者让前面一位一直重复。

博弈递归

LC486 - 预测赢家

从现在我们进入了博弈论 DP（Minimax 极小化极大算法），看代码的时候经常很难理解，因为这套递归中，隐藏了无缝的“视角切换”。之前的题，dfs主视角永远是自己、当前，而博弈论中，dfs变成一个高级模型，两人会轮流使用它得出自己的最优解。

我们只用dfs关心自己的分减去对手分的正负，也就是自己的优势。打个比方，我方选择left的时候，对手采用最优解得到的相对我的分数是 dfs(left+1,right)，那么我想对于对手的最优解得到的分数增加就是 nums[left] - dfs(left+1, right)。

所以，实际上我们在两种选择，都会考虑相对于对手的最优解我们的最优解，最终只要判断从这过区间开始，第一个开始选的人能不能让优势大于0，就可以解决这题了。

from functools import cache

def PredictTheWinner(self, nums: list[int]) -> bool:
    @cache
    def dfs(left: int, right: int) -> int:
        # 只剩一个可以拿
        if left == right:
            return nums[left]

        # dfs(left, right) 表示在区间 [left, right] 中，当前玩家相对于对手最多能领先多少分。
        take_left = nums[left] - dfs(left + 1, right)
        take_right = nums[right] - dfs(left, right - 1)

        return max(take_left, take_right)

    # 对手的优势大于0就输了
    return dfs(0, len(nums) - 1) >= 0

LC877 - 石子游戏

这一题其实跟预测赢家一样，我们用dfs来表示对手可能产生的优势，按照相同方式求解。

from functools import cache

def stoneGame(self, piles: list[int]) -> bool:
    @cache
    def dfs(i,j):
        if i == j:
            return piles[i]
        
        take_left = piles[i] - dfs(i+1,j)
        take_right = piles[j] - dfs(i,j-1)

        return max(take_left,take_right)
    
    return dfs(0,len(piles)-1)  > 0

不过，这一题可以直接用石子游戏题目结论秒杀，结论就是先手必胜。。直接return True。

构造递归：递归地生成答案

生成括号

LC22 - 括号生成

dfs生成答案的过程中，我们还要保证括号有效，所以我们需要left和right来维持有效性，可以用nonlocal更改或者直接当参数传入。

def generateParenthesis(self, n: int) -> list[str]:
    ans = []
    path = []

    def dfs(left: int, right: int):
        if len(path) == 2 * n:
            ans.append("".join(path))
            return

        if left < n:
            path.append("(")
            dfs(left + 1, right)
            path.pop()

        if right < left:
            path.append(")")
            dfs(left, right + 1)
            path.pop()

    dfs(0, 0)
    return ans

构造二叉树

LC105 - 从前序与中序遍历序列构造二叉树

树是天然递归结构，我用左右指针对准dfs的结果就行，dfs定义为完成构建的二叉树。同时，我们传入目前的前序和中序数组。

def buildTree(self, preorder: list[int], inorder: list[int]) -> TreeNode:
    if not preorder or not inorder:
        return None

    root_val = preorder[0]
    root = TreeNode(root_val)

    idx = inorder.index(root_val)
    left_size = idx

    root.left = self.buildTree(preorder[1:1 + left_size], inorder[:idx])
    root.right = self.buildTree(preorder[1 + left_size:], inorder[idx + 1:])

    return root

LC106 - 从中序与后序遍历序列构造二叉树

跟上一题如出一辙，我们记得按照方式划分即可。

class TreeNode:
    def __init__(self, val=0, left=None, right=None):
        self.left = left
        self.right = right
        self.val = val

def buildTree(self, inorder: list[int], postorder: list[int]) -> TreeNode:
    # 后序左右根，中序左根右
    if not postorder:
        return None
    root = TreeNode(postorder[-1])
    # 左侧长度为idx
    idx = inorder.index(postorder[-1])
    root.left = buildTree(inorder[:idx],postorder[:idx])
    root.right = buildTree(inorder[idx+1:],postorder[idx:-1])
    return root

LC654 - 最大二叉树

这一题直接就把构造的过程告诉你了，照猫画虎即可。

def constructMaximumBinaryTree(self, nums: list[int]) -> TreeNode:
    if len(nums) == 0:
        return None
    max_num = max(nums)
    root = TreeNode(max_num)
    idx = nums.index(max_num)
    root.left = constructMaximumBinaryTree(nums[:idx])
    root.right = constructMaximumBinaryTree(nums[idx+1:])
    return root

LC108 - 将有序数组转换为二叉搜索树

既然已经是有序数组了，我们每次取中间部分即可。和前面的题没啥区别：

def sortedArrayToBST(self, nums: list[int]) -> TreeNode:
    if not nums:
        return None
    mid = len(nums)//2
    root = TreeNode(nums[mid])
    root.left = sortedArrayToBST(nums[:mid])
    root.right = sortedArrayToBST(nums[mid+1:])
    return root

序列化与反序列化

LC297 - 二叉树的序列化与反序列化

这一题其实可以通过特判空的bfs来解决，这也是带null数组建树的过程和逆过程，我们来实操一下。

from collections import deque

class Codec:
    def serialize(self, root):
        if not root:
            return ""

        q = deque([root])
        ans = []

        while q:
            node = q.popleft()

            if not node:
                ans.append("null")
                continue

            ans.append(str(node.val))
            q.append(node.left)
            q.append(node.right)

        return ",".join(ans)

    def deserialize(self, data):
        if not data:
            return None

        vals = data.split(",")
        root = TreeNode(int(vals[0]))
        q = deque([root])
        # 反序列化需要用i指导位置，然后按照左右左右添加即可。
        i = 1

        while q:
            node = q.popleft()

            if vals[i] != "null":
                node.left = TreeNode(int(vals[i]))
                q.append(node.left)
            i += 1

            if vals[i] != "null":
                node.right = TreeNode(int(vals[i]))
                q.append(node.right)
            i += 1

        return root

但是既然放在这里，那就说明可以通过递归构造法来构造。实际上，我们只要先序遍历就能得到树的，虽然顺序不一样，但是序列化本来就是布置一种顺序，所以用dfs也是可以的。

class Codec:
    def serialize(self, root):
        vals = []

        def dfs(node):
            if not node:
                vals.append("null")
                return

            vals.append(str(node.val))
            dfs(node.left)
            dfs(node.right)

        dfs(root)
        return ",".join(vals)

    def deserialize(self, data):
        vals = data.split(",")
        self.i = 0

        def dfs():
            if vals[self.i] == "null":
                self.i += 1
                return None

            node = TreeNode(int(vals[self.i]))
            self.i += 1

            node.left = dfs()
            node.right = dfs()

            return node

        return dfs()

LC449 - 序列化和反序列化二叉搜索树

有左小右大规律，可以靠值范围恢复结构。这样，我们就不需要null了，直接按照前序建立。然后，反序列化的过程，用BST的上界和下界值域约束：

class Codec:
    def serialize(self, root):
        vals = []

        def dfs(node):
            if not node:
                return
            vals.append(str(node.val))
            dfs(node.left)
            dfs(node.right)

        dfs(root)
        return ",".join(vals)

    def deserialize(self, data):
        if not data:
            return None

        vals = list(map(int, data.split(",")))
        self.i = 0

        def dfs(lower, upper):
            if self.i == len(vals):
                return None

            val = vals[self.i]
            if val < lower or val > upper:
                return None

            self.i += 1
            node = TreeNode(val)
            node.left = dfs(lower, val)
            node.right = dfs(val, upper)
            return node

        return dfs(float("-inf"), float("inf"))

数学递归：按公式定义问题

阶乘

经典递归入门。

def solution(n:int):
    @cache
    def dfs(n:int):
        if n<=1:
            return 1
        return dfs(n-1)*n 
    return dfs(n)

最大公约数

正常做法是从1找到一半（或者平方根）能整除n的数。最大公约数最经典的递归算法是欧几里得算法，核心结论是 gcd(a, b) = gcd(b, a % b) 。所以我们辗转相除，最终一定能得到结果：

def gcd(a: int, b: int) -> int:
    a, b = abs(a), abs(b)
    if b == 0:
        return a
    return gcd(b, a % b)

快速幂

本来x的n次幂要乘n次，时间复杂度是On。但是如果我们存中间的过程，每次把问题减半，就会降低复杂度到Onlogn

def myPow(x: float, n: int) -> float:
    def dfs(n: int) -> float:
        if n == 0:
            return 1

        half = dfs(n // 2)

        if n % 2 == 0:
            return half * half
        else:
            return half * half * x

    if n >= 0:
        return dfs(n)
    else:
        return 1 / dfs(-n)

面试题 08.06. 汉诺塔问题

在经典汉诺塔问题中，有 3 根柱子及 N 个不同大小的穿孔圆盘，盘子可以滑入任意一根柱子。一开始，所有盘子自上而下按升序依次套在第一根柱子上(即每一个盘子只能放在更大的盘子上面)。移动圆盘时受到以下限制: (1) 每次只能移动一个盘子; (2) 盘子只能从柱子顶端滑出移到下一根柱子; (3) 盘子只能叠在比它大的盘子上。

请编写程序，用栈将所有盘子从第一根柱子移到最后一根柱子。

汉诺塔问题也非常经典

这题是递归最经典的数学模型之一。移动 n 个盘子，看起来很复杂，但如果把最大的盘子单独拿出来看，事情就清楚了：

1. 先把上面的 n-1 个盘子借助目标柱移到辅助柱
2. 再把最大的那个盘子移到目标柱
3. 最后把辅助柱上的 n-1 个盘子借助起始柱移到目标柱

也就是说，汉诺塔的本质是：

移动 n 个盘子 = 先解决 n-1 个盘子 + 移动最大的盘子 + 再解决 n-1 个盘子

递归出口就是只剩一个盘子时，直接移动即可：

def hanoi(n: int, source: str, auxiliary: str, target: str) -> None:
    if n == 1:
        print(f"{source} -> {target}")
        return

    hanoi(n - 1, source, target, auxiliary)
    print(f"{source} -> {target}")
    hanoi(n - 1, auxiliary, source, target)

本题最少移动次数是 2^n - 1，时间复杂度为 O(2^n)，空间复杂度为递归栈深度 O(n)。它特别适合帮助理解“把大问题拆成相同形式的小问题”这件事。

约瑟夫环

卡特兰数

递归优化

记忆化搜索

记忆化搜索，就是在递归的基础上加一个缓存，把已经算过的状态保存起来，避免重复计算。

它最适合这种场景：

递归状态很多次重复出现。

典型比如斐波那契数列，朴素递归会反复计算 f(n-1)、f(n-2)。加上记忆化之后，就能把指数级复杂度压下来。

一个常见模板：

from functools import cache

@cache
def dfs(state):
    if 递归出口:
        return base
    return 由更小状态转移得到的结果

记忆化搜索本质上就是“自顶向下的动态规划”。

尾递归

尾递归指的是：递归调用是函数中的最后一步，当前层在递归返回后不再做额外运算。

比如下面这种就更接近尾递归：

def dfs(n, acc):
    if n == 0:
        return acc
    return dfs(n - 1, acc + n)

不过在 Python 里，尾递归并不会像某些语言那样自动优化掉栈空间，所以更多是一个概念上的了解，不用特别执着去写尾递归风格。

剪枝

剪枝就是：发现当前这条递归分支不可能成为答案时，提前停掉，不再继续往下搜。

常见剪枝方式有：

超过目标值直接返回，比如组合总和
同层重复元素直接跳过，比如子集II、组合总和II、全排列II
当前状态已经不合法，立即返回，比如括号生成、N皇后
当前最优值已经不可能超过已有答案，直接停掉

回溯题很多时候能不能通过，差别就在剪枝是否及时。

递归转迭代

递归本质上是系统帮我们维护调用栈，所以很多递归都能改写成“显式维护栈”的迭代。

最常见的例子就是树遍历：

stack = [root]
while stack:
    node = stack.pop()
    ...

一般来说：

如果题目天然是树、图、回溯结构，递归通常更直观
如果数据规模很大，担心爆栈，或者逻辑本身就是线性的，迭代通常更稳

能不能从递归切到迭代，本质上就是看你能不能把“当前层还没做完的信息”自己存在栈里。

递归爆栈问题

当递归层数太深时，就会爆栈。最常见的情况有：

链表递归，但链表很长
树退化成链表
DFS 图/网格时搜索深度过大
递归出口写错，导致无限递归

所以写递归题时，要特别注意：

出口是否一定能到
每次递归规模是否真的变小
最坏情况下递归深度是多少

Python递归深度限制

Python 默认递归深度不高，通常在千级左右。刷题时，如果递归层数可能达到几万，就要警惕。

有时候可以临时调整：

import sys
sys.setrecursionlimit(10**6)

但这不是万能解法。真正更稳的方式还是：

改迭代
优化递归结构
减少不必要的深度

递归题目的分类判断

看数据结构

如果题目本身给的是链表、树、图、网格，那么先想递归往往没错，因为这些结构天然具有“一个部分里还嵌着更小的同类部分”的特点。

链表：当前节点 + 后续链表
二叉树：当前节点 + 左右子树
网格/图：当前点 + 四周可达状态

看是否可以拆成子问题

如果一个问题能自然地写成：

当前问题 = 更小规模的同类问题 + 当前层处理

那它大概率就能用递归。

比如：

反转链表：反转后续链表，再接回当前节点
Pow(x, n)：先求 x^(n//2)，再平方
汉诺塔：先移动 n-1 个盘子，再移动最大的

看是否需要枚举选择

如果每一步都有多个选择，而你需要把所有可能都试一遍，那通常就是回溯递归。

比如：

子集：选或不选
组合：下一个选哪个数
排列：当前位置放谁
N皇后：当前行放哪一列

看是否存在重复子问题

如果不同路径会反复进入同一个状态，那就不要只写朴素递归了，应该进一步考虑记忆化搜索。

比如：

斐波那契
爬楼梯
编辑距离
预测赢家

这些题如果只递归不缓存，复杂度通常会很难看。

看是否需要回溯撤销选择

如果你在递归过程中修改了某些状态，并且回到上一层后还要恢复原状，那这就是典型回溯。

比如：

path.append(...) 之后要 path.pop()
棋盘上放皇后后，回来要撤销
数独填数字后，回来要删掉
网格搜索里标记访问后，回来要恢复

递归常见模板

链表递归模板

链表递归常见于“返回处理后的链表头”：

def dfs(head):
    if not head or not head.next:
        return head

    new_head = dfs(head.next)

    # 当前层处理指针关系
    ...

    return new_head

这类题要特别注意：改指针之前，先想清楚当前层到底返回什么。

二叉树递归模板

二叉树递归最常见的是后序汇总：

def dfs(root):
    if not root:
        return base

    left = dfs(root.left)
    right = dfs(root.right)

    return 用 left 和 right 合并当前答案

如果题目需要自顶向下传信息，也可以写成前序：

def dfs(root, state):
    if not root:
        return

    # 先处理当前节点
    dfs(root.left, new_state)
    dfs(root.right, new_state)

分治递归模板

分治递归就是“先拆，再治，最后合并”：

def dfs(left, right):
    if left == right:
        return 单点答案

    mid = (left + right) // 2
    left_info = dfs(left, mid)
    right_info = dfs(mid + 1, right)

    return merge(left_info, right_info)

如果题目涉及跨中点答案，就把“跨中点”也写在 merge 里考虑进去。

回溯递归模板

组合、排列、切割、棋盘题大多长这样：

ans = []
path = []

def dfs(start):
    if 达成答案:
        ans.append(path[:])
        return

    for i in range(start, 范围终点):
        if 当前选择不合法:
            continue

        path.append(选择)
        dfs(下一层状态)
        path.pop()

如果是排列问题，通常没有 start，而是用 used 数组控制。

记忆化搜索模板

from functools import cache

@cache
def dfs(state1, state2):
    if 递归出口:
        return base

    return 根据更小状态计算结果

一旦题目有“区间 + 最优策略”“字符串前缀 + 最优值”“当前位置 + 剩余容量”这类重复状态，都可以先想这个模板。

DFS网格搜索模板

def dfs(i, j):
    if 越界或当前位置不合法:
        return

    标记当前位置已访问

    dfs(i - 1, j)
    dfs(i + 1, j)
    dfs(i, j - 1)
    dfs(i, j + 1)

如果题目要求统计面积、路径数、是否可达，就把 return 的值改成对应的量即可。

递归问题总结

递归专题走到这里，最重要的其实不是记住多少题，而是形成几个稳定的直觉。

第一，先定义函数，不要先写代码。

这个递归函数到底返回什么？
它处理的是哪个子结构、哪个区间、哪个状态？

第二，出口一定要和函数定义匹配。

空节点返回什么？
空区间返回什么？
目标达成时返回什么？

第三，很多递归题真正难的不是“怎么递”，而是“怎么归”。

普通树题往往递下去不难，真正要想清楚的是：

回来的时候要汇总什么信息
是否要维护全局答案
是否需要在当前层做合并

第四，回溯题的关键不是会不会写 path.append() 和 path.pop()，而是：

这一层的选择范围是什么？
什么情况该 continue？
什么情况该 break？
哪些状态要撤销？

第五，分治题不要先急着看代码，先问：

左边返回什么？
右边返回什么？
当前层怎么合并？

最后给自己留一个非常实用的判断口诀：

树和链表，先想结构递归；
要试所有可能，先想回溯；
问题能切两半，先想分治；
状态重复出现，先想记忆化；
网格四向扩散，先想 DFS。

递归不是一类题，而是一种看问题的方式。只要能把“当前问题”写成“更小的同类问题 + 当前层处理”，递归就自然出来了。

LangChain 核心组件 07：Agents

Fri, 20 Mar 2026 00:00:00 GMT

这篇我刻意放到最后。不是因为 Agents 不重要，而是因为它恰恰太重要、也太综合了。如果不先看底层组件，读 Agent 章节时很容易一直遇到“前面没学过但这里先用了”的跳跃感。

1. 介绍

Agent结合语言模型和工具，创建可以推理任务、决定使用哪些工具并逐步朝着解决方案工作的系统。create_agent 提供了一个生产就绪的Agent实现。LLM 代理在循环中运行工具以实现目标。代理运行直到满足停止条件，即当模型发出最终输出或达到迭代限制时。

%%{
  init: {
    "fontFamily": "monospace",
    "flowchart": {
      "curve": "curve"
    }
  }
}%%
graph TD
  %% Outside the agent
  QUERY([input])
  LLM{model}
  TOOL(tools)
  ANSWER([output])

  %% Main flows (no inline labels)
  QUERY --> LLM
  LLM --"action"--> TOOL
  TOOL --"observation"--> LLM
  LLM --"finish"--> ANSWER

  classDef blueHighlight fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A;
  classDef greenHighlight fill:#DCFCE7,stroke:#16A34A,color:#14532D;
  class QUERY blueHighlight;
  class ANSWER blueHighlight;
  class LLM greenHighlight;
  class TOOL greenHighlight;

如上图，换句话说，create_agent 使用 LangGraph 构建基于图的Agent运行时。一个图由节点（步骤）和边（连接）组成，定义了Agent如何处理信息。代理通过这个图移动，执行节点，例如模型节点（调用模型）、工具节点（执行工具）或中间件。

2. 模型 (Model)

模型是Agent的大脑、推理引擎。有多种方式可以指定。

(1) 静态模型

我们通过传入能被识别的模型字符串，可以直接定义静态模型。字符串映射的完整列表可以看这里，里面有详细的关于model、provider等等的参数映射，用不同模型的时候可以找这里。

from langchain.agents import create_agent

agent = create_agent("openai:gpt-5", tools=tools)

如果要更好控制模型，就需要直接用provider的包，比如之前用过的ChatOpenAI，按照如下的方式：

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model="gpt-5",
    temperature=0.1,
    max_tokens=1000,
    timeout=30
    # ... (other params)
)
agent = create_agent(model, tools=tools)

这里的参数完全由你控制，不同Provider提供的用法查询可以看这里。至于具体参数都怎么使用，可以看这里。

(2) 动态模型

使用@wrap_model_call创建中间件，就可以在运行时根据当前状态或上下文进行选择。官网的例子如下，实现了一个简单的根据信息长度筛选模型：

from langchain_openai import ChatOpenAI
from langchain.agents import create_agent
from langchain.agents.middleware import wrap_model_call, ModelRequest, ModelResponse


basic_model = ChatOpenAI(model="gpt-4.1-mini")
advanced_model = ChatOpenAI(model="gpt-4.1")

@wrap_model_call
def dynamic_model_selection(request: ModelRequest, handler) -> ModelResponse:
    """Choose model based on conversation complexity."""
    message_count = len(request.state["messages"])

    if message_count > 10:
        # Use an advanced model for longer conversations
        model = advanced_model
    else:
        model = basic_model

    return handler(request.override(model=model))

agent = create_agent(
    model=basic_model,  # Default model
    tools=tools,
    middleware=[dynamic_model_selection]
)

使用结构化输出的时候，不支持预绑定模型。

我们来细看一下代码，这个中间件函数会在模型被真正调用之前，先拿到请求看看，需不需要进行某些程度上的更改，改完之后再交给下一个处理者继续进行。要用的东西，我们都是用from langchain.agents.middleware import wrap_model_call来导入。比如ModelRequest类，是一个模型请求类，我们用request这个实例来拿到模型请求对象，这里包含了很多与模型调用有关的信息，比如:

request.state：当前 agent 的状态
request.tools：当前可用工具列表
request.model：当前要用的模型
request.messages：当前消息历史

handler则只是一个“可调用对象”，可以先当做这样一个普通函数理解:

def handler(request: ModelRequest) -> ModelResponse:
    ...

上述例子，我们修改完model之后，用override重写model，返回handler之后的结果。所以过程其实是这样的：

先看当前请求
按条件修改 request，比如切换 model
再调用 handler，把修改后的 request 继续传下去
拿到最终响应并返回

因此，我们在agent创建的时候，将中间件函数写进中间件中即可，如middleware=[dynamic_model_selection]。

3. 工具 (Tool)

工具赋予Agent“take action”的能力。Agent超越了简单的仅模型工具绑定，通过促进：

多次工具调用的顺序（由单个提示触发）
在适当的情况下并行工具调用
根据之前的结果动态选择工具
工具重试逻辑和错误处理
工具调用之间的状态持久性等能力

可以在这里看到工具的详细信息，不过之后也会学习的。

(1) 静态工具

在创建agent时构建，整个执行过程中保持不变的工具，这是最常见和最直接的方法。官网示例如下（没错还是假天气工具）：

from langchain.tools import tool
from langchain.agents import create_agent


@tool
def search(query: str) -> str:
    """Search for information."""
    return f"Results for: {query}"

@tool
def get_weather(location: str) -> str:
    """Get weather information for a location."""
    return f"Weather in {location}: Sunny, 72°F"

agent = create_agent(model, tools=[search, get_weather])

如果提供的是空工具列表的话，代理就会由一个没有调用工具能力的单一LLM节点组成。

(2) 动态工具

工具过多会使模型过载上下文并添加错误的可能，而过少又会限制能力，因此我们需要动态工具。动态工具选择使可用工具集能够根据身份验证状态、用户权限、功能标志或对话阶段进行调整。依然使用@wrap_model_call。

根据工具是否已知，可以采用两种方法。

第一种方法，Filtering pre-registered tools。我们通过将预先的规则写进中间件函数里，达到动态调整工具的效果。又可细分为三个方面，一个是从request的state（request.state）来限制、一个是按照存储内容中的用户偏好或者功能标记来筛选（request.runtime.store）、还有通过运行时候的上下文（requset.runtime.context...）进行筛选。这里不展开，后面学到runtime会细聊。

比如我们可以举一个state的例子，具体依靠两个条件：用户是否认证is_authenticated和对话消息数是否达标message_count。

from langchain.agents import create_agent
from langchain.agents.middleware import wrap_model_call, ModelRequest, ModelResponse
from typing import Callable

@wrap_model_call
def state_based_tools(
    request: ModelRequest,
    handler: Callable[[ModelRequest], ModelResponse]
) -> ModelResponse:
    """Filter tools based on conversation State."""
    # Read from State: check if user has authenticated
    state = request.state
    is_authenticated = state.get("authenticated", False)
    message_count = len(state["messages"])

    # Only enable sensitive tools after authentication
    if not is_authenticated:
        tools = [t for t in request.tools if t.name.startswith("public_")]
        request = request.override(tools=tools)
    elif message_count < 5:
        # Limit tools early in conversation
        tools = [t for t in request.tools if t.name != "advanced_search"]
        request = request.override(tools=tools)

    return handler(request)

agent = create_agent(
    model="gpt-4.1",
    tools=[public_search, private_search, advanced_search],
    middleware=[state_based_tools]
)

这里中间件写的看上去比动态agent更唬人，实际上只是类型标注更详细了，不过也好，能更深刻理解。这里多引入了typing包里面的Callable，如果你python和我一样稀烂可能还不了解，我临时学了下。可以使用Callable来指定参数和返回值的类型。Callable[[Arg1Type, Arg2Type, ...], ReturnType]表示一个接受特定参数类型并返回特定类型值的可调用对象。比如这里，Callable[[ModelRequest], ModelResponse]，表示接受ModelRequest并返回ModelResponse的可调用对象（也就是可以像函数一样直接加个()来执行的对象，包括普通函数、类（调用类就是创建实例）、实现了__call__()的对象）。弄个简单的例子：

from typing import Callable
 
# 定义一个接受两个整数并返回一个整数的可调用对象
def add(a: int, b: int) -> int:
    return a + b
 
def my_function(callback: Callable[[int, int], int]) -> None:
    result = callback(1, 2)
    print(result)
 
my_function(add)  # 输出: 3

意思是，这里是一个可调用对象Callable[[int, int], int]，也就是一个接受两个整数、返回一个整数的可调用对象。然后我们普通函数def add(a: int, b: int) -> int显然满足这个条件，我们可以传入。

回到这里，写Callable[[ModelRequest], ModelResponse]，实际上就是为了给handler写类型标注，表示它是一个接收ModelRequest、输出ModelResponse的可调用对象。这也是中间件里“把请求继续交给下一个处理者”的关键。也就是说，这里和动态model是一样的，只不过写得更加详细一点。

我们继续，刚才说了第一种情况是Filtering pre-registered tools，现在我们来介绍第二种情况，即Runtime tool registration。

当工具在运行时被发现或者创建时（比如MCP服务器加载、基于用户数据生产、或者远程注册表获得），需要既注册这些工具，又动态处理它们的执行。所以这里有两个中间件钩子来使用，一个是wrap_model_call，老朋友，可以用这个在模型推理前将工具动态添加到requset；另外还有一个wrap_tool_call，负责在真正执行工具时把工具名映射到实际的工具函数。

示例如下：

from langchain.tools import tool
from langchain.agents import create_agent
from langchain.agents.middleware import AgentMiddleware, ModelRequest, ToolCallRequest

# A tool that will be added dynamically at runtime
@tool
def calculate_tip(bill_amount: float, tip_percentage: float = 20.0) -> str:
    """Calculate the tip amount for a bill."""
    tip = bill_amount * (tip_percentage / 100)
    return f"Tip: ${tip:.2f}, Total: ${bill_amount + tip:.2f}"

class DynamicToolMiddleware(AgentMiddleware):
    """Middleware that registers and handles dynamic tools."""

    def wrap_model_call(self, request: ModelRequest, handler):
        # Add dynamic tool to the request
        # This could be loaded from an MCP server, database, etc.
        updated = request.override(tools=[*request.tools, calculate_tip])
        return handler(updated)

    def wrap_tool_call(self, request: ToolCallRequest, handler):
        # Handle execution of the dynamic tool
        if request.tool_call["name"] == "calculate_tip":
            return handler(request.override(tool=calculate_tip))
        return handler(request)

agent = create_agent(
    model="gpt-4o",
    tools=[get_weather],  # Only static tools registered here
    middleware=[DynamicToolMiddleware()],
)

# The agent can now use both get_weather AND calculate_tip
result = agent.invoke({
    "messages": [{"role": "user", "content": "Calculate a 20% tip on $85"}]
})

读一下，啥意思呢，这段函数定义了一个找小费的函数，但是定义agent的时候没有传进去。但是，我们从中间件包里导入了AgentMiddleware，是插在agetn运行流程中的中间层基类，从而给Agent扩展了动态添加tool的能力。

我们继承这个基类后，自定义一个agent中间件类，常见用法就是重写这些方法：

class MyMiddleware(AgentMiddleware):
    def before_model(self, state, runtime):
        ...

    def after_model(self, state, runtime):
        ...

    def wrap_model_call(self, request, handler):
        ...

    def wrap_tool_call(self, request, handler):
        ...

如何理解这几个函数，实际上，我们可以把agent运行流程分为如下的过程，并且只有4个插手的时机：

before_model，调用模型前执行，拿到的是agent的状态state，适合检查消息、权限、标志位、更新状态、提起终止流程、决定是否跳转。
wrap_model_call，把整个模型调用包起来，不仅能在前后做事，还能直接修改模型请求、决定是不是需要继续调用、改模型、改工具、改system prompt，功能非常强大，最后再调用handler(request)把流程传下去即可。
模型真正执行
after_model，模型返回结果后执行，适合做记录日志、统计调用次数、读取生成内容、根据结果更新状态。
如果模型决定调工具：
wrap_tool_call，把整个工具调用包起来，在工具真正执行前触发，可以用于拦截某些工具调用、修改工具调用请求、动态替换工具、给工具添加日志、权限校验、错误处理。
工具真正执行

然后，我们在创建agent的时候将这个类的实例创建传给create_agent即可，类似middleware=[MyMiddleware()]。

回到上例，我们实现了一个动态工具中间基类，在wrap_model_call环节重写tools，加入了新工具。然后wrap_tool_call动态处理调用名为"calculate_tip"时，将这次请求的工具调用改为calculate_tip。

为什么需要这两个过程？因为前者只是让模型选工具阶段知道有这么一个工具名，让它有机会吐出{"name": "calculate_tip", ...}这样的输出，而调用的时候需要一个实际可执行的工具，所以需要动态注册 —— 这次执行的Python工具就是calculate_tip对象，即return handler(request.override(tool=calculate_tip))，实现双hook动态注册。

顺带一提，钩子 = 框架提前留好的“插入点”或“扩展点”让你能在某个时机把自己的逻辑“挂进去”，是一种广泛约定的设计思想。

(3) 工具调用错误处理

中间件确实牛逼，我们还可以用@wrap_tool_call这个钩子来自定义工具错误的处理方式。

比如下面的例子中，我们给钩子中写了一个try-catch，然后发成错误的时候，返回一个错误信息。

from langchain.agents import create_agent
from langchain.agents.middleware import wrap_tool_call
from langchain.messages import ToolMessage


@wrap_tool_call
def handle_tool_errors(request, handler):
    """Handle tool execution errors with custom messages."""
    try:
        return handler(request)
    except Exception as e:
        # Return a custom error message to the model
        return ToolMessage(
            content=f"Tool error: Please check your input and try again. ({str(e)})",
            tool_call_id=request.tool_call["id"]
        )

agent = create_agent(
    model="gpt-4.1",
    tools=[search, get_weather],
    middleware=[handle_tool_errors]
)

这样的话，agent会返回一个ToolMessage，带有你刚才自己写的错误信息内容。

(4) 在ReAct循环中使用工具

我们可以会看最开始介绍Agent的图片，实际上Agent是遵循一种ReAct (“Reasoning + Acting”)模式来工作的，具体而言就是在简要推理步骤与针对性工具调用之间交替，并将产生的观察结果反馈到后续决策中，直到能够给出最终答案。

模型什么时候回停止Loop，在create_agent中描述的很明确：模型产出最终回答或者达到迭代上限。一般是交给 agent 里的模型自己判断“现在能不能回答了”，去完成这样一个过程：

模型先看当前消息和工具结果
如果它觉得还需要外部信息，就发起tool_calls
工具执行完，结果回到上下文
模型再判断一次
如果它已经有足够信息，就直接给出最终答案，不再调用工具，这时循环结束

4. System Prompt

(1) system_prompt

可以通过系统提示词，来定义agent如何处理任务。如果没有提供，agent将从消息中推断任务。

system_prompt接受str或者SystemMessage作为输入，使用SystemMessage能让你对提示词结构拥有更多控制权。比如下面的例子中，我们把整本书放进 system prompt，让 agent 以这本书为固定上下文来回答问题”的例子，而且它顺手演示了 Anthropic 的 prompt（Anthropic的提示缓存能力cache_control: {"type": "ephemeral"}，代表这样标记后，会缓存这个内容块，在重复请求时降低延迟和成本。

from langchain.agents import create_agent
from langchain.messages import SystemMessage, HumanMessage

literary_agent = create_agent(
    model="anthropic:claude-sonnet-4-5",
    system_prompt=SystemMessage(
        content=[
            {
                "type": "text",
                "text": "You are an AI assistant tasked with analyzing literary works.",
            },
            {
                "type": "text",
                "text": "<the entire contents of 'Pride and Prejudice'>",
                "cache_control": {"type": "ephemeral"}
            }
        ]
    )
)

result = literary_agent.invoke(
    {"messages": [HumanMessage("Analyze the major themes in 'Pride and Prejudice'.")]}
)

(2) 动态系统提示词

动态的实现方式跟前面其实也没什么区别，这次是使用@dynamic_prompt中间件，来更新system_prompt，用法举例如下，这是根据运行时上下文来决定system_message：

from typing import TypedDict

from langchain.agents import create_agent
from langchain.agents.middleware import dynamic_prompt, ModelRequest


class Context(TypedDict):
    user_role: str

@dynamic_prompt
def user_role_prompt(request: ModelRequest) -> str:
    """Generate system prompt based on user role."""
    user_role = request.runtime.context.get("user_role", "user")
    base_prompt = "You are a helpful assistant."

    if user_role == "expert":
        return f"{base_prompt} Provide detailed technical responses."
    elif user_role == "beginner":
        return f"{base_prompt} Explain concepts simply and avoid jargon."

    return base_prompt

agent = create_agent(
    model="gpt-4.1",
    tools=[web_search],
    middleware=[user_role_prompt],
    context_schema=Context
)

# The system prompt will be set dynamically based on context
result = agent.invoke(
    {"messages": [{"role": "user", "content": "Explain machine learning"}]},
    context={"user_role": "expert"}
)

这里需要说明一下，你也可以直接在@wrap_model_call装饰器下修改，它更加通用。不过建议用@dynamic_prompt，语义清晰、代码直观，所以建议用这个。

5. Name

这是一个可选项，给agent起名，在多智能体系统中将该智能体作为子图添加时，此名称会用做节点标识符。（建议用snake_case命名，防止某些模型提供商不支持含空格或特殊字符的名称）。

6. Advanced concepts

(1) Structured output

在某些情况下，你可能希望智能体以特定格式返回输出。LangChain 通过response_format参数提供了结构化输出的策略。

(2) ToolStrategy

ToolStrategy利用人工工具调用生成结构化输出。这适用于任何支持工具调用的模型。当原生提供商的结构化输出（通过ProviderStrategy）不可用或不可靠时，应使用ToolStrategy。用法也很简单，直接调用的时候传入一个Pydantic的模型给response_format参数就行。

(3) ProvideStrategy

ProviderStrategy使用模型提供商的原生结构化输出生成功能。这种方式更可靠，但仅适用于支持原生结构化输出的提供商

7. 记忆 (Memory)

智能体通过消息状态自动保存对话历史。你也可以配置智能体使用自定义状态模式，以在对话过程中记住额外信息。状态中存储的信息可以被视为智能体的短期记忆：

自定义状态模式必须作为TypedDict扩展AgentState。

有两种定义自定义状态的方式：

通过中间件（推荐）
通过create_agent上的state_schema

(1) 通过中间件自定义状态

当你的自定义状态需要被特定的中间件钩子以及附加到该中间件上的工具访问时，请使用中间件来定义自定义状态。

from langchain.agents import AgentState
from langchain.agents.middleware import AgentMiddleware
from typing import Any


class CustomState(AgentState):
    user_preferences: dict

class CustomMiddleware(AgentMiddleware):
    state_schema = CustomState
    tools = [tool1, tool2]

    def before_model(self, state: CustomState, runtime) -> dict[str, Any] | None:
        ...

agent = create_agent(
    model,
    tools=tools,
    middleware=[CustomMiddleware()]
)

# The agent can now track additional state beyond messages
result = agent.invoke({
    "messages": [{"role": "user", "content": "I prefer technical explanations"}],
    "user_preferences": {"style": "technical", "verbosity": "detailed"},
})

上述例子就是在给agent拓展默认消息状态之外的自定义状态，默认状态下，agent主要会维护messages这样的基础状态，而这里有定义了一个CustomState继承AgentState类，这样以后就会多携带一个user_preferences的字典。

紧接着，我们再次用到AgentMiddleware中间件，将里面的state_schema = CustomState，就告诉了agent，希望整个agent使用CustomState这种状态结构。紧接着，在之前提到过的before_model函数，更新agent的state即可（方法是直接传入），这里还可以多实现一些基于user_preferences的逻辑。

然后我们可以看到，在调用agent的时候，除了message还传入了user_preferences。

(2) 通过`state_schema`自定义状态

使用state_schema参数作为快捷方式，定义仅在工具中使用的自定义状态。例子如下：

from langchain.agents import AgentState


class CustomState(AgentState):
    user_preferences: dict

agent = create_agent(
    model,
    tools=[tool1, tool2],
    state_schema=CustomState
)
# The agent can now track additional state beyond messages
result = agent.invoke({
    "messages": [{"role": "user", "content": "I prefer technical explanations"}],
    "user_preferences": {"style": "technical", "verbosity": "detailed"},
})

这种方法和中间件操作法有什么区别呢？官方更推荐作用域更清晰、更模块化的中间件方式，而这个方法则是直接给整个Agent制定一份自定义结构状态，没办法细分跟哪组工具、哪个中间件有关，不够聚焦。

8. Streaming

我们已经了解到可以通过invoke方法调用智能体以获取最终响应。如果智能体需要执行多个步骤，这一过程可能会耗费一定时间。为了展示中间执行进度，我们可以在消息产生时将其流式返回。

from langchain.messages import AIMessage, HumanMessage

for chunk in agent.stream({
    "messages": [{"role": "user", "content": "Search for AI news and summarize the findings"}]
}, stream_mode="values"):
    # Each chunk contains the full state at that point
    latest_message = chunk["messages"][-1]
    if latest_message.content:
        if isinstance(latest_message, HumanMessage):
            print(f"User: {latest_message.content}")
        elif isinstance(latest_message, AIMessage):
            print(f"Agent: {latest_message.content}")
    elif latest_message.tool_calls:
        print(f"Calling tools: {[tc['name'] for tc in latest_message.tool_calls]}")

这里启动一次agent执行，执行过程中会不断出现chunk，然后用stream_mode = "values"表示每个chunk都是当前时刻的完整的state，所以每次都拿到完整的状态。然后你就懂了，chunk["messages"][-1]就是最后一条信息，用两步判断，如果有内容，再判断是人还是AI说的，输出信息和文本。如果没有内容但是有工具调用，就输出工具调用信息。

9. 中间件 (Middleware)

前面已经用过了很多了，这里再做一个简单的总结：

中间件具备强大的可扩展性，可在执行的不同阶段自定义智能体行为。你可以通过中间件实现以下功能：

在调用模型前处理状态（例如消息裁剪、上下文注入）
修改或验证模型的响应（例如安全防护、内容过滤）
通过自定义逻辑处理工具执行错误
基于状态或上下文实现动态模型选择
添加自定义日志记录、监控或分析功能
中间件可无缝融入智能体的执行流程，让你能够在关键节点拦截并修改数据流，而无需更改智能体的核心逻辑。

上面如果都能想到是怎么做的，那就差不多了解清楚这个Agents特性了。

RAG 查询构建：从元数据过滤到 Text2SQL

Fri, 20 Mar 2026 00:00:00 GMT

到这里，检索已经不只是“把一句问题编码成向量再去搜文本”。如果底层数据源本身带结构，查询构建的关键就在于先把自然语言翻译成合适的查询表达式。

RAG - 查询创建

1. 介绍

前面大多学习从非结构化的数据中检索信息，但是实际应用中，我们常常需要处理更加复杂和多样化的数据，包括结构化数据（如SQL数据库）、半结构化数据（如带有元数据的文档）以及图数据。用户的查询也可能不仅仅是简单的语义匹配，而是包含复杂的过滤条件、聚合操作或关系查询。

查询构建（Query Construction）正是应对这一挑战的关键技术。它利用大语言模型（LLM）的强大理解能力，将用户的自然语言查询“翻译”成针对特定数据源的结构化查询语言或带有过滤条件的请求。这使得RAG系统能够无缝地连接和利用各种类型的数据，从而极大地扩展了其应用场景和能力。

2. 从文本到元数据过滤器

在构建向量索引时，常常会为文档块（Chunks）附加元数据（Metadata），例如文档来源、发布日期、作者、章节、类别等。这些元数据为我们提供了在语义搜索之外进行精确过滤的可能。

自查询检索器（Self-Query Retriever）是LangChain中实现这一功能的核心组件。它的工作流程如下：

定义元数据结构：首先，需要向LLM清晰地描述文档内容和每个元数据字段的含义及类型。
查询解析：当用户输入一个自然语言查询时，自查询检索器会调用LLM，将查询分解为两部分：
- 查询字符串（Query String）：用于进行语义搜索的部分。
- 元数据过滤器（Metadata Filter）：从查询中提取出的结构化过滤条件。
执行查询：检索器将解析出的查询字符串和元数据过滤器发送给向量数据库，执行一次同时包含语义搜索和元数据过滤的查询。

例如，对于查询“关于2022年发布的机器学习的论文”，自查询检索器会将其解析为：

查询字符串: "机器学习的论文"
元数据过滤器: year == 2022

下面，来看看SelfQueryRetriever的最小示例：

import os

from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from langchain_milvus import Milvus

from langchain_classic.chains.query_constructor.schema import AttributeInfo
from langchain_classic.retrievers.self_query.base import SelfQueryRetriever
from langchain_community.query_constructors.milvus import MilvusTranslator


# 1. 模型
llm = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0,
    api_key=os.environ["QIHANG_API"],
    base_url=os.environ["QIHANG_BASE_URL"],
)

embeddings = OpenAIEmbeddings(
    model="text-embedding-3-small",
    api_key=os.environ["QIHANG_API"],
    base_url=os.environ["QIHANG_BASE_URL"],
)

# 2. 连接你现有的 Milvus collection
vectorstore = Milvus(
    embedding_function=embeddings,
    collection_name="RL_docs",
    connection_args={"uri": os.environ["MILVUS_URL"]},
    primary_field="id",
    text_field="text",
    vector_field="vector",
    search_params={"metric_type": "COSINE", "params": {}},
)

# 3. 告诉 SelfQueryRetriever：你的 metadata 有哪些字段
metadata_field_info = [
    AttributeInfo(
        name="h1",
        description="一级标题，例如 一. 鸿沟 -- 为什么需要RL ?",
        type="string",
    ),
    AttributeInfo(
        name="h2",
        description="二级标题，例如 4. 强化学习的特征与历史",
        type="string",
    ),
    AttributeInfo(
        name="h3",
        description="三级标题，例如 3. Q-learning",
        type="string",
    ),
]

document_content_description = "强化学习学习笔记的文本片段"

# 4. 创建 SelfQueryRetriever
retriever = SelfQueryRetriever.from_llm(
    llm=llm,
    vectorstore=vectorstore,
    document_contents=document_content_description,
    metadata_field_info=metadata_field_info,
    structured_query_translator=MilvusTranslator(),
    enable_limit=True,
    search_kwargs={"k": 4},
    verbose=True,
)

# 5. 直接自然语言检索
docs = retriever.invoke("只看三级标题和 Q-learning 有关的内容，返回2条")

for i, doc in enumerate(docs, start=1):
    print(f"--- 文档 {i} ---")
    print(doc.metadata)
    print(doc.page_content[:300])
    print()

提一嘴就是现在结构化主要通过Schema等验证去做了，你可以看到这个方法已经被放到langchain_classic.retrievers.self_query.base 里面了。

3. 从文本到Cypher

与“文本到元数据过滤器”类似，“文本到Cypher”技术利用大语言模型（LLM）将用户的自然语言问题直接翻译成一句精准的 Cypher 查询语句。LangChain 提供了相应的工具链（如 GraphCypherQAChain），其工作流程通常是：

接收用户的自然语言问题。
LLM 根据预先提供的图谱模式（Schema），将问题转换为 Cypher 查询。
在图数据库上执行该查询，获取精确的结构化数据。
(可选)将查询结果再次交由 LLM，生成通顺的自然语言答案。

由于生成有效的 Cypher 查询是一项复杂的任务，通常使用性能较强的 LLM 来确保转换的准确性。通过这种方式，用户可以用最自然的方式与高度结构化的图数据进行交互，极大地降低了数据查询的门槛。

4. Text2SQL

这是结构化数据领域中一个常见的应用。在数据世界中，除了向量数据库能够处理的非结构化数据，关系型数据库（如 MySQL, PostgreSQL, SQLite）同样是存储和管理结构化数据的重点。文本到SQL（Text-to-SQL）正是为了打破人与结构化数据之间的语言障碍而生。它利用大语言模型（LLM）将用户的自然语言问题，直接翻译成可以在数据库上执行的SQL查询语句。

LangChain 进阶：Middleware

Thu, 19 Mar 2026 00:00:00 GMT

这篇更像 Agents 的后续拆解。前面已经把模型、消息、工具、记忆、流式和结构化输出串起来了，这里再回头看 middleware，就更容易理解它到底是“插在循环的哪一层”。

1. 介绍

中间件提供了一种更精细地控制智能体内部运行逻辑的方式。中间件适用于以下场景：

通过日志、分析和调试跟踪智能体行为。
转换提示词、工具选择及输出格式。
添加重试、降级方案和提前终止逻辑。
应用速率限制、防护机制及个人身份信息检测

只要在create_agent的时候传入中间件即可，代码示例如下：

from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware, HumanInTheLoopMiddleware

agent = create_agent(
    model="gpt-4.1",
    tools=[...],
    middleware=[
        SummarizationMiddleware(...),
        HumanInTheLoopMiddleware(...)
    ],
)

我们知道，agent被invoke之后会进入一个loop，而中间件，就是在其中各个节点添加中间件。前面的学习中，其实我们已经多次用到中间件了。我们将普通的Agent Loop和带中间件的Agent Loop总结如下：

2. Prebuilt middleware

LangChain 和 Deep Agents 为常见应用场景提供预构建中间件。每种中间件均可直接用于生产环境，并可根据你的具体需求进行配置。

总结如下。为了方便查阅，我把表格和下面的示例代码做成了跳转关系：

点击 “Middleware” 列：跳到本文档下方对应示例
点击 “官方文档” 列：跳到 LangChain 官方 built-in middleware 页面对应章节

Middleware	中文解释	作用	典型用法	适用场景	官方文档
Summarization	对话摘要	当上下文快接近 token 上限时，自动压缩历史对话，保留关键信息	把早期多轮聊天总结成一段摘要，替换冗长历史消息	长对话、客服、持续多轮 agent	链接
Human-in-the-loop	人类介入审批	在执行高风险动作前暂停，让人工确认是否继续	调用删除文件、发邮件、转账、外部 API 写操作前先审批	高风险工具调用、生产环境	链接
Model call limit	模型调用次数限制	限制一次任务中调用 LLM 的次数，防止死循环或费用失控	设置最多调用模型 5 次，超出后直接终止	成本控制、调试 agent 循环	链接
Tool call limit	工具调用次数限制	限制 agent 调用工具的次数，避免无限试错	限制搜索工具最多调 3 次、数据库查询最多调 5 次	工具容易死循环、外部调用昂贵	链接
Model fallback	模型降级/回退	主模型失败时，自动切换到备用模型继续执行	先用 `gpt-4o`，失败后回退到 `gpt-4o-mini`	稳定性要求高、生产兜底	链接
PII detection	敏感信息检测	检测输入/输出中是否包含个人敏感信息，并执行脱敏、拦截或告警	识别手机号、身份证号、邮箱后自动打码	隐私合规、企业内部系统	链接
To-do list	待办列表	给 agent 增加任务分解、任务跟踪和完成状态记录能力	把“大任务”拆成多个步骤，逐步完成并更新状态	长流程任务、研究型 agent	链接
LLM tool selector	工具预筛选器	先用一个小模型判断哪些工具相关，再交给主模型决策	先选出最可能需要的 3 个工具，减少主模型负担	工具很多、路由复杂	链接
Tool retry	工具重试	工具调用失败时自动重试，并通常使用指数退避	网络超时后 1 秒、2 秒、4 秒后再试	外部 API 不稳定、偶发失败	链接
Model retry	模型重试	模型请求失败时自动重试，减少临时错误影响	遇到超时、429、临时连接失败时自动再调一次	模型 API 不稳定、网络波动	链接
LLM tool emulator	工具模拟器	用 LLM 模拟工具执行结果，便于测试 agent 流程	不连真实数据库，而让模型假装返回查询结果	本地调试、测试、演示	链接
Context editing	上下文编辑	动态裁剪、清理或重写上下文内容，避免上下文污染	删掉无用 tool message，只保留关键结论	长流程、多工具混杂场景	链接
Shell tool	Shell 工具	给 agent 一个可持续的终端会话，让它执行命令	运行 `ls`、`python`、`git status` 等命令	编码 agent、自动化运维	链接
File search	文件搜索	提供文件级搜索能力，如 Glob、Grep、全文检索	按文件名查找 `*.md`，或全文搜索某个函数名	代码库问答、文档检索	链接
Filesystem	文件系统	给 agent 提供读写文件能力，用于保存上下文、缓存或长期记忆	把中间结果写入文件，下次继续读取	持久化记忆、任务缓存	链接
Subagent	子代理	允许 agent 派生多个子 agent 分工处理任务	一个 agent 查资料，一个 agent 写总结，一个 agent 校验结果	复杂任务拆分、并行处理	链接

接下来，看看大概是怎么用的：

Summarization

from langchain.agents import create_agent
from langchain.agents.middleware import SummarizationMiddleware

agent = create_agent(
    model="gpt-4.1",
    tools=[your_weather_tool, your_calculator_tool],
    middleware=[
        SummarizationMiddleware(
            model="gpt-4.1-mini",
            trigger=("tokens", 4000),
            keep=("messages", 20),
        ),
    ],
)

Human-in-the-loop

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver


def your_read_email_tool(email_id: str) -> str:
    """Mock function to read an email by its ID."""
    return f"Email content for ID: {email_id}"

def your_send_email_tool(recipient: str, subject: str, body: str) -> str:
    """Mock function to send an email."""
    return f"Email sent to {recipient} with subject '{subject}'"

agent = create_agent(
    model="gpt-4.1",
    tools=[your_read_email_tool, your_send_email_tool],
    checkpointer=InMemorySaver(),
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                "your_send_email_tool": {
                    "allowed_decisions": ["approve", "edit", "reject"],
                },
                "your_read_email_tool": False,
            }
        ),
    ],
)

Model call limit

from langchain.agents import create_agent
from langchain.agents.middleware import ModelCallLimitMiddleware
from langgraph.checkpoint.memory import InMemorySaver

agent = create_agent(
    model="gpt-4.1",
    checkpointer=InMemorySaver(),  # Required for thread limiting
    tools=[],
    middleware=[
        ModelCallLimitMiddleware(
            thread_limit=10,
            run_limit=5,
            exit_behavior="end",
        ),
    ],
)

Tool call limit

from langchain.agents import create_agent
from langchain.agents.middleware import ToolCallLimitMiddleware

agent = create_agent(
    model="gpt-4.1",
    tools=[search_tool, database_tool],
    middleware=[
        # Global limit
        ToolCallLimitMiddleware(thread_limit=20, run_limit=10),
        # Tool-specific limit
        ToolCallLimitMiddleware(
            tool_name="search",
            thread_limit=5,
            run_limit=3,
        ),
    ],
)

Model fallback

from langchain.agents import create_agent
from langchain.agents.middleware import ModelFallbackMiddleware

agent = create_agent(
    model="gpt-4.1",
    tools=[],
    middleware=[
        ModelFallbackMiddleware(
            "gpt-4.1-mini",
            "claude-3-5-sonnet-20241022",
        ),
    ],
)

PII detection

from langchain.agents import create_agent
from langchain.agents.middleware import PIIMiddleware

agent = create_agent(
    model="gpt-4.1",
    tools=[],
    middleware=[
        PIIMiddleware("email", strategy="redact", apply_to_input=True),
        PIIMiddleware("credit_card", strategy="mask", apply_to_input=True),
    ],
)

from langchain.agents import create_agent
from langchain.agents.middleware import PIIMiddleware
import re


# Method 1: Regex pattern string
agent1 = create_agent(
    model="gpt-4.1",
    tools=[],
    middleware=[
        PIIMiddleware(
            "api_key",
            detector=r"sk-[a-zA-Z0-9]{32}",
            strategy="block",
        ),
    ],
)

# Method 2: Compiled regex pattern
agent2 = create_agent(
    model="gpt-4.1",
    tools=[],
    middleware=[
        PIIMiddleware(
            "phone_number",
            detector=re.compile(r"\+?\d{1,3}[\s.-]?\d{3,4}[\s.-]?\d{4}"),
            strategy="mask",
        ),
    ],
)

# Method 3: Custom detector function
def detect_ssn(content: str) -> list[dict[str, str | int]]:
    """Detect SSN with validation.

    Returns a list of dictionaries with 'text', 'start', and 'end' keys.
    """
    import re
    matches = []
    pattern = r"\d{3}-\d{2}-\d{4}"
    for match in re.finditer(pattern, content):
        ssn = match.group(0)
        # Validate: first 3 digits shouldn't be 000, 666, or 900-999
        first_three = int(ssn[:3])
        if first_three not in [0, 666] and not (900 <= first_three <= 999):
            matches.append({
                "text": ssn,
                "start": match.start(),
                "end": match.end(),
            })
    return matches

agent3 = create_agent(
    model="gpt-4.1",
    tools=[],
    middleware=[
        PIIMiddleware(
            "ssn",
            detector=detect_ssn,
            strategy="hash",
        ),
    ],
)

3. Custom middleware

自定义的中间件，就是前面说的几个钩子自定义函数，大概有这几类：

Node-style:

@before_agent - 智能体启动前执行（每次调用仅运行一次）
@before_model - 每次调用模型前执行
@after_model - 每次模型返回结果后执行
@after_agent - 智能体执行完成后执行（每次调用仅运行一次）

Wrap-style:

@wrap_model_call - 用自定义逻辑包装每次模型调用
@wrap_tool_call - 用自定义逻辑包装每次工具调用 Convenience:
@dynamic_prompt - 生成动态系统提示词

关于这几个的调用，假设我们传入了三个中间件，执行流大概是这样的：

Before hooks run in order:
middleware1.before_agent()
middleware2.before_agent()
middleware3.before_agent()
Agent loop starts
middleware1.before_model()
middleware2.before_model()
middleware3.before_model()
Wrap hooks nest like function calls:
middleware1.wrap_model_call() → middleware2.wrap_model_call() → middleware3.wrap_model_call() → model
After hooks run in reverse order:
middleware3.after_model()
middleware2.after_model()
middleware1.after_model()
Agent loop ends
middleware3.after_agent()
middleware2.after_agent()
middleware1.after_agent()

4. Agent jumps

我们可以使用jump_to命令，提前退出中间件，有几个条跳转对象：

'end'：跳转到智能体执行结束（或首个after_agent钩子）
'tools'：跳转到工具节点
'model'：跳转到模型节点（或首个before_model钩子）

例子如下：

from langchain.agents.middleware import after_model, hook_config, AgentState
from langchain.messages import AIMessage
from langgraph.runtime import Runtime
from typing import Any


@after_model
@hook_config(can_jump_to=["end"])
def check_for_blocked(state: AgentState, runtime: Runtime) -> dict[str, Any] | None:
    last_message = state["messages"][-1]
    if "BLOCKED" in last_message.content:
        return {
            "messages": [AIMessage("I cannot respond to that request.")],
            "jump_to": "end"
        }
    return None

5. 最好的用法

保持中间件职责专一 —— 每个中间件只做好一件事
优雅处理错误 —— 避免中间件异常导致智能体崩溃

使用合适的钩子类型:

节点式钩子用于顺序逻辑（日志记录、数据校验）
包装式钩子用于控制流（重试、降级、缓存）
清晰文档化所有自定义状态属性
集成前对中间件进行独立单元测试
考虑执行顺序 —— 关键中间件放在列表首位
尽可能使用内置中间件

RAG 查询翻译：重写、分解与路由

Thu, 19 Mar 2026 00:00:00 GMT

查询构建更像“把自然语言翻译成某种结构化查询”；这一篇进一步处理另一个问题：就算面对的还是普通文本检索，原始问题本身也未必是一个好 query。

RAG - 查询重构与分发

一、引入

此前已经学习了如何从不同类型的数据源（如向量数据库、关系型数据库）中构建查询。然而，用户的原始问题往往不是最优的检索输入。它可能过于复杂、包含歧义，或者与文档的实际措辞存在偏差。为了解决这些问题，我们需要在检索之前对用户的查询进行“预处理”，这就是本节要探讨的查询重构与分发。

这个阶段主要包含两个关键技术：

查询翻译（Query Translation）：将用户的原始问题转换成一个或多个更适合检索的形式。
查询路由（Query Routing）：根据问题的性质，将其智能地分发到最合适的数据源或检索器。

本节将重点介绍几种主流的查询翻译技术，并简要讨论查询路由的概念。

二、查询翻译

1. 提示工程

最直接的查询重构方法。通过精心设计的提示词（Prompt），可以引导 LLM 将用户的原始查询改写得更清晰、更具体，或者转换成一种更利于检索的叙述风格。比如，要求 LLM 直接分析用户的意图，并生成一个结构化（例如 JSON 格式）的指令，告诉我们的代码应该如何操作。

举例如下：

# 使用大模型将自然语言转换为排序指令
prompt = f"""你是一个智能助手，请将用户的问题转换成一个用于排序视频的JSON指令。

你需要识别用户想要排序的字段和排序方向。
- 排序字段必须是 'view_count' (观看次数) 或 'length' (时长) 之一。
- 排序方向必须是 'asc' (升序) 或 'desc' (降序) 之一。

例如:
- '时间最短的视频' 或 '哪个视频时间最短' 应转换为 {{"sort_by": "length", "order": "asc"}}
- '播放量最高的视频' 或 '哪个视频最火' 应转换为 {{"sort_by": "view_count", "order": "desc"}}

请根据以下问题生成JSON指令:
原始问题: "{query}"

JSON指令:"""

然后我们在代码中调用LLM，解析其返回的JSON指令。

2. 多查询分解

当用户提出一个复杂的问题时，直接用整个问题去检索可能效果不佳，因为它可能包含多个子主题或意图。分解技术的核心思想是将这个复杂问题拆分成多个更简单、更具体的子问题。然后，系统分别对每个子问题进行检索，最后将所有检索到的结果合并、去重，形成一个更全面的上下文，再交给 LLM 生成最终答案。

示例：

原始问题：“在《流浪地球》中，刘慈欣对人工智能和未来社会结构有何看法？”
分解后的子问题：
- “《流浪地球》中描述的人工智能技术有哪些？”
- “《流浪地球》中描绘的未来社会是怎样的？”
- “刘慈欣关于人工智能的观点是什么？”

LangChain 提供了 MultiQueryRetriever 来完成这一过程。它在内部利用 LLM 将原始问题从不同角度分解成多个子问题，然后并行为每个子问题检索相关文档。最后，它将所有检索到的文档合并并去重，形成一个更全面的上下文，再传递给语言模型生成最终答案。通过这种策略，极大地丰富了检索结果，在有些应用中可以有效提升后续生成环节的质量。

3. 退步提示（Step-Back Prompting）

退步提示是由 Google DeepMind 团队提出的一种旨在提升大语言模型推理能力的提示工程技巧。当面对一个细节繁多或过于具体的问题时，模型直接作答（即便是使用思维链）也容易出错。退步提示通过引导模型“退后一步”来解决这个问题。

其核心流程分为两步：

抽象化：首先，引导 LLM 从用户的原始具体问题中，生成一个更高层次、更概括的“退步问题”（Step-back Question）。这个退步问题旨在探寻原始问题背后的通用原理或核心概念。
推理：接着，系统会先获取“退步问题”的答案（例如，一个物理定律、一段历史背景等），然后将这个通用原理作为上下文，再结合原始的具体问题，进行推理并生成最终答案。

示例：

原始问题：“如果理想气体的温度增加2倍，体积增加8倍，其压力会如何变化？”
退步问题：“这个问题背后的物理原理是什么？”
推理过程：首先回答退步问题，得到“理想气体定律 PV=nRT”。然后基于这个定律，代入具体数值进行计算，最终得出压力变为原来的1/4。

4. 假设性文档嵌入（HyDE）

假设性文档嵌入（Hypothetical Document Embeddings, HyDE）是一种无需微调即可显著提升向量检索质量的查询改写技术，由 Luyu Gao 等人在其论文中首次提出。其核心是解决一个普遍存在于检索任务中的难题：用户的查询（Query）通常简短、关键词有限，而数据库中存储的文档则内容详实、上下文丰富，两者在语义向量空间中可能存在“鸿沟”，导致直接用查询向量进行搜索效果不佳。

HyDE 通过一种巧妙的方式来“绕过”这个问题：它不直接使用用户的原始查询，而是先利用一个生成式大语言模型（LLM）来生成一个“假设性”的、能够完美回答该查询的文档。然后，HyDE 将这个内容详实的假设性文档进行向量化，用其生成的向量去数据库中寻找与之最相似的真实文档。HyDE 的工作流程可以分为三个步骤：

生成：当接收到用户查询时，首先调用一个生成式 LLM（例如，GPT-3.5）。提示该模型根据查询生成一个详细的、可能是理想答案的文档。这个文档不必完全符合事实，但它必须在语义上与一个好的答案高度相关。
编码：将上一步生成的假设性文档输入到一个对比编码器（如 Contriever）中，将其转换为一个高维向量嵌入。这个向量在语义上代表了一个“理想答案”的位置。
检索：使用这个假设性文档的向量，在向量数据库中执行相似性搜索，找出与这个“理想答案”最接近的真实文档。这些被检索出的文档将作为最终的上下文信息。

通过这种方式，HyDE 将困难的“查询到文档”的匹配问题，转化为了一个相对容易的“文档到文档”的匹配问题，从而提升检索的准确率。

三、查询路由

查询路由（Query Routing）是用于优化复杂 RAG 系统的一项关键技术。当系统接入了多个不同的数据源或具备多种处理能力时，就需要一个“智能调度中心”来分析用户的查询，并动态选择最合适的处理路径。其本质是替代硬编码规则，通过语义理解将查询分发至最匹配的数据源、处理组件或提示模板，从而提升系统的效率与答案的准确性。

查询路由有两种主流方法：

1. 基于LLM的意图识别

这是最灵活的方法。通过设计一个包含路由选项的提示词，让大语言模型（LLM）直接对用户的查询进行分类，并输出一个代表路由选择的标签。

实现流程：
1. 定义清晰的路由选项（例如，数据源名称、功能分类）。
2. LLM 分析查询并输出决策标签。
3. 代码根据标签调用相应的检索器或工具。

该方法的核心在于构建一个“分类-分发”的流水线。

2. 嵌入相似性路由

这种方法不依赖 LLM 进行分类，延迟更低。它通过计算用户查询与预设的“路由示例语句”之间的向量嵌入相似度来做出决策。

OwEn

Docker 学习路线图：镜像到 Compose 的一条主线

LangGraph 学习路线图：先建图，再进入持久化与中断

Fine Tuning 学习路线图：从微调基础到多模态实战复盘

FastAPI 学习路线图：把教程式切分重新排成一条主线

1. 应用入口、fastapi dev、uvicorn

2. URL 输入：路径参数与查询参数

3. 请求体与 Pydantic 模型

4. 参数来源与校验

5. 输出层：响应模型、状态码与更新语义

6. 请求编码切换：表单与文件上传

7. 依赖注入、yield、错误处理与安全起步

8. Bigger Applications：APIRouter、多文件结构、生命周期

9. 中间件、CORS、后台任务

10. 测试、CLI、手动运行与 Workers

claude-code的源码拆解学习

一、总介绍

二、s01–s12

1. s01：最小 Agent 循环——"一个循环 + 一个 Bash，就是一个 Agent"

(1) 依赖与环境

(2) 系统提示词——赋予模型"身份"

(3) 工具定义——模型唯一能"调用"的东西

(4) 工具执行——run_bash

(5) 核心循环——整个 s01 的灵魂

(6) 交互循环——REPL 外壳

(7) macOS UTF-8 输入补丁

(8) 运行

关键洞察

2. s02：工具分发——"加工具不改循环"

(1) 路径沙箱——safe_path

(2) 三个新工具的函数实现

(3) 分发映射——Dispatch Map

(4) 循环中的分发调用

(5) 工具定义——JSON Schema 数组

(6) s01 → s02 变化总结

(7) 运行

关键洞察

3. s03：TodoWrite——"没有计划的 Agent 走哪算哪"

(1) TodoManager——有状态的待办管理器

(2) todo 工具——模型自己写、自己更新

(3) Nag Reminder——harness 的催促机制

(4) 为什么这个设计有效

(5) s02 → s03 变化总结

(6) 运行

关键洞察

4. s04：Subagent——"上下文隔离就是思维隔离"

(1) 两套工具、两套身份

(2) run_subagent——独立循环 + 上下文丢弃

(3) 父 loop 中的 task 调度

(4) 为什么不允许递归生成

(5) 这个模式的应用场景

(6) s03 → s04 变化总结

(7) 运行

关键洞察

5. s05：Skill 加载——"用到什么知识，临时加载什么"

(1) Skill 的文件格式——YAML frontmatter + Markdown 正文

(2) SkillLoader——扫描、解析、两层供给

(3) system prompt 中只放名字

(4) load_skill 工具——模型需要时自己调

(5) 为什么走 tool_result 而不是 system prompt？

(6) 和 prompt engineering 的区别

(6.5) 一个常见误解：pdf skill 能"处理 PDF"吗？

(7) s04 → s05 变化总结

(8) 运行

关键洞察

6. s06：上下文压缩——"Agent 可以策略性地遗忘"

Layer 1：micro_compact——沉默的清扫工

Layer 2：auto_compact——"我记不住了，帮我总结一下"

Layer 3：compact 工具——模型主动请求压缩

三层在循环中的位置

三层金字塔的总结

s05 → s06 变化总结

运行

关键洞察

7. s07：任务系统——"比任何一次对话都长命的目标"

(1) 磁盘上的任务图

(2) TaskManager——CRUD + 依赖传播

(3) 依赖传播——完成即解锁

(4) 四个 task 工具

(5) s03 TodoWrite vs s07 TaskManager 对比

1. 应用入口、`fastapi dev`、`uvicorn`

7. 依赖注入、`yield`、错误处理与安全起步

8. Bigger Applications：`APIRouter`、多文件结构、生命周期

(4) 工具执行——`run_bash`

(1) 路径沙箱——`safe_path`

(2) `run_subagent`——独立循环 + 上下文丢弃

(4) `load_skill` 工具——模型需要时自己调

(2) `run()`——启动即返回

(3) `_execute()`——线程内的 subprocess

(4) `drain_notifications()`——循环中唯一的线程交汇点

(2) 任务看板扫描——`scan_unclaimed_tasks`

(3) 任务认领——`claim_task`

(5) `idle` 工具——模型主动说"我干完了"