Edward Chen

OpenCLAW vs Hermes：多智能体框架深度对比

Wed, 22 Jul 2026 00:00:00 GMT

OpenCLAW vs Hermes：多智能体框架深度对比

引言：为什么需要对比？

1.1 多智能体框架的兴起

2024-2026 年，LLM 应用从单 Agent 向多 Agent 协作演进。早期应用（如 Chatbot）只需一个 LLM 处理用户请求，但复杂场景（如数据分析、工作流自动化）需要多个 Agent 分工协作。

为什么需要框架？

避免重复造轮子：Agent 协作的通用模式（任务分解、状态管理、工具调用）
降低开发成本：框架提供基础设施，开发者专注业务逻辑
最佳实践沉淀：框架封装了多 Agent 协作的经验和教训

1.2 对比的动机

Hermes：我使用数个月，熟悉其能力边界。它是一个个人 AI 助手，擅长即时交互、工具调用、知识管理。

OpenCLAW：新兴的多 Agent 框架，设计哲学与 Hermes 截然不同。它强调自主 Agent 协作，适合复杂任务分解和企业级工作流。

对比价值：帮助读者根据场景选择合适框架，避免"用锤子找钉子"。

1.3 对比维度

设计哲学：以人为本 vs Agent 优先
源码架构：核心类、设计模式、关键实现
能力边界：擅长什么、不擅长什么
适用场景：什么时候选哪个

Hermes 框架深度解析

2.1 设计哲学

以人为本：Hermes 是 AI 助手，而非自主 Agent。人类始终在控制回路中，AI 辅助而非替代。

工具优先：内置丰富工具集（终端、文件、Web 搜索、MCP），Agent 是工具的使用者。

持久化：记忆（memory）、技能（skills）、定时任务（cron），支持长期协作。

2.2 核心架构

会话驱动：基于对话的交互模式，用户输入 → Agent 处理 → 工具调用 → 返回结果。

技能系统：SKILL.md 格式的可插拔能力，YAML frontmatter + Markdown 正文。

记忆机制：

短期：会话历史（context window）
长期：memory（事实）+ skills（流程）

工具集：

终端：执行 shell 命令
文件：读写、搜索、编辑
Web：搜索、访问 API
MCP：Model Context Protocol，扩展工具

2.3 能力边界

擅长：

个人助理（日程、笔记、邮件）
知识管理（Obsidian、Git、文档）
自动化脚本（定时任务、监控告警）

局限：

多 Agent 协作（仅支持 delegate_task，功能有限）
复杂状态管理（无状态机，依赖会话历史）
长期任务（无任务队列，依赖 cron）

2.4 使用场景

个人知识管理：Obsidian 同步、博客写作、知识检索。

自动化运维：定时任务（cron）、监控告警、脚本执行。

技术写作：选题推荐、草稿生成、内容同步。

2.5 Hermes 源码解构

2.5.1 核心类分析

Agent：主循环，处理用户输入和工具调用。

# 简化版 Hermes Agent 核心逻辑
class Agent:
    async def run(self, user_input: str) -> str:
        # 1. 加载上下文（技能 + 记忆）
        context = self.load_context()
        
        # 2. 调用 LLM
        response = await self.llm.chat(
            messages=[{"role": "user", "content": user_input}],
            tools=self.available_tools,
            context=context
        )
        
        # 3. 解析工具调用
        tool_calls = self.parse_tool_calls(response)
        
        # 4. 执行工具（支持并行）
        results = await self.execute_tools(tool_calls)
        
        # 5. 将结果回喂给 LLM
        final_response = await self.llm.chat(
            messages=[
                {"role": "user", "content": user_input},
                {"role": "assistant", "tool_calls": tool_calls},
                {"role": "tool", "content": results}
            ]
        )
        
        return final_response.content

Tool：工具抽象，统一接口。

from abc import ABC, abstractmethod

class Tool(ABC):
    name: str
    description: str
    parameters: Dict  # JSON Schema
    
    @abstractmethod
    async def execute(self, **kwargs) -> str:
        """执行工具，返回结果"""
        pass

# 示例：终端工具
class TerminalTool(Tool):
    name = "terminal"
    description = "执行 shell 命令"
    
    async def execute(self, command: str, timeout: int = 180) -> str:
        import subprocess
        result = subprocess.run(
            command, shell=True, capture_output=True, 
            text=True, timeout=timeout
        )
        return f"stdout: {result.stdout}\nstderr: {result.stderr}"

Memory：记忆管理。

class Memory:
    def __init__(self):
        self.user_memory = []  # 用户偏好
        self.system_memory = []  # 系统笔记
    
    def add(self, target: str, content: str):
        """添加记忆"""
        if target == "user":
            self.user_memory.append(content)
        else:
            self.system_memory.append(content)
    
    def load_context(self) -> str:
        """加载上下文"""
        return f"User Memory:\n{'\n'.join(self.user_memory)}\n\nSystem Memory:\n{'\n'.join(self.system_memory)}"

SkillLoader：技能加载器。

import yaml
from pathlib import Path

class SkillLoader:
    def load_skill(self, name: str) -> Dict:
        skill_path = Path(f"~/.hermes/skills/{name}/SKILL.md").expanduser()
        content = skill_path.read_text()
        
        # 解析 frontmatter
        if content.startswith("---"):
            end = content.find("---", 3)
            frontmatter = yaml.safe_load(content[3:end])
            body = content[end+3:].strip()
            return {**frontmatter, "content": body}
        
        return {"name": name, "content": content}

2.5.2 关键设计模式

命令模式：工具调用作为命令对象，便于日志记录和重试。

class ToolCommand:
    def __init__(self, tool: Tool, args: Dict):
        self.tool = tool
        self.args = args
    
    async def execute(self) -> str:
        return await self.tool.execute(**self.args)

策略模式：不同的模型提供者（OpenAI/Anthropic/Custom）。

class ModelProvider(ABC):
    @abstractmethod
    async def chat(self, messages: List[Dict], tools: List[Dict]) -> str:
        pass

class OpenAIProvider(ModelProvider):
    async def chat(self, messages, tools):
        # OpenAI API 实现
        pass

class AnthropicProvider(ModelProvider):
    async def chat(self, messages, tools):
        # Anthropic API 实现
        pass

观察者模式：工具调用的事件通知。

class ToolEventBus:
    def __init__(self):
        self.listeners = []
    
    def on_tool_call(self, listener):
        self.listeners.append(listener)
    
    async def notify(self, tool_name: str, args: Dict, result: str):
        for listener in self.listeners:
            await listener(tool_name, args, result)

OpenCLAW 框架深度解析

3.1 设计哲学

Agent 优先：自主 Agent 协作，人类只需定义目标，Agent 自动分解和执行任务。

状态机驱动：明确的状态流转（待处理→执行中→完成），支持复杂任务管理。

可扩展性：插件化设计，支持自定义 Agent 类型和协作策略。

3.2 核心架构

多 Agent 协作：

主管 - 工人模式（Orchestrator-Worker）
投票共识（Voting）
流水线协作（Pipeline）

状态管理：基于状态机的任务流转，支持断点续传。

工具调用：类似 LangChain 的工具抽象，需自行实现。

持久化：任务状态、执行历史，支持恢复和审计。

3.3 能力边界

擅长：

复杂任务分解（自动拆分为子任务）
多 Agent 协作（主管 - 工人、投票）
长期任务（任务队列、状态持久化）

局限：

个人助理场景（缺乏即时交互）
工具丰富度（需自行实现）
学习曲线（需理解状态机、多 Agent 模式）

3.4 使用场景

企业级工作流自动化：需要多角色协作的复杂流程。

复杂数据分析任务：多步骤分析，需要中间状态。

需要多角色协作的场景：如代码审查（作者 + 审查者 + 合并者）。

3.5 OpenCLAW 源码解构

3.5.1 核心类分析

Agent 基类：定义 Agent 的接口。

# 简化版 OpenCLAW Agent 基类
from abc import ABC, abstractmethod
from typing import List, Dict

class Agent(ABC):
    name: str
    role: str
    tools: List[Tool]
    
    @abstractmethod
    def plan(self, task: str) -> Plan:
        """制定计划"""
        pass
    
    @abstractmethod
    def execute(self, plan: Plan) -> Result:
        """执行计划"""
        pass
    
    @abstractmethod
    def communicate(self, message: str, from_agent: str) -> str:
        """与其他 Agent 通信"""
        pass

Orchestrator：主管 Agent，负责任务分解和分配。

class Orchestrator(Agent):
    def __init__(self, workers: List[Agent]):
        super().__init__(name="orchestrator", role="task_manager")
        self.workers = workers
    
    def decompose(self, task: str) -> List[SubTask]:
        """将大任务分解为子任务"""
        # 使用 LLM 分解任务
        plan_prompt = f"""
        任务：{task}
        
        请将任务分解为多个子任务，每个子任务应：
        1. 可独立执行
        2. 有明确的输入输出
        3. 可分配给不同 Agent
        
        输出格式：JSON 数组
        """
        subtasks = self.llm.generate(plan_prompt)
        return [SubTask(**st) for st in subtasks]
    
    def assign(self, tasks: List[SubTask]):
        """将子任务分配给工人 Agent"""
        for task in tasks:
            # 根据任务类型选择最合适的 Agent
            worker = self.select_worker(task)
            worker.execute_task(task)

Worker：工人 Agent，负责执行具体子任务。

class Worker(Agent):
    def __init__(self, name: str, specialty: str):
        super().__init__(name=name, role=specialty)
        self.specialty = specialty
    
    def can_handle(self, task: SubTask) -> bool:
        """判断是否能处理该任务"""
        return task.type == self.specialty
    
    def execute_task(self, task: SubTask) -> Result:
        """执行任务"""
        # 1. 制定计划
        plan = self.plan(task.description)
        
        # 2. 执行工具调用
        results = []
        for step in plan.steps:
            if step.requires_tool:
                result = self.execute_tool(step.tool, step.args)
                results.append(result)
        
        # 3. 返回结果
        return Result(
            task_id=task.id,
            status="completed",
            output="\n".join(results)
        )

State：状态管理。

from enum import Enum

class TaskStatus(Enum):
    PENDING = "pending"
    IN_PROGRESS = "in_progress"
    COMPLETED = "completed"
    FAILED = "failed"

class TaskState:
    def __init__(self):
        self.tasks: Dict[str, Dict] = {}
    
    def create_task(self, task_id: str, description: str) -> Dict:
        """创建任务"""
        task = {
            "id": task_id,
            "description": description,
            "status": TaskStatus.PENDING,
            "subtasks": [],
            "history": []
        }
        self.tasks[task_id] = task
        return task
    
    def update_status(self, task_id: str, status: TaskStatus):
        """更新任务状态"""
        task = self.tasks[task_id]
        task["status"] = status
        task["history"].append({
            "timestamp": datetime.now(),
            "status": status.value
        })
    
    def get_task(self, task_id: str) -> Dict:
        """获取任务状态"""
        return self.tasks.get(task_id)

3.5.2 关键设计模式

工厂模式：创建不同类型的 Agent。

class AgentFactory:
    @staticmethod
    def create_agent(agent_type: str, **kwargs) -> Agent:
        if agent_type == "orchestrator":
            return Orchestrator(**kwargs)
        elif agent_type == "worker":
            return Worker(**kwargs)
        elif agent_type == "voter":
            return VoterAgent(**kwargs)
        else:
            raise ValueError(f"Unknown agent type: {agent_type}")

观察者模式：Agent 间的事件通知。

class AgentEventBus:
    def __init__(self):
        self.subscribers: Dict[str, List[Callable]] = {}
    
    def subscribe(self, event_type: str, callback: Callable):
        """订阅事件"""
        if event_type not in self.subscribers:
            self.subscribers[event_type] = []
        self.subscribers[event_type].append(callback)
    
    async def publish(self, event_type: str, data: Dict):
        """发布事件"""
        for callback in self.subscribers.get(event_type, []):
            await callback(data)

# 使用示例
event_bus = AgentEventBus()

async def on_task_completed(data):
    print(f"Task {data['task_id']} completed!")

event_bus.subscribe("task.completed", on_task_completed)

策略模式：不同的协作策略。

class CollaborationStrategy(ABC):
    @abstractmethod
    async def collaborate(self, agents: List[Agent], task: str) -> Result:
        pass

class OrchestratorStrategy(CollaborationStrategy):
    async def collaborate(self, agents, task):
        """主管 - 工人模式"""
        orchestrator = agents[0]
        workers = agents[1:]
        return await orchestrator.execute(task, workers)

class VotingStrategy(CollaborationStrategy):
    async def collaborate(self, agents, task):
        """投票共识模式"""
        results = await asyncio.gather(*[
            agent.execute(task) for agent in agents
        ])
        return self.majority_vote(results)

底层逻辑对比

4.1 核心抽象差异

Hermes：User ↔ Agent ↔ Tools（单 Agent 多工具）

一个 Agent，多个工具
人类在控制回路中
即时交互，对话式

OpenCLAW：Orchestrator ↔ Workers ↔ Tools（多 Agent 协作）

多个 Agent，分工协作
人类只需定义目标
任务队列，异步执行

4.2 状态管理对比

Hermes：

会话状态：消息历史（context window）
持久记忆：memory（事实）+ skills（流程）
无状态机，依赖 LLM 理解上下文

OpenCLAW：

任务状态：状态机（PENDING → IN_PROGRESS → COMPLETED）
执行历史：任务日志、子任务状态
支持断点续传、任务恢复

4.3 工具系统对比

Hermes：

内置工具丰富：terminal/file/web_search/MCP
工具即服务：无需自行实现
扩展方式：MCP 协议、自定义工具

OpenCLAW：

工具抽象类似 LangChain
需自行实现工具逻辑
扩展方式：继承 Tool 基类

4.4 扩展机制对比

Hermes：SKILL.md（Markdown + YAML frontmatter）

---
name: git-automation
title: Git 自动化
description: 自动化 Git 工作流
---

# Git 自动化技能

## 能力范围
- 提交代码
- 推送远程
- 创建分支

## 工具调用
- `git_commit(message)`
- `git_push(remote, branch)`

OpenCLAW：Python 类继承（需编码）

class GitAutomationAgent(Worker):
    def __init__(self):
        super().__init__(name="git-automation", specialty="git")
    
    def execute_task(self, task: SubTask) -> Result:
        if task.type == "commit":
            return self.git_commit(task.message)
        elif task.type == "push":
            return self.git_push(task.remote, task.branch)

4.5 设计哲学差异

| 维度 | Hermes | OpenCLAW | |------|--------|----------| | 核心理念 | Human-in-the-loop | Autonomous | | 交互模式 | 对话式（即时） | 任务队列（异步） | | 状态管理 | 会话历史 | 状态机 | | 工具系统 | 内置丰富 | 需自行实现 | | 扩展方式 | SKILL.md（无代码） | Python 类（需编码） | | 适用场景 | 个人助理、即时交互 | 企业工作流、复杂任务 |

能力对比矩阵

5.1 功能对比表

| 能力 | Hermes | OpenCLAW | |------|--------|----------| | 人机交互 | ✅ 优秀（对话式） | ⚠️ 有限（任务队列） | | 多 Agent 协作 | ⚠️ 有限（delegate_task） | ✅ 优秀（主管 - 工人/投票） | | 状态管理 | ⚠️ 简单（会话历史） | ✅ 复杂（状态机） | | 工具丰富度 | ✅ 丰富（内置 + MCP） | ⚠️ 中等（需自行实现） | | 持久化 | ✅ 完善（memory/skills） | ✅ 完善（任务状态） | | 自动化 | ✅ 定时任务（cron） | ⚠️ 需外部触发 | | 学习曲线 | 上手快，精通需时间 | 上手慢，精通后灵活 | | 扩展性 | SKILL.md（无代码） | Python 类（需编码） |

5.2 性能对比

响应速度：

Hermes：即时（对话式，单次 LLM 调用）
OpenCLAW：较慢（任务队列，多次 LLM 调用）

资源消耗：

Hermes：轻量（单 Agent，少状态）
OpenCLAW：较重（多 Agent，状态持久化）

扩展性：

Hermes：技能系统（无代码，易上手）
OpenCLAW：插件系统（需编码，灵活）

5.3 学习曲线

Hermes：

上手快：对话式交互，无需编程
精通需时间：理解技能系统、记忆机制、工具调用

OpenCLAW：

上手慢：需理解状态机、多 Agent 模式、Python 编程
精通后灵活：可自定义 Agent 类型、协作策略、工具系统

实战场景对比

6.1 场景 1：个人知识管理

需求：Obsidian 同步、博客写作、知识检索。

Hermes：

✅ 即时交互：随时询问、检索、同步
✅ 工具丰富：文件读写、Git 操作、Web 搜索
✅ 记忆持久：记住用户偏好、写作风格

OpenCLAW：

❌ 不适合：需要持续的人机交互，而非任务队列
❌ 工具有限：需自行实现文件、Git 工具

6.2 场景 2：自动化运维

需求：定时任务、监控告警、脚本执行。

Hermes：

✅ 定时任务：cron 支持，自动执行
✅ 工具丰富：terminal/file/web_search
✅ 即时反馈：执行结果即时返回

OpenCLAW：

⚠️ 需外部触发：无内置定时任务
✅ 复杂流程：多步骤任务分解
⚠️ 异步执行：任务队列，非即时

推荐：简单用 Hermes，复杂用 OpenCLAW

6.3 场景 3：数据分析

需求：多步骤分析，需要中间状态。

Hermes：

✅ 单次分析：即时查询、简单统计
❌ 多步骤：依赖会话历史，易丢失状态

OpenCLAW：

✅ 多步骤：状态机管理，支持中间状态
✅ 任务分解：自动拆分为子任务（数据清洗→分析→可视化）
✅ 持久化：任务状态可恢复

6.4 场景 4：企业工作流

需求：多角色协作（如代码审查：作者→审查者→合并者）。

Hermes：

❌ 不适合：缺乏多 Agent 协作能力
❌ 无状态机：无法管理复杂流程

OpenCLAW：

✅ 多 Agent：主管 - 工人模式
✅ 状态管理：明确的状态流转
✅ 可扩展：自定义 Agent 类型（作者/审查者/合并者）

选型决策树

7.1 决策流程图

需要多 Agent 协作？
├─ 是 → OpenCLAW
└─ 否 → 需要即时交互？
    ├─ 是 → Hermes
    └─ 否 → 需要复杂状态管理？
        ├─ 是 → OpenCLAW
        └─ 否 → Hermes

7.2 关键问题清单

是否需要多 Agent 协作？
- 是 → OpenCLAW
- 否 → 继续
是否需要即时交互（而非任务队列）？
- 是 → Hermes
- 否 → 继续
是否需要复杂状态管理（状态机）？
- 是 → OpenCLAW
- 否 → 继续
是否需要丰富的内置工具？
- 是 → Hermes
- 否 → 继续
是否需要定时任务/自动化？
- 是 → Hermes
- 否 → 两者皆可

7.3 混合方案

Hermes + OpenCLAW：

Hermes 做日常助理（即时交互、工具调用）
OpenCLAW 处理复杂任务（多 Agent 协作、状态管理）

Hermes + LangGraph：

Hermes 做交互（对话式、工具调用）
LangGraph 做状态管理（状态机、任务流转）

总结与建议

8.1 核心结论

Hermes：

✅ 个人助理、即时交互、工具丰富
✅ 上手快、无代码扩展、定时任务
❌ 多 Agent 协作有限、状态管理简单

OpenCLAW：

✅ 多 Agent 协作、状态管理、企业级
✅ 灵活扩展、任务持久化、复杂流程
❌ 上手慢、需编程、工具需自行实现

8.2 学习建议

初学者：

从 Hermes 开始，理解 Agent 基础
熟悉工具调用、技能系统、记忆机制

进阶者：

学习 OpenCLAW，掌握多 Agent 协作
理解状态机、任务分解、协作策略

专家：

根据场景选择，甚至混合使用
自定义框架，结合两者优势

8.3 未来展望

Hermes：

可能增强多 Agent 协作能力（delegate_task 升级）
可能引入状态机（复杂任务管理）

OpenCLAW：

可能增强人机交互体验（对话式接口）
可能内置更多工具（减少自行实现）

融合趋势：

两者的设计思想可能互相借鉴
未来可能出现"对话式多 Agent"框架

资源与延伸阅读

9.1 官方文档

Hermes：https://hermes-agent.nousresearch.com/docs
OpenCLAW：https://github.com/open-claw/open-claw

9.2 相关博文

9.3 社区与讨论

Hermes：Discord 社区、GitHub Issues
OpenCLAW：GitHub Discussions、技术论坛

相关文章：

LLM 应用评估体系设计：指标、工具与自动化

Thu, 16 Jul 2026 00:00:00 GMT

LLM 应用评估体系设计：指标、工具与自动化

引言：为什么需要专门的评估体系

1.1 LLM 应用与传统软件的根本差异

传统软件测试有一个基本假设：相同输入必然得到相同输出。但 LLM 应用打破了这个假设：

非确定性输出：即使输入完全相同，LLM 也可能给出不同回答。温度参数（temperature）控制随机性，但即使 temperature=0，不同模型、不同版本、甚至同一模型的不同调用，输出也可能有细微差异。

概率性错误：传统软件是"对/错"二元判断，LLM 是"好/更好/最好"的连续谱。一个回答可能"基本正确但有细节错误"，或者"方向正确但表述不清"。如何量化这种模糊性？

上下文依赖：LLM 的效果受历史对话、系统提示、few-shot 示例等多重因素影响。单独测试某个 Prompt 可能效果很好，但放到完整对话流程中就可能失效。

1.2 缺少验收标准的后果

我们团队在 AskBI 项目中踩过这些坑：

上线即翻车：测试环境用 50 个精心设计的问答对，准确率 95%。上线后真实用户提问，准确率掉到 70%。原因：测试数据没有覆盖真实场景的多样性。

无法量化改进：优化 Prompt 后，产品说"感觉更好了"，但无法证明。A/B 测试需要 2 周才能看到统计显著性，迭代太慢。

责任边界模糊：效果差时，模型团队说是数据问题，数据团队说是工程问题，工程团队说是模型问题。没有分层指标，无法定位问题层级。

1.3 评估体系的核心目标

可量化：每个层级都有明确指标，不是"感觉好"而是"准确率达到 92%"。

可复现：测试结果可以重复验证，不是"今天好明天差"。

可自动化：减少人工评估成本，支持持续集成和快速迭代。

评估体系设计原则

2.1 分层评估

LLM 应用通常有 3 个层级，每层关注点不同：

Prompt 层：单个交互的质量。关注回答的准确性、相关性、完整性。

RAG 层：检索与生成的协同。关注检索结果的召回率、生成内容的忠实度。

Agent 层：任务完成与工具调用。关注任务成功率、工具选择准确率、状态管理。

2.2 指标设计原则

可测量：必须有明确的计算方法，不能是主观判断。

有意义：与业务目标对齐，不是"为了测而测"。

可行动：指标异常时知道如何改进，不是"只能看不能改"。

2.3 测试数据设计

基准数据集：覆盖典型场景的固定测试集，用于版本对比。

边界案例：极端输入、模糊需求、对抗样本，用于压力测试。

真实数据：生产环境采样，持续更新，用于发现长尾问题。

Prompt 层级的评估指标

3.1 核心指标

准确率（Accuracy）：回答正确的比例。适合有明确答案的场景（如数学题、事实查询）。

相关性（Relevance）：回答与问题的相关程度，通常用 1-5 分人工评分。适合开放性问题。

完整性（Completeness）：是否覆盖问题的所有子问题。适合复杂问题（如"分析 A 并给出 B 建议"）。

一致性（Consistency）：多次调用的输出稳定性。相同问题调用 5 次，输出语义一致的比例。

3.2 测试方法

黄金测试集：准备 50-100 个标准问答对，覆盖典型场景。

人工评分：3 人独立评分，取平均值，减少个人偏差。

自动化评估：用另一个 LLM 作为评判模型（LLM-as-a-Judge），但需要定期人工抽检校准。

3.3 合格标准示例

准确率 ≥ 90%
相关性 ≥ 4.0/5.0
完整性 ≥ 85%
一致性 ≥ 80%（相同问题 5 次调用，输出语义一致的比例）

3.4 常见问题与调优方向

准确率低 → 优化系统提示、增加 Few-shot 示例、调整模型温度。

相关性低 → 调整温度参数、优化问题重写、增加上下文。

完整性低 → 在 Prompt 中明确要求"分点回答"、"覆盖所有子问题"。

一致性低 → 降低温度（如 0.1）、增加随机种子控制、简化输出格式。

RAG 层级的评估指标

4.1 检索质量指标

召回率（Recall@K）：正确答案是否在前 K 个检索结果中。K 通常取 5 或 10。

精确率（Precision@K）：前 K 个结果中有多少是相关的。

MRR（Mean Reciprocal Rank）：正确答案的排名倒数平均值。排名越靠前，分数越高。

NDCG（Normalized DCG）：考虑排名位置的加权评分，排名越靠前权重越大。

4.2 生成质量指标

忠实度（Faithfulness）：生成内容是否基于检索到的上下文，不编造信息。

答案相关性（Answer Relevance）：最终答案与问题的相关程度。

上下文利用率（Context Utilization）：检索内容被引用的比例，避免检索了大量但只用了一部分。

4.3 端到端指标

答案准确率：最终答案是否正确，综合检索和生成的效果。

拒绝率：无法回答时的拒绝比例。应控制在合理范围（如 5-10%），太高说明检索能力不足，太低可能产生幻觉。

幻觉率：生成内容中事实错误的比例，应尽可能低（< 5%）。

4.4 测试方法

检索测试：固定问题集，评估检索结果质量，不关心生成。

生成测试：固定检索结果，评估生成质量，不关心检索。

端到端测试：完整流程，评估最终答案，反映真实效果。

4.5 合格标准示例

Recall@5 ≥ 95%
Precision@3 ≥ 80%
MRR ≥ 0.85
忠实度 ≥ 90%
幻觉率 ≤ 5%

4.6 常见问题与调优方向

召回率低 → 优化分块策略（chunk size）、增加嵌入维度、调整相似度阈值。

精确率低 → 优化重排序（Re-ranking）、增加元数据过滤、调整 Top-K。

忠实度低 → 在 Prompt 中强调"仅基于上下文回答"、"不知道就说不知道"。

幻觉率高 → 增加引用要求（"请标注信息来源"）、设置置信度阈值、过滤低分结果。

Agent 层级的评估指标

5.1 任务完成指标

任务成功率（Task Success Rate）：任务最终完成的比例。Agent 的核心指标。

步骤准确率（Step Accuracy）：每一步工具调用的正确率。定位哪一步容易出错。

平均步骤数（Average Steps）：完成任务所需的平均工具调用次数。越少越好，但不应以牺牲成功率为代价。

超时率（Timeout Rate）：超过最大步骤数仍未完成的比例。反映任务复杂度或 Agent 规划能力。

5.2 工具调用指标

工具选择准确率：选择正确工具的比例。Agent 需要理解"用什么工具做什么事"。

参数准确率：工具参数的正确率。选对工具但参数错误，任务仍会失败。

工具执行成功率：工具调用成功（无异常）的比例。反映工具稳定性和参数格式。

冗余调用率：不必要的工具调用比例。如重复查询、无效尝试。

5.3 状态管理指标

状态一致性：多轮对话中状态维护的正确性。如"记住用户之前选的选项"。

错误恢复率：遇到错误后成功恢复的比例。反映容错能力。

人工介入率：需要人类协助的比例。越低越好，但关键任务需要人工确认。

5.4 测试方法

场景测试：设计典型任务场景（如"创建环境并部署"），覆盖完整流程。

压力测试：复杂任务、多步骤、边界条件，测试极限能力。

对抗测试：故意提供错误信息、模糊需求，测试鲁棒性。

5.5 合格标准示例

任务成功率 ≥ 85%
步骤准确率 ≥ 90%
平均步骤数 ≤ 预期步骤数 × 1.5
超时率 ≤ 10%
工具选择准确率 ≥ 95%
人工介入率 ≤ 15%

5.6 常见问题与调优方向

任务成功率低 → 优化技能设计（更清晰的工具描述）、增加错误处理、降低任务复杂度。

步骤准确率低 → 改进工具描述（更详细的参数说明）、增加 Few-shot 示例、优化系统提示。

冗余调用高 → 优化系统提示（"避免重复调用"）、增加状态记忆、合并相似工具。

人工介入率高 → 明确任务边界（"哪些能做哪些不能"）、增加确认环节（关键操作前让用户确认）。

自动化测试框架设计

6.1 框架架构

测试数据层（JSON/CSV）
    ↓
测试执行层（并发调用、结果收集）
    ↓
评估层（指标计算、阈值判断）
    ↓
报告层（可视化、趋势分析）

6.2 核心组件

测试数据管理：版本化（Git）、分类（Prompt/RAG/Agent）、标签（场景/难度）。

测试执行器：支持并发（提高速度）、限流（避免超限）、重试（处理临时失败）。

评估引擎：指标计算（准确率/召回率等）、阈值判断（是否合格）、异常告警。

报告生成器：HTML/PDF 报告、图表可视化（趋势图/分布图）、邮件通知。

6.3 实现示例（Python）

from dataclasses import dataclass
from typing import List, Dict
import json

@dataclass
class TestCase:
    id: str
    input: str
    expected: str  # 期望输出或评估标准
    layer: str  # prompt/rag/agent
    tags: List[str]

class LLMTestSuite:
    def __init__(self, test_data_path: str, model_config: Dict):
        self.test_cases = self.load_test_cases(test_data_path)
        self.model = LLMClient(model_config)
        
    def load_test_cases(self, path: str) -> List[TestCase]:
        with open(path) as f:
            data = json.load(f)
        return [TestCase(**case) for case in data]
    
    def run_prompt_tests(self) -> Dict:
        results = []
        for case in self.filter_by_layer('prompt'):
            output = self.model.generate(case.input)
            score = self.evaluate_prompt_output(output, case.expected)
            results.append({
                'case_id': case.id,
                'score': score,
                'output': output
            })
        return self.calculate_metrics(results)
    
    def evaluate_prompt_output(self, output: str, expected: str) -> float:
        # 可以用另一个 LLM 作为评判模型
        judge_prompt = f"""
        问题：{expected['question']}
        期望答案：{expected['answer']}
        实际输出：{output}
        
        请评分（0-1 分）：
        """
        judge_output = self.judge_model.generate(judge_prompt)
        return self.extract_score(judge_output)
    
    def calculate_metrics(self, results: List[Dict]) -> Dict:
        scores = [r['score'] for r in results]
        return {
            'accuracy': sum(scores) / len(scores),
            'pass_rate': sum(1 for s in scores if s >= 0.8) / len(scores),
            'total_cases': len(results)
        }

6.4 持续集成

Git Hook：提交前运行快速测试（如 10 个核心用例），防止明显回归。

CI Pipeline：每次 PR 运行完整测试（如 50-100 个用例），生成报告附在 PR 中。

定时任务：每日/每周运行全量测试（如 200+ 用例），跟踪长期趋势，发现退化。

工具链与资源

7.1 开源工具

RAGAS：RAG 评估框架，提供忠实度、相关性、召回率等指标。支持自动化评估。

TruLens：LLM 应用评估平台，支持多指标、可视化、A/B 测试。

LangSmith：LangChain 官方评估工具，集成度高，支持追踪和调试。

DeepEval：通用 LLM 评估库，支持多种指标和自定义评估函数。

7.2 自建工具

基准数据集管理：版本化（Git）、标注工具（Label Studio）、去重和平衡。

自动化评分器：LLM-as-a-Judge 实现，定期人工校准，避免评判模型偏差。

可视化看板：指标趋势（时间序列）、分布图（分数分布）、异常告警（邮件/钉钉）。

7.3 推荐配置

# test_config.yaml
test_config:
  prompt:
    temperature: 0.1  # 低温度，提高一致性
    max_tokens: 512
    top_p: 0.9
    
  rag:
    top_k: 5
    similarity_threshold: 0.7
    rerank: true
    
  agent:
    max_steps: 128
    timeout_seconds: 300
    retry_count: 3
    
  evaluation:
    judge_model: "gpt-4-turbo"  # 评判模型
    human_sample_rate: 0.1  # 10% 人工抽检
    alert_threshold:
      accuracy_drop: 0.05  # 准确率下降 5% 告警
      timeout_rate: 0.15  # 超时率超过 15% 告警

实战案例：AskBI 智能问答评估

8.1 项目背景

AskBI 是企业级 BI 智能问答系统，用户可以用自然语言查询业务指标（如"上个月销售额是多少"）。

技术架构：RAG + Agent

RAG：检索指标文档、SQL 模板
Agent：生成 SQL、执行查询、解释结果

挑战：需要支持 100+ 个业务指标，指标定义复杂（如"活跃用户"有多种定义），SQL 生成容易出错。

8.2 评估体系设计

Prompt 层：

SQL 生成准确率：生成的 SQL 是否正确
自然语言理解准确率：是否正确理解用户意图

RAG 层：

指标文档召回率：是否能找到相关指标定义
SQL 模板匹配率：是否能找到合适的 SQL 模板

Agent 层：

多步查询成功率：复杂查询（如"对比上个月和今年"）的成功率
工具调用准确率：选择正确工具（查询/计算/可视化）

8.3 测试结果（第 4 版）

Prompt 层：
  - SQL 生成准确率：92%
  - 自然语言理解准确率：88%
  
RAG 层：
  - 指标文档召回率@5：96%
  - SQL 模板匹配率：85%
  
Agent 层：
  - 多步查询成功率：82%
  - 工具调用准确率：94%
  - 平均步骤数：3.2（预期 2-4 步）

8.4 优化迭代

第 1 版 → 第 2 版：准确率从 77% 提升到 92%（+15%）

优化 Prompt：增加 Few-shot 示例、明确 SQL 格式要求
增加指标文档：补充 20 个常见指标的详细说明

第 2 版 → 第 3 版：召回率从 86% 提升到 96%（+10%）

优化分块策略：从固定 500 字符改为按语义分块
增加重排序：用 Cross-Encoder 对检索结果重排序

第 3 版 → 第 4 版：任务成功率从 74% 提升到 82%（+8%）

增加错误处理：SQL 执行失败时尝试修复或换方案
优化状态管理：记住用户之前的筛选条件

总结与最佳实践

9.1 核心要点回顾

分层评估：Prompt/RAG/Agent 各有侧重，不能混为一谈。

指标设计：可测量、有意义、可行动，不是"为了测而测"。

自动化：减少人工成本，支持持续集成和快速迭代。

9.2 最佳实践清单

[ ] 建立基准数据集（至少 50 个测试用例，覆盖典型场景）
[ ] 定义合格标准（每个层级都有明确阈值，如准确率≥90%）
[ ] 自动化测试流程（CI/CD 集成，每次提交自动运行）
[ ] 定期人工抽检（防止自动化偏差，如 10% 抽样）
[ ] 持续跟踪趋势（发现退化及时告警，如准确率下降 5%）

9.3 常见陷阱

过度依赖自动化：LLM-as-a-Judge 也有偏差，需定期人工校准。

测试数据偏差：基准数据集不能覆盖所有场景，需持续补充真实数据。

指标游戏：优化指标不等于优化体验，需关注真实用户反馈（如满意度调查）。

9.4 下一步行动

评估当前项目：测试覆盖度如何？哪些层级缺少评估？
选择一个层级开始：从 Prompt 层开始最简单，逐步扩展到 RAG 和 Agent。
建立基准数据集：收集 50-100 个典型用例，版本化管理。
自动化测试流程：集成到 CI/CD，每次提交自动运行。
持续迭代优化：根据测试结果调整 Prompt、检索策略、技能设计。

相关文章：

[[LangGraph 复杂状态机设计模式]]
[[LLM 在垂直领域的微调策略]]
[[轻量级 Agent 开发方案：基于 Skill 插件的工具调用循环]]

Ansible UI 部署工作台设计复盘：从 CLI 到 Agent 技能系统

Fri, 10 Jul 2026 00:00:00 GMT

Ansible UI 部署工作台设计复盘：从 CLI 到 Agent 技能系统

引言：为什么需要 UI？

公司内部现状

2024 年初，我们团队面临一个典型困境：

10+ 个环境：开发、测试、预发布、生产，每个环境 3-5 台服务器
5+ 个服务：AskBI、LangChain 应用、Milvus 向量库、MinIO 对象存储、前端服务
3 个运维同事：每人维护 2-3 个环境，频繁切换
零文档：部署流程靠口口相传，新人入职 1 周学不会

核心痛点：

"每次部署都要查笔记、翻 Slack 记录、问老同事。同一个操作，三个人有三种写法。"

CLI 的局限性

Ansible 本身是优秀的自动化工具，但CLI 不是产品：

| 问题 | 表现 | 影响 | |------|------|------| | 学习门槛高 | 新人需要懂 YAML、SSH、网络、容器 | 入职培训 2 周+ | | 无状态 | 每次执行都是独立的，无法追溯历史 | 故障排查困难 | | 无协作 | 多人同时部署容易冲突 | 生产事故风险 | | 无可视化 | 日志是纯文本，无法快速定位问题 | 排查效率低 | | 无权限 | 要么全权，要么无权 | 安全边界模糊 |

为什么没有官方工具？

Ansible Tower / AWX 是官方解决方案，但不适合我们：

太重：需要独立集群，维护成本高
太通用：我们的部署流程高度定制化（私有化交付、离线包、特殊网络）
太贵：Tower 企业版 License 费用不菲
不够灵活：我们的环境模型（env + config + job）与 Tower 的 inventory + playbook 不匹配

结论：我们需要一个轻量级、定制化、产品化的部署工作台。

Phase 1-2：从脚本到工作台（2024 Q2）

初始设计

目标：把散落在脚本、笔记、Slack 中的部署流程，整合成一个可重复使用的工作台。

核心模型：

环境 (Environment)
├── 库存 (Inventory)：服务器列表、SSH 配置
├── 配置 (Config)：main.yml、hosts.yml、.env
├── 作业 (Job)：部署历史、日志、产物
└── 动作 (Action)：check、deploy、clean、rollback

设计原则：

环境是核心边界：所有数据（库存、配置、日志）都挂到环境
高频操作优先：环境选择、配置编辑、执行部署、查看日志
复用既有组件：文件管理、配置版本沿用已有交互，减少新模型

技术选型

| 层级 | 技术 | 理由 | |------|------|------| | 前端 | React + TypeScript + Ant Design | 团队熟悉，组件丰富 | | 后端 | FastAPI + Python | 与 Ansible 生态无缝集成 | | 执行器 | Ansible shell 通道 | 复用既有 SSH 能力，无需引 paramiko | | 存储 | 文件系统 + JSONL | 轻量，无需数据库 | | 部署 | Docker Compose | 与目标环境一致 |

关键决策

Q：为什么不直接用 Ansible API？

A：Ansible 的 Python API 太重，且绑定特定版本。我们用shell 通道（ansible <env> -m shell -a "<cmd>"）作为执行层，好处：

版本无关：任何 Ansible 版本都能用
权限复用：直接用 ~/.ssh/config 的 ProxyJump、别名
日志透明：stdout/stderr 直接返回，无需额外解析

Q：为什么不引入数据库？

A：初期数据量小（< 100 个环境，< 1000 个作业），文件系统 + JSONL 足够：

开发快：无需 ORM、迁移
调试易：直接 cat 文件就能看数据
部署简：Docker volume 挂载即可持久化

Phase 3-4：用户体验与协作（2024 Q3-Q4）

用户反馈

上线 3 个月后，收集到 5 个核心问题：

| # | 问题 | 根因 | 影响 | |---|------|------|------| | 1 | 任务列表不跟随选中环境 | Jobs 页用独立 state，与全局环境无联动 | 用户频繁切环境，容易误操作 | | 2 | 多人共用 admin 账号 | 无审计、无并发控制 | 无法追溯谁做了什么 | | 3 | 登录态不稳定（常显示 guest） | 异步加载期间按 guest 渲染 | 用户以为没权限，放弃操作 | | 4 | 环境选择在 tab 间不一致 | selectedEnv 不持久化，刷新丢失 | 每次刷新都要重新选环境 | | 5 | Agent 页会话历史串环境 | Agent 的 env 是局部 state | 切环境后看到别人的会话 |

解决方案

统一状态管理：

// 之前：每个页面独立 state
const [selectedEnv, setSelectedEnv] = useState("");
const [jobFilters, setJobFilters] = useState({ env: "" });

// 之后：全局 Provider + URL 参数
const { env, setEnv } = useGlobalEnv(); // 持久化到 localStorage + URL ?env=xxx

操作者标识：

# 每条任务记录客户端 IP + User-Agent
task = {
    "env": env_name,
    "action": "deploy",
    "operator": f"{request.client.host} ({request.headers.get('User-Agent', 'Unknown')})",
    "timestamp": datetime.now(),
    "status": "running"
}

登录态三态：

type AuthState = "unknown" | "admin" | "guest";

// 加载中显示 loading，不按 guest 渲染
const [auth, setAuth] = useState<AuthState>("unknown");

效果

✅ 环境一致性：所有 tab 统一消费全局环境，刷新不丢失
✅ 操作可追溯：每条任务记录 IP + UA，至少知道是谁的机器
✅ 登录稳定：三态管理，加载中不降级为 guest

Phase 5：Agent 技能系统（2026 Q1）

为什么引入 Agent？

问题：即使有 UI，复杂操作仍需多步：

创建环境 → 2. 编辑配置 → 3. 上传私钥 → 4. 信任主机 → 5. 执行部署

用户反馈：

"我知道要做什么，但不知道每一步点哪里。有时候漏了一步，部署失败还要重来。"

目标：让 Agent 理解意图，自动规划，执行全流程。

技能系统设计

核心思想：Skill = 带 SKILL.md 的目录

skills/
├── create-env/
│   └── SKILL.md          # 技能说明
│   └── tools.py          # 工具定义
├── ssh-ops/
│   └── SKILL.md
└── diagnosis/
    └── SKILL.md

渐进式披露：

系统提示只给技能目录（name + description）
模型判断相关后，调用 load_skill 工具拉取正文
节省 Token，按需加载

工具调用循环：

用户：创建一个新的测试环境
模型：需要调用 create_environment 工具
→ 执行工具 → 返回结果
模型：需要调用 add_authorized_key 工具
→ 执行工具 → 返回结果
模型：需要调用 run_deploy_action 工具
→ 执行工具 → 返回结果
模型：部署完成，总结步骤

技能示例：create-env

SKILL.md：

---
name: create-env
title: 环境创建与部署
description: 创建新环境、复制环境、修改配置、执行部署
---

# 环境创建与部署技能

## 能力范围
- 创建新环境（指定服务器、SSH 配置）
- 复制现有环境（保留配置，生成独立 vault 密码）
- 修改环境配置（走 inventory，留版本历史）
- 执行部署动作（check、deploy、clean、rollback）

## 工具调用
- `create_environment(env, host, user, port, deploy_root)`
- `copy_environment(source_env, target_env)`
- `update_env_config(env, config_updates)`
- `run_deploy_action(env, action, force=false)`

## 使用原则
- 少问：只问必要信息（env、host、SSH 凭据），其余默认
- 确认：部署前让用户确认配置
- 留痕：改配置走 inventory，可 diff/回滚

效果：

✅ 意图理解：用户说"创建一个测试环境"，Agent 自动规划步骤
✅ 少问多干：只问必要信息，其余用默认值
✅ 可追溯：每一步都有工具调用记录，可审计

Phase 6：全流程运维助手（2026 Q2）

会话与交互增强

会话历史：

服务端持久化（JSONL），按环境过滤
50 会话上限，200 条/会话，30 天 TTL
刷新/切换可恢复，包含 reasoning 和工具轨迹

附件上传：

支持上传私钥、配置文件
工具按 file id 读取原始内容，不经模型转述
避免大段 base64 被改坏，也不进模型上下文

可终止任务：

运行中"发送"按钮变"停止"
AbortSignal 终止当前工具调用
AbortError 不当报错，友好提示

环境全流程工具

多意图技能：

# create-env 技能重写为多意图
def handle_create_env_intent(message):
    if "创建" in message or "新建" in message:
        return "create"
    elif "复制" in message:
        return "copy"
    elif "修改" in message or "改配置" in message:
        return "update"
    elif "删除" in message:
        return "delete"
    elif "部署" in message:
        return "deploy"

工具集：

| 工具 | 作用 | 调用次数 | |------|------|----------| | create_environment | 创建新环境 | 1 | | copy_environment | 复制环境 | 1 | | update_env_config | 修改配置 | 1 | | delete_environment | 删除环境 | 1 | | run_deploy_action | 执行部署动作 | 1-3 | | add_authorized_key | 添加 SSH 公钥 | 1 | | replace_container_file | 替换容器内文件 | 1 | | trust_ssh_host | 信任 SSH 主机 | 1 | | get_deployer_public_key | 获取部署机公钥 | 1 |

max_steps = 128：一条龙部署需 7-8+ 次工具调用，留足余量。

排查/修复引导原则

写入系统提示：

排查/修复原则：
1. 改配置优先走 inventory（留版本历史可 diff/回滚）
2. 服务日志以 docker-compose 挂载路径为准（docker inspect Mounts）
3. 不假装轮询：Agent 无法自我定时唤醒，长任务引导用户看任务看板
4. 定位最早失败点：从部署日志找到第一个 ERROR，不盲目重试

效果：

✅ 改配置留痕：优先 update_env_config，不直接改文件
✅ 日志路径准确：按 compose mount 路径，不猜服务名
✅ 不假装轮询：引导用户看任务看板，不循环调用 read_job_log

设计取舍与经验

1. 为什么不做成"低代码平台"？

问题：很多内部工具想做成"拖拽式编排"，但我们刻意避免。

原因：

学习成本：拖拽式看似简单，但用户仍需理解流程、变量、条件
灵活性差：拖拽式难以表达复杂逻辑（如"如果 A 失败则重试 3 次"）
维护困难：每个自定义流程都要单独测试、文档化

我们的选择：

Agent 驱动：用户说"我要做什么"，Agent 自动规划
技能封装：复杂逻辑封装在技能中，用户无需理解细节
可审计：每一步都有工具调用记录，可追溯

2. 为什么不用工作流引擎（如 Temporal、Argo Workflows）？

问题：工作流引擎适合长期运行、复杂编排的任务，但我们的场景是短任务、多步骤。

对比：

| 维度 | 工作流引擎 | Agent 技能系统 | |------|-----------|--------------| | 适用场景 | 长期运行（小时/天）、复杂依赖 | 短任务（分钟级）、线性流程 | | 学习成本 | 需理解 DAG、状态机 | 自然语言描述意图 | | 灵活性 | 需预先定义流程 | 动态规划，可调整 | | 可观测性 | 内置可视化 | 工具调用轨迹 |

我们的选择：Agent 技能系统，因为：

部署任务通常是线性流程（创建 → 配置 → 部署）
用户更习惯自然语言描述意图
工具调用轨迹已足够可观测

3. 为什么不做成"完全自动化"？

问题：理论上 Agent 可以全自动完成所有操作，但我们刻意保留确认环节。

原因：

安全：生产环境部署需要人工确认
学习：用户需要知道 Agent 做了什么，才能信任
审计：关键操作需要人工审批

我们的设计：

Agent：检测到需要部署生产环境
→ 暂停，请求用户确认
用户：确认
→ 继续执行

效果：

✅ 安全：关键操作有人工把关
✅ 透明：用户知道每一步在做什么
✅ 可审计：确认记录可追溯

未来规划

短期（2026 Q3）

多账号系统：告别共用 admin，支持个人账号 + 角色权限
环境模板：一键创建标准环境（开发/测试/生产）
部署流水线：支持多阶段部署（dev → test → prod）
通知集成：飞书/钉钉通知部署结果

中期（2026 Q4）

K8s 深度集成：Helm chart 管理、K8s 资源监控
成本分析：按环境统计资源使用、成本分摊
自动化测试：部署后自动运行 smoke test
回滚策略：支持一键回滚到任意历史版本

长期（2027+）

多云支持：同时管理 AWS、阿里云、私有云
智能优化：基于历史数据推荐资源配置
自愈能力：检测到故障自动修复（如重启服务、扩容）
开放平台：允许第三方开发技能插件

总结

核心经验

UI 不是 CLI 的包装：需要从产品视角重新设计交互模型
Agent 不是银弹：复杂场景仍需人工确认，安全边界不能丢
技能系统是关键：封装复杂逻辑，用户只需描述意图
可观测性优先：每一步都要可追溯，故障排查才不头疼

适用场景

适合：

企业内部部署平台
运维自动化工具
DevOps 工作台
私有化交付管理

不适合：

超大规模集群（> 1000 节点）
需要复杂编排的长期任务
完全无人值守的自动化

开源计划

我们计划将 Ansible UI 的核心模块（技能系统、工具调用循环、会话管理）开源，帮助更多团队构建自己的部署平台。

预计时间：2026 Q3

仓库地址：待定（欢迎提前 star 关注）

相关文章：

[[轻量级 Agent 开发方案：基于 Skill 插件的工具调用循环]]
[[LangGraph 状态机设计模式]]
[[Karpathy LLM Wiki 模式：Obsidian 知识库重构指南]]

轻量级 Agent 开发方案：基于 Skill 插件的工具调用循环

Tue, 07 Jul 2026 00:00:00 GMT

轻量级 Agent 开发方案：基于 Skill 插件的工具调用循环

引言：为什么需要 Skill 插件系统？

很多 Agent 实现停留在"一次性问答 + 硬编码提示词"阶段：

能力固化：所有技能写死在系统提示里，无法扩展
Token 浪费：每次对话都注入全部技能说明，即使大部分用不上
无法定制：用户不能添加自己的技能，只能等待官方更新
单轮对话：没有工具调用循环，模型无法"边思考边行动"

本文介绍一个轻量级 Agent 架构，核心特性：

Skill = 带 SKILL.md 的目录：YAML frontmatter 声明元数据，正文是技能说明
渐进式披露：系统提示只给 name + description，模型需要时通过 load_skill 工具拉取正文
工具调用循环：流式响应 + 多轮工具调用，模型可以"边思考边行动"
用户自定义：支持前端新增/编辑/删除技能，持久化存储
定向技能：/skill_name 语法预注入技能正文，无需模型再调用 load_skill

核心设计

1. Skill 文件格式

每个技能是一个目录，包含 SKILL.md：

skills/
  ├── file-ops/
  │   └── SKILL.md
  ├── api-client/
  │   └── SKILL.md
  └── data-analysis/
      └── SKILL.md

SKILL.md 格式：

---
name: file-ops
title: 文件操作
description: 读取、写入、搜索、统计文件内容
---

# 文件操作技能

## 能力范围
- 读取文件内容（支持分页）
- 写入/覆盖文件
- 搜索文件内容（正则）
- 统计代码行数

## 工具调用
- `read_file(path, offset=1, limit=500)`
- `write_file(path, content)`
- `search_files(pattern, target="content")`

## 使用示例
用户：查看 main.py 的前 50 行
模型：调用 read_file(path="main.py", limit=50)

2. 渐进式披露

问题：如果系统提示包含所有技能的完整说明，Token 消耗巨大。

解法：系统提示只包含技能目录（name + description），模型判断相关后，通过 load_skill 工具拉取正文。

系统提示示例：

可用技能（调用 load_skill 获取详情）：
- file-ops: 读取、写入、搜索、统计文件内容
- api-client: HTTP 请求、JSON 解析、认证管理
- data-analysis: 数据清洗、统计、可视化

当前任务：分析日志文件中的错误模式

模型思考：

需要文件操作能力 → 调用 load_skill(name="file-ops")
获取技能详情 → 看到 read_file + search_files 工具
执行任务 → 调用 search_files(pattern="ERROR", path="logs/")

优势：

Token 节省：系统提示从 2000 Token → 200 Token
灵活扩展：新增技能不影响现有对话
按需加载：只加载当前任务相关的技能

3. 工具调用循环

核心引擎：一个同步生成器形式的流式工具调用循环。

伪代码：

async def agent_chat_stream(user_message, history, max_steps=128):
    messages = [system_prompt] + history + [user_message]
    
    for step in range(max_steps):
        # 1. 调用 LLM，流式返回
        tool_calls = []
        async for chunk in llm_stream(messages, tools=ALL_TOOLS):
            if chunk.type == "text":
                yield {"type": "text", "content": chunk.text}
            elif chunk.type == "tool":
                tool_calls.append(chunk.tool)
        
        # 2. 没有工具调用 → 对话结束
        if not tool_calls:
            yield {"type": "done"}
            return
        
        # 3. 执行工具调用
        for call in tool_calls:
            result = await dispatch_tool(call.name, call.arguments)
            messages.append({"role": "assistant", "tool_calls": [call]})
            messages.append({"role": "tool", "content": result})
            
            yield {"type": "tool", "name": call.name, "result": result}
    
    # 4. 超过最大步数 → 强制结束
    yield {"type": "error", "message": "达到最大工具调用次数"}

关键点：

流式响应：边生成边推送，用户可以看到"思考过程"
多轮循环：工具结果回喂给模型，模型可以继续调用工具
异常兜底：任何工具错误都归一化为文本，模型可以解释/换路

4. 技能来源与权限

两个技能来源：

| 来源 | 路径 | 权限 | 用途 | |------|------|------|------| | 内置 | skills/ | 只读 | 官方技能，随代码发布 | | 用户 | data/skills/ | 可写 | 用户自定义，持久化存储 |

加载逻辑：

def load_all_skills():
    builtin_skills = scan_directory(SKILLS_DIR)
    user_skills = scan_directory(USER_SKILLS_DIR)
    
    # 同名以内置为准（内置只读，不可被覆盖）
    all_skills = {**user_skills, **builtin_skills}
    
    return all_skills

CRUD 接口：

# 新增/更新用户技能
def save_user_skill(name: str, content: str):
    if name in BUILTIN_SKILLS:
        raise PermissionError("内置技能不可覆盖")
    if not re.match(r'^[a-z0-9][a-z0-9-]{0,48}$', name):
        raise ValueError("技能名格式错误")
    
    path = USER_SKILLS_DIR / name / "SKILL.md"
    path.parent.mkdir(exist_ok=True)
    path.write_text(content)

# 删除用户技能
def delete_user_skill(name: str):
    if name in BUILTIN_SKILLS:
        raise PermissionError("内置技能不可删除")
    
    path = USER_SKILLS_DIR / name
    shutil.rmtree(path)

5. 定向技能

语法：/skill_name 任务描述

实现：

def parse_user_message(message: str) -> tuple[str, str | None]:
    """解析 /skill_name 语法"""
    if message.startswith("/"):
        parts = message.split(None, 1)
        if len(parts) == 2:
            skill_name = parts[0][1:]  # 去掉 /
            task = parts[1]
            return task, skill_name
    return message, None

def build_system_prompt(forced_skill: str | None):
    prompt = "可用技能：\n" + skill_catalog()
    
    if forced_skill:
        skill_content = read_skill(forced_skill)
        prompt += f"\n\n【已激活】{skill_content}"
    
    return prompt

优势：

用户可以直接指定技能，无需模型判断
减少 load_skill 调用，节省 Token 和延迟
适合"我知道要用哪个技能"的场景

实现示例

1. 后端：技能加载器

# skills.py
from pathlib import Path
import yaml
from typing import Dict, List

SKILLS_DIR = Path(__file__).parent / "skills"
USER_SKILLS_DIR = Path("~/data/skills").expanduser()

def parse_skill_file(path: Path) -> dict:
    """解析 SKILL.md，返回 {name, title, description, content}"""
    content = path.read_text()
    
    # 提取 frontmatter
    if content.startswith("---"):
        end = content.find("---", 3)
        if end > 0:
            frontmatter = yaml.safe_load(content[3:end])
            body = content[end+3:].strip()
            return {
                **frontmatter,
                "content": body,
                "path": str(path)
            }
    
    return {"name": path.parent.name, "content": content}

def load_skills() -> Dict[str, dict]:
    """加载所有技能（内置 + 用户）"""
    skills = {}
    
    # 加载用户技能
    for skill_dir in USER_SKILLS_DIR.glob("*"):
        if skill_dir.is_dir():
            skill_file = skill_dir / "SKILL.md"
            if skill_file.exists():
                skills[skill_dir.name] = parse_skill_file(skill_file)
    
    # 加载内置技能（覆盖同名）
    for skill_dir in SKILLS_DIR.glob("*"):
        if skill_dir.is_dir():
            skill_file = skill_dir / "SKILL.md"
            if skill_file.exists():
                skill = parse_skill_file(skill_file)
                skill["builtin"] = True
                skills[skill_dir.name] = skill
    
    return skills

def skill_catalog() -> str:
    """生成技能目录（name + description，用于系统提示）"""
    skills = load_skills()
    lines = []
    for name, skill in sorted(skills.items()):
        marker = "（内置）" if skill.get("builtin") else ""
        lines.append(f"- {name}: {skill.get('description', '无说明')} {marker}")
    return "\n".join(lines)

def read_skill(name: str) -> str | None:
    """读取技能正文"""
    skills = load_skills()
    if name in skills:
        return skills[name]["content"]
    return None

2. 后端：工具调用循环

# agent_loop.py
import json
import requests
from typing import Iterator, Dict, Any

CORE_TOOLS = [
    {
        "name": "load_skill",
        "description": "加载技能详情",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {"type": "string", "description": "技能名"}
            }
        }
    },
    {
        "name": "read_file",
        "description": "读取文件内容",
        "parameters": {
            "type": "object",
            "properties": {
                "path": {"type": "string"},
                "offset": {"type": "integer", "default": 1},
                "limit": {"type": "integer", "default": 500}
            }
        }
    }
]

TOOL_HANDLERS = {
    "load_skill": lambda args: read_skill(args["name"]) or "技能不存在",
    "read_file": lambda args: Path(args["path"]).read_text()
}

def agent_chat_stream(user_message: str, history: list, max_steps: int = 128) -> Iterator[str]:
    """流式工具调用循环"""
    messages = [
        {"role": "system", "content": build_system_prompt()},
        *history,
        {"role": "user", "content": user_message}
    ]
    
    for step in range(max_steps):
        # 调用 LLM
        tool_calls = []
        response_text = ""
        
        response = requests.post(
            "http://localhost:8000/v1/chat/completions",
            json={
                "model": "claude-3",
                "messages": messages,
                "tools": CORE_TOOLS,
                "tool_choice": "auto",
                "stream": True
            }
        )
        
        for line in response.iter_lines():
            if line.startswith(b"data: "):
                data = json.loads(line[6:])
                if "choices" in data and data["choices"]:
                    delta = data["choices"][0]["delta"]
                    
                    if delta.get("content"):
                        yield json.dumps({"type": "text", "content": delta["content"]})
                        response_text += delta["content"]
                    
                    if delta.get("tool_calls"):
                        tool_calls.extend(delta["tool_calls"])
        
        if not tool_calls:
            yield json.dumps({"type": "done"})
            return
        
        # 执行工具
        messages.append({"role": "assistant", "tool_calls": tool_calls})
        
        for call in tool_calls:
            result = TOOL_HANDLERS[call["function"]["name"]](
                json.loads(call["function"]["arguments"])
            )
            
            yield json.dumps({
                "type": "tool",
                "name": call["function"]["name"],
                "result": result
            })
            
            messages.append({
                "role": "tool",
                "tool_call_id": call["id"],
                "content": result
            })

3. 前端：流式对话组件

// AgentChatPanel.tsx
function AgentChatPanel() {
  const [messages, setMessages] = useState<Message[]>([]);
  const [input, setInput] = useState("");
  const [isLoading, setIsLoading] = useState(false);

  const sendMessage = async () => {
    if (!input.trim() || isLoading) return;
    
    const userMsg = { role: "user", content: input };
    setMessages(prev => [...prev, userMsg]);
    setInput("");
    setIsLoading(true);
    
    const response = fetch("/api/agent/chat", {
      method: "POST",
      body: JSON.stringify({ message: input, messages: messages })
    });
    
    const reader = response.body.getReader();
    const decoder = new TextDecoder();
    
    let assistantMsg = { role: "assistant", content: "", tools: [] };
    
    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      
      const line = decoder.decode(value);
      const event = JSON.parse(line);
      
      if (event.type === "text") {
        assistantMsg.content += event.content;
      } else if (event.type === "tool") {
        assistantMsg.tools.push(event);
      } else if (event.type === "done") {
        break;
      }
      
      // 实时更新消息
      setMessages(prev => {
        const newMessages = [...prev, userMsg, assistantMsg];
        return newMessages;
      });
    }
    
    setIsLoading(false);
  };

  return (
    <div>
      <div className="messages">
        {messages.map((msg, i) => (
          <MessageBubble key={i} message={msg} />
        ))}
      </div>
      <div className="input-area">
        <input value={input} onChange={e => setInput(e.target.value)} />
        <button onClick={sendMessage} disabled={isLoading}>
          {isLoading ? "思考中..." : "发送"}
        </button>
      </div>
    </div>
  );
}

最佳实践

1. 技能设计原则

单一职责：每个技能只解决一类问题
自包含：技能正文包含完整的使用说明和工具定义
可组合：技能之间可以协作，但不强依赖

2. 工具设计原则

幂等性：工具可以安全重试
原子性：一次工具调用完成一个完整操作
可观察：工具调用轨迹对用户可见

3. 安全边界

技能名白名单：拒绝路径穿越（如 ../../etc/passwd）
内置技能只读：用户技能不能覆盖内置技能
工具输出截断：防止单条工具结果撑爆上下文（如限制 4000 字符）
权限控制：敏感操作（如删除技能）需要管理员权限

总结

这个轻量级 Agent 架构的核心思想：

Skill = 文件：技能是可版本化、可分享、可自定义的 Markdown 文件
渐进式披露：系统提示只给目录，模型按需加载，节省 Token
工具调用循环：流式响应 + 多轮工具调用，模型可以"边思考边行动"
用户自定义：支持前端 CRUD，技能持久化存储

适用场景：

内部工具平台（如运维助手、数据分析助手）
开发者工具（如代码审查、文档生成）
企业知识库（如客服问答、故障排查）

不适用场景：

需要复杂状态管理的长期任务（考虑 LangGraph 等框架）
需要人类审核的敏感操作（考虑 Human-in-the-loop 模式）

Karpathy LLM Wiki 模式：Obsidian 知识库重构指南

Mon, 06 Jul 2026 00:00:00 GMT

Karpathy LLM Wiki 模式：Obsidian 知识库重构指南

引言：为什么需要 LLM Wiki 模式

1.1 传统笔记库的"AI 不友好"问题

如果你像我一样，用 Obsidian 积累了数百条笔记，可能会发现一个尴尬的事实：这些笔记对人类阅读很友好，但对 AI 来说几乎不可用。

碎片化是最明显的问题。一条关于"Ansible 部署"的笔记可能散落在 10 个不同的文件中：有的在项目笔记里，有的在运维文档里，还有的在随手记的命令行片段中。AI 无法自动拼凑出完整上下文，因为它不知道哪些笔记属于同一个主题。

冗余性同样普遍。"什么是 LangGraph"这个概念可能在 5 个地方被解释过，每次的表述略有不同。AI 读取时无法判断哪个版本是最新的、哪个更准确，导致生成的内容前后矛盾。

非结构化让问题更严重。有的笔记用 frontmatter，有的不用；有的用 H1 标题，有的用粗体；日期格式五花八门（2026-07-03、2026/7/3、7 月 3 日）。AI 批量处理时不得不为每种格式写特殊的解析逻辑。

1.2 RAG 的局限性

很多人会想：那用 RAG（检索增强生成）不就行了吗？确实，RAG 能缓解检索问题，但无法解决根本矛盾。

检索噪声是 RAG 的核心痛点。向量相似度不等于语义相关性。搜索"如何部署 AskBI"可能返回"AskBI 是什么"的定义段落，因为两者在向量空间很接近，但对用户来说毫无帮助。

幻觉风险在片段拼接时尤其明显。RAG 从 3 个不同笔记中各取一段，拼成一个回答，但这三段可能来自不同版本、不同环境，甚至相互矛盾。AI 无法判断，只能硬拼，结果就是看似合理实则错误的回答。

维护成本常被忽视。每次添加新笔记，理论上都应该重新计算 embedding。1000 条笔记的 embedding 更新可能需要几分钟，而且一旦原始笔记被修改，对应的 embedding 就失效了，但系统无法自动感知。

1.3 Karpathy Wiki 模式的核心思想

Andrej Karpathy 在 2024 年提出的"LLM Wiki"模式，为解决上述问题提供了新思路。核心思想很简单：把知识库当成 Wiki 来维护，而不是当成笔记堆来存储。

结构化是第一条原则。每个主题一个页面，页面内包含完整上下文。比如"AskBI 私有化部署"这个主题，所有相关信息（环境要求、步骤、常见问题、回滚策略）都在一个页面里，AI 读取时不需要跨文件拼凑。

可审计是第二条原则。每个页面都有 frontmatter 记录创建时间、更新时间、标签、来源。所有变更都记录在日志文件中，AI 可以追踪知识的演变过程，人类也可以审计变更历史。

Agent 友好是第三条原则。明确的读取协议（先读 index.md，再读相关页面）和更新协议（新材料进 raw/，抽取后进 wiki/），让 AI 能够可靠地维护和扩展知识库，而不是在碎片中盲目搜索。

Wiki 模式 vs RAG vs 传统笔记

2.1 三种模式的对比矩阵

| 维度 | 传统笔记 | RAG | LLM Wiki | |------|----------|-----|----------| | 组织方式 | 按时间/场景碎片化存储 | 向量索引 + 原始文件 | 按主题结构化页面 | | 适用场景 | 个人随手记、灵感收集 | 大规模文档检索 | AI 协作知识库 | | 维护成本 | 低（只管写） | 中（需定期 re-embedding） | 高（需人工审阅） | | 查询质量 | 低（依赖关键词匹配） | 中（向量相似度有噪声） | 高（精确匹配 + 语义搜索） | | AI 参与度 | 无 | 检索辅助 | 主动维护 | | 可审计性 | 弱（Git 历史但无结构） | 弱（黑盒检索） | 强（frontmatter + log） |

2.2 何时选择 Wiki 模式

不是所有场景都适合 Wiki 模式。以下是我的决策树：

数据规模：

< 50 条笔记：传统笔记即可，过度结构化反而增加负担
50-500 条：考虑 Wiki 模式，尤其是需要 AI 协助时
500 条：强烈建议 Wiki 模式，否则难以维护

更新频率：

每天新增 > 5 条：需要自动化 pipeline，Wiki 模式更合适
每周新增 < 10 条：传统笔记或 RAG 也可以

AI 参与度：

仅用于检索：RAG 足够
需要 AI 维护、扩展、审计：必须 Wiki 模式

混合模式也是可行的。我的实践中，raw/ 目录用传统笔记方式快速记录，wiki/ 目录用 Wiki 模式沉淀知识。AI 定期扫描 raw/，建议哪些内容应该抽取到 wiki/，人类审阅后执行。

Karpathy Wiki 的核心原则

3.1 页面组织原则

单一职责：每个页面只讲一个主题。"Ansible UI 项目"一个页面，"SSH 跳板机穿透"一个页面，不要为了节省空间把多个主题塞在一起。这看似浪费，实则提高了可链接性和可维护性。

自包含：页面内应包含完整上下文，让读者（人类或 AI）不需要跳来跳去就能理解核心内容。当然，详细实现可以链接到其他页面，但摘要、关键结论、使用场景必须在当前页面。

可链接：明确的内外部引用关系。内部链接用 Obsidian 的双括号语法 [[页面标题]]，外部链接用标准 Markdown [标题](URL)。每个页面底部应有"相关页面"章节，列出关联主题。

3.2 frontmatter 标准

frontmatter 是 Wiki 模式的灵魂。我的标准配置如下：

---
title: 页面标题
type: project|operation|concept|learning|source-summary
created: YYYY-MM-DD
updated: YYYY-MM-DD
tags: [标签 1, 标签 2]
sources: [来源 1, 来源 2]
author: 可选
status: draft|review|published
---

必需字段：

title：页面标题，与文件名对应（空格转连字符）
type：页面类型，决定组织方式和处理逻辑
created / updated：日期格式统一为 ISO 8601
tags：标签数组，用于分类和检索

可选字段：

author：多人群协作时有用
status：草稿、审阅中、已发布
sources：原始材料来源，用于审计

3.3 变更审计机制

日志文件：log.md 记录所有重要变更，格式如下：

## 2026-07-03

- [新增] wiki/projects/ansible-ui.md：从 raw/抽取 Ansible UI 项目信息
- [合并] wiki/operations/deployment.md：合并 3 条部署相关笔记
- [删除] archive/old-notes.md：超过 60 天未更新的临时笔记

版本追踪：Git commit 与页面更新关联。每次批量更新后，commit message 应说明变更内容：

git commit -m "wiki 更新：新增 Ansible UI 项目页，合并部署文档"

回滚策略：基于 Git 的历史恢复。如果发现某次更新有问题，可以直接 revert 或 checkout 到之前版本：

git log --oneline wiki/projects/ansible-ui.md  # 查看历史
git checkout <commit-hash> -- wiki/projects/ansible-ui.md  # 恢复版本

重构流程：从 raw/ 到 wiki/

4.1 准备阶段

现状评估：先统计现有笔记的状态。我的脚本会扫描所有文件，输出：

总文件数：80
博客文章：10
Wiki 页面：11
Raw 目录：59（含 23 个待处理文件）
最近 30 天变更：15 个文件

工具准备：

Python 脚本：批量处理、frontmatter 生成
Git 配置：确保 remote 正确、.gitignore 合理
frontmatter 模板：预设标准字段

备份策略：原始文件保留在 raw/sources/YYYY-MM-DD/ 目录，即使抽取到 wiki 也不删除原文。这是安全网，也是审计依据。

4.2 抽取与合并

主题识别：先用关键词聚类，再手动标注。我的做法是：

扫描所有笔记标题和标签
提取高频词（如"Ansible"、"部署"、"LangGraph"）
按高频词分组，人工确认是否属于同一主题

内容抽取：从碎片笔记中提取相关段落，不是简单复制粘贴，而是：

保留核心结论和关键步骤
删除临时性、场景特定的细节（这些进 raw/private）
统一表述风格（时态、人称、术语）

冲突处理：相同信息在不同笔记中有不同版本时：

优先选择最新的（按修改时间）
如果内容矛盾，保留更详细的版本，并在注释中说明差异
无法判断时，两个版本都保留，标记"待确认"

4.3 结构化与去重

模板填充：为每个新页面生成标准 frontmatter 和章节结构：

---
title: 页面标题
type: project
created: 2026-07-06
updated: 2026-07-06
tags: []
sources: []
---

# 页面标题

## 摘要

## 关键结论

## 细节

## 相关页面

去重检测：用文本相似度检查新页面与现有页面是否重复。我的阈值是 80%：相似度超过 80% 就触发警告，人工判断是合并还是保留。

引用规范化：统一内部链接格式。Obsidian 用 [[页面标题]]，但为了兼容其他工具，我会在导出时转换为 [页面标题](页面标题.md)。

4.4 验证与发布

完整性检查：

必填字段是否都有值
内部链接是否指向存在的页面
标签是否符合命名规范

人工审阅：自动化≠完全可靠。关键页面（尤其是项目文档、运维流程）必须人工审阅，确保：

信息准确
表述清晰
没有敏感信息泄漏

发布流程：

# 本地提交
git add wiki/
git commit -m "新增：XXX 页面"

# 推送到远程
git push origin main

# 同步到博客（如果是 blog 目录）
bash ~/.hermes/scripts/obsidian-git-sync.sh

实战案例：一次完整重构的记录

5.1 项目背景

2026-07-03，我决定对 Obsidian vault 进行一次彻底重构。初始状态：

总文件数：80 个
博客文章：10 篇（在 blog/ 目录）
Wiki 页面：11 个（分散在不同目录）
Raw 目录：59 个文件（含大量待处理笔记）

重构目标：

建立 AGENTS.md 标准，明确 raw/ 与 wiki/ 的边界
清理 raw/ 目录，抽取有价值的内容到 wiki/
建立 archive/ 目录，归档旧版本和临时文件
配置自动化同步脚本

时间线：单日完成（约 4 小时），包括脚本编写、文件处理、人工审阅。

5.2 关键决策点

raw/ 与 wiki/ 的边界定义：

raw/sources/：原始材料、未消化的笔记、临时记录
raw/private/：含敏感信息的材料（凭据、内网地址、客户细节）
wiki/：结构化、可公开、Agent 友好的知识页面
archive/：旧版本、已废弃但需保留参考的内容

archive/ 目录的设计：不是简单的"回收站"，而是有组织的归档：

archive/cleanup-YYYY-MM-DD.md：每次清理的记录
archive/old-versions/：页面历史版本（Git 已记录，但人工可读版本放这里）
archive/deprecated/：已废弃但仍需参考的内容

private/ 敏感信息的隔离策略：

所有含凭据、token、密码的文件必须进 raw/private/
.gitignore 配置为忽略 raw/private/，确保不会误推送到远程
wiki 页面需要引用敏感信息时，写"见 raw/private/对应原文"，不复制内容

5.3 工具链与脚本

文件扫描脚本：统计变更、识别主题

import os
from pathlib import Path

def scan_vault(vault_path):
    stats = {
        'total_files': 0,
        'blog_articles': 0,
        'wiki_pages': 0,
        'raw_files': 0,
        'recent_changes': []
    }
    
    for root, dirs, files in os.walk(vault_path):
        for file in files:
            if file.endswith('.md'):
                stats['total_files'] += 1
                path = Path(root)
                
                if 'blog' in str(path):
                    stats['blog_articles'] += 1
                elif 'wiki' in str(path):
                    stats['wiki_pages'] += 1
                elif 'raw' in str(path):
                    stats['raw_files'] += 1
    
    return stats

frontmatter 生成脚本：自动化填充模板

def generate_frontmatter(title, page_type, tags=None, sources=None):
    from datetime import date
    
    frontmatter = f"""---
title: "{title}"
type: {page_type}
created: {date.today().isoformat()}
updated: {date.today().isoformat()}
tags: {tags or []}
sources: {sources or []}
---
"""
    return frontmatter

同步脚本：Obsidian 与 Git 的双向同步

#!/bin/bash
# ~/.hermes/scripts/obsidian-git-sync.sh

VAULT_PATH="/Users/edward/workspace/edward/Obsidian"
BLOG_PATH="$VAULT_PATH/blog"
REMOTE_BLOG="/Users/edward/workspace/edward/edwardchen.com/src/content/blog"

# 同步 blog 目录到博客项目
rsync -av --delete "$BLOG_PATH/" "$REMOTE_BLOG/"

# 提交到博客 Git 仓库
cd "$REMOTE_BLOG/.."
git add src/content/blog/
git commit -m "同步博客文章 $(date +%Y-%m-%d)"
git push origin main

5.4 效果对比

重构前：

❌ 碎片化：相同主题散落在多个文件
❌ 难以维护：不知道哪些笔记是最新的
❌ AI 读取困难：缺乏结构，AI 无法可靠提取信息
❌ 无审计：变更历史分散在 Git commit，难以追踪

重构后：

✅ 结构化：每个主题一个页面，信息集中
✅ 可维护：frontmatter 记录更新时间，log.md 记录变更
✅ Agent 友好：明确的读取协议，AI 能可靠维护
✅ 可审计：Git + log.md 双重记录，变更可追溯

工具链与自动化

6.1 核心工具

Git：版本控制与变更追踪的基础。关键配置：

# .gitignore 示例
raw/private/
*.tmp
.DS_Store
blog/.gitignore  # blog 目录有自己的 Git 仓库

Python 脚本：批量处理、frontmatter 生成、相似度检测。我常用的库：

from pathlib import Path  # 文件操作
import yaml  # frontmatter 解析
from datetime import date  # 日期处理
from difflib import SequenceMatcher  # 相似度检测

Obsidian 插件：

Dataview：查询 frontmatter，生成动态列表
Templater：模板填充，自动化 frontmatter 生成
Obsidian Git：自动提交、定时同步

6.2 自动化 Pipeline

每日同步：raw/ 目录的自动扫描

# ~/.hermes/scripts/daily-scan.sh
#!/bin/bash
python3 ~/.hermes/scripts/vault-scanner.py \
    --vault /Users/edward/workspace/edward/Obsidian \
    --output /tmp/vault-stats.json

定期审计：frontmatter 完整性检查

# check_frontmatter.py
def check_frontmatter(file_path):
    required_fields = ['title', 'type', 'created', 'updated', 'tags']
    issues = []
    
    with open(file_path, 'r') as f:
        content = f.read()
    
    if not content.startswith('---'):
        issues.append("缺少 frontmatter")
        return issues
    
    # 解析 frontmatter 并检查必填字段
    # ...
    
    return issues

变更通知：Git hook 触发提醒

# .git/hooks/post-commit
#!/bin/bash
echo "Wiki 页面已更新，请检查 log.md 是否需要记录"

6.3 推荐插件与配置

Obsidian 插件清单：

Dataview：查询和展示 frontmatter 数据
Templater：模板填充，支持 JavaScript
Obsidian Git：自动提交、定时同步
Advanced Tables：表格编辑增强
Markdown Checklist：任务列表管理

Git 配置模板：

# ~/.gitconfig
[user]
    name = Your Name
    email = your.email@example.com

[init]
    defaultBranch = main

[push]
    default = current

Python 脚本示例：批量更新 frontmatter

#!/usr/bin/env python3
"""批量为 wiki 页面添加或更新 frontmatter"""

import yaml
from pathlib import Path
from datetime import date

def update_frontmatter(vault_path):
    wiki_path = Path(vault_path) / 'wiki'
    
    for md_file in wiki_path.rglob('*.md'):
        content = md_file.read_text()
        
        if not content.startswith('---'):
            # 添加 frontmatter
            title = md_file.stem.replace('-', ' ').title()
            frontmatter = {
                'title': title,
                'type': 'concept',
                'created': date.today().isoformat(),
                'updated': date.today().isoformat(),
                'tags': []
            }
            new_content = '---\n' + yaml.dump(frontmatter) + '---\n\n' + content
            md_file.write_text(new_content)
            print(f"已添加 frontmatter: {md_file}")

if __name__ == '__main__':
    update_frontmatter('/Users/edward/workspace/edward/Obsidian')

常见问题与最佳实践

7.1 常见陷阱

过度结构化：为了结构化而结构化，牺牲了灵活性。有些内容确实不适合 Wiki 模式（如灵感碎片、临时记录），强行结构化只会增加负担。解决方案：明确 raw/ 的边界，允许碎片化内容存在，只在需要时抽取到 wiki/。

忽略人工审阅：相信自动化能解决所有问题。frontmatter 生成、内容抽取、去重检测都有出错的可能，尤其是边界情况。解决方案：关键页面必须人工审阅，建立"自动化建议 + 人工确认"的流程。

边界模糊：raw/ 与 wiki/ 混用，有些文件不知道该放哪里。解决方案：制定明确的规则（如 AGENTS.md），并定期检查。我的规则是：如果内容需要被多处引用、需要 AI 维护、需要长期保存，就进 wiki/；否则进 raw/。

7.2 最佳实践清单

每周 review：

[ ] 检查 raw/ 目录的新文件
[ ] 识别哪些内容应该抽取到 wiki/
[ ] 更新 log.md 记录本周变更

月度审计：

[ ] frontmatter 完整性扫描
[ ] 内部链接有效性检查
[ ] 标签一致性审查
[ ] 删除或归档超过 60 天未更新的临时笔记

季度清理：

[ ] archive/ 旧版本归档
[ ] 检查 private/ 目录是否有需要清理的敏感信息
[ ] 评估 Wiki 模式的有效性，调整规则

7.3 团队协作建议

角色分工：

内容生产者：负责 raw/ 目录的日常记录
知识工程师：负责抽取、结构化、wiki/ 维护
审阅者：负责关键页面的人工审阅
审计员：负责定期审计和清理

冲突解决：多人编辑同一页面时：

Git 分支策略：每人一个分支，合并时解决冲突
锁定机制：编辑前在 log.md 标注"正在编辑：XXX"
沟通渠道：Slack/Discord 频道同步编辑计划

权限管理：

raw/private/：仅核心成员可访问
wiki/：全员可读，核心成员可写
blog/：独立仓库，发布流程需审阅

总结与资源

8.1 核心要点回顾

Wiki 模式的三大原则：

结构化：每个主题一个页面，页面内包含完整上下文
可审计：frontmatter + 变更日志，追踪知识演变
Agent 友好：明确的读取与更新协议，AI 能可靠维护

重构流程的四个阶段：

准备：现状评估、工具准备、备份策略
抽取：主题识别、内容抽取、冲突处理
结构化：模板填充、去重检测、引用规范化
验证：完整性检查、人工审阅、发布流程

工具链的关键组件：

Git：版本控制与变更追踪
Python 脚本：批量处理、frontmatter 生成
Obsidian 插件：Dataview、Templater、Obsidian Git

8.2 延伸阅读

8.3 下一步行动

评估自己的笔记库状态：

# 统计文件数量和分布
find ~/Obsidian -name "*.md" | wc -l
find ~/Obsidian -name "*.md" -path "*/blog/*" | wc -l
find ~/Obsidian -name "*.md" -path "*/wiki/*" | wc -l

选择一个主题试跑重构流程：

找一个你经常写的主题（如"部署"、"LangGraph"）
收集所有相关笔记
抽取到一个 wiki 页面
添加 frontmatter 和相关链接

建立自动化 pipeline：

配置 Git 和 .gitignore
编写或下载 frontmatter 生成脚本
设置每日/每周的扫描和审计任务
在 Obsidian 中安装推荐插件

校验

[x] 没有真实凭据、客户内网地址或未脱敏材料
[x] 引用了对应 wiki/source 材料（AGENTS.md、本次重构经验）
[x] 更新了相关 wiki 页面或 index（需在发布前完成）

相关文章：

[[LangGraph 复杂状态机设计模式]]
[[SSH 跳板机端口穿透进阶]]
[[Obsidian 博客与知识库分仓同步实践]]

SSH 跳板机端口穿透：当 ProxyJump、ssh -L 和 SOCKS5 都不可用时

Fri, 03 Jul 2026 00:00:00 GMT

SSH 跳板机端口穿透：当 ProxyJump、ssh -L 和 SOCKS5 都不可用时

在内网运维场景里，经常会遇到这种链路：

本机 -> 跳板机 -> 目标机

本机不能直接访问目标机，只能先登录跳板机，再从跳板机访问目标机。通常我们会优先使用 ProxyJump、ssh -L 或 ssh -D SOCKS5 代理。但如果跳板机或目标机的 sshd 禁止 TCP forwarding，这些标准方案会直接失败。

这篇文章记录一个更朴素但实用的方案：用 ProxyCommand + nc 完成 SSH 登录，再用 socat + ssh + nc 穿透少量固定端口。它不需要修改服务器 sshd 配置，适合权限受限但可以正常 SSH 登录的环境。

示例里的 IP、用户和别名均为脱敏占位，不对应真实环境。

1. 基础 SSH 链路

先给跳板机配置普通 SSH Host：

Host bastion-demo
    HostName 192.0.2.10
    User bastion-user
    IdentityFile ~/.ssh/id_ed25519

目标机通过跳板机上的 nc 建立 TCP 连接：

Host target-demo
    HostName 198.51.100.20
    User app-user
    IdentityFile ~/.ssh/id_ed25519
    ProxyCommand ssh bastion-demo nc %h %p

验证登录：

ssh target-demo

这条链路的关键点是：ProxyCommand 不走 SSH 的 direct-tcpip channel，而是在跳板机上执行 nc <target-host> <target-port>。因此它可以绕过一部分禁止 ProxyJump 的环境。

要求很简单：

本机私钥能登录跳板机。
本机私钥或本机公钥授权能登录目标机。
跳板机上存在 nc、ncat 或 socat 之一。
SSH Host 别名建议只用 ASCII。

2. 常见失败现象

2.1 中文或特殊字符别名导致 hostname 报错

如果执行：

ssh 某个中文别名

可能会报：

hostname contains invalid characters

处理方式很直接：SSH Host 别名使用 ASCII，中文写到注释或文档里。

project-bastion
project-target

2.2 ProxyJump 被服务端拒绝

ProxyJump 失败时常见报错：

channel 0: open failed: administratively prohibited: open failed
stdio forwarding failed

原因是 ProxyJump 依赖 SSH direct-tcpip channel。如果跳板机 sshd 禁止 TCP forwarding，就会被服务端拒绝。

替代配置：

ProxyCommand ssh bastion-demo nc %h %p

2.3 SOCKS5 或 ssh -L 被目标机拒绝

如果尝试：

ssh -N -D 127.0.0.1:1080 target-demo

或：

ssh -N -L 18080:127.0.0.1:8080 target-demo

遇到：

channel 1: open failed: administratively prohibited: open failed

通常是目标机 sshd 禁止 TCP forwarding。

可以在目标机检查：

sshd -T 2>/dev/null | egrep '^(allowtcpforwarding|disableforwarding|permitopen|permitlisten)'

如果看到：

allowtcpforwarding no
disableforwarding no
permitopen any
permitlisten any

那么 ssh -D SOCKS5 和 ssh -L 基本都不能用。

3. 固定端口穿透方案

当 SSH forwarding 被禁时，可以在本机用 socat 监听一个本地端口。每次有浏览器连接进来，就执行一次：

ssh target-demo nc 127.0.0.1 <remote-port>

通用模板：

socat TCP-LISTEN:<local-port>,bind=127.0.0.1,reuseaddr,fork EXEC:'ssh <target-alias> nc <remote-host> <remote-port>'

安装 socat：

brew install socat

示例：把本机 18080 转到目标机本地 8080：

socat TCP-LISTEN:18080,bind=127.0.0.1,reuseaddr,fork EXEC:'ssh target-demo nc 127.0.0.1 8080'

浏览器访问：

http://127.0.0.1:18080

如果目标服务监听的是内网 IP 而不是 127.0.0.1，把命令里的 127.0.0.1 换成对应地址即可。

4. 稳定性增强：复用 SSH 连接

上面的原始命令有一个问题：浏览器的每个 TCP 连接都会新建一次 SSH 登录。页面资源多时，连接会明显抖动。

可以先建立 SSH master 连接：

mkdir -p ~/.ssh/cm
chmod 700 ~/.ssh/cm

ssh -MNf \
  -S ~/.ssh/cm/target-demo \
  -o ControlMaster=yes \
  -o ControlPersist=2h \
  -o ServerAliveInterval=30 \
  -o ServerAliveCountMax=3 \
  target-demo

再让 socat 复用这个 master：

socat TCP-LISTEN:18080,bind=127.0.0.1,reuseaddr,fork,keepalive EXEC:'ssh -T -S ~/.ssh/cm/target-demo -o BatchMode=yes -o LogLevel=ERROR target-demo nc 127.0.0.1 8080'

检查 master 状态：

ssh -S ~/.ssh/cm/target-demo -O check target-demo

关闭 master：

ssh -S ~/.ssh/cm/target-demo -O exit target-demo

这个版本仍然不是完整 VPN，也不是 SOCKS5，但对少量固定 Web 服务已经足够稳定。

5. 什么时候不该用这个方案

这个方案适合：

只需要访问少量固定端口。
不能修改 sshd 配置。
ProxyJump、ssh -L、ssh -D 被服务端策略禁止。
跳板机能访问目标机，且跳板机上有 nc。

不适合：

需要访问大量动态端口。
需要全系统透明代理。
需要长期高并发访问。
能让管理员开启 AllowTcpForwarding yes。

如果管理员允许 TCP forwarding，优先使用标准方案：

ssh -N -L 18080:127.0.0.1:8080 target-demo

或者：

ssh -N -D 127.0.0.1:1080 target-demo

标准方案更简单，也更稳定。

6. 总结

当 SSH TCP forwarding 被禁时，不必一上来就改服务器配置或搭 VPN。对少量固定端口，可以用：

ProxyCommand + nc
socat + ssh + nc
ControlMaster 复用连接

这套组合足够小，也足够实用。它的边界也很清楚：适合临时访问固定端口，不适合替代正式 VPN 或标准 SSH forwarding。

LLM 在垂直领域的微调策略

Thu, 02 Jul 2026 00:00:00 GMT

LLM 在垂直领域的微调策略

摘要：本文深入探讨 LLM 在垂直领域的微调策略，通过技术原理、代码示例和实战案例，带你全面掌握 LoRA、QLoRA、P-Tuning 等参数高效微调技术。从数学推导到工程实现，从方法对比到效果评估，为你提供完整的技术指南。

1. 问题背景与挑战

1.1 为什么需要垂直领域微调？

大语言模型 (LLM) 在通用任务上表现出色，但在垂直领域往往面临以下挑战：

领域知识缺失：通用模型缺乏医疗、法律、金融等专业领域的知识
术语理解偏差：专业术语的含义可能与通用语境不同
格式要求严格：垂直领域对输出格式有特定要求（如医疗诊断报告）
合规性要求：某些行业对 AI 输出有严格的合规要求

示例场景：

通用模型：患者发烧了，建议多喝水休息。
医疗领域模型：患者体温 38.5°C，建议服用对乙酰氨基酚 500mg，每 6 小时一次，
              同时监测体温变化，如持续高烧需及时就医。

1.2 微调的挑战

传统的全量微调面临巨大挑战：

| 挑战 | 说明 | 影响 | |------|------|------| | 计算成本高 | 需要更新所有参数 (数十亿) | 需要多张 A100 GPU | | 存储需求大 | 每个微调版本占用数十 GB | 难以维护多个版本 | | 灾难性遗忘 | 学习新知识时遗忘旧知识 | 通用能力下降 | | 训练时间长 | 完整 epoch 需要数天 | 迭代周期长 |

以 LLaMA-7B 为例：

参数数量：70 亿
全量微调显存：~140GB (需要多卡)
训练时间：~3 天 (单 epoch)
模型存储：~14GB (FP16)

1.3 参数高效微调 (PEFT) 的兴起

为了解决上述问题，参数高效微调 (Parameter-Efficient Fine-Tuning, PEFT) 应运而生：

核心思想：冻结预训练模型参数，只训练少量额外参数
优势：
- 显存占用降低 10-50 倍
- 训练速度提升 5-10 倍
- 避免灾难性遗忘
- 可以维护多个任务适配器

2. 微调方法分类与对比

2.1 方法分类

PEFT 方法主要可以分为以下几类：

参数高效微调 (PEFT)
├── 添加参数方法
│   ├── LoRA (Low-Rank Adaptation)
│   ├── AdaLoRA (Adaptive LoRA)
│   └── DoRA (Weight-Decomposed LoRA)
├── 提示学习方法
│   ├── Prefix-Tuning
│   ├── P-Tuning v2
│   └── Prompt Tuning
├── 适配器方法
│   ├── Adapter
│   ├── Parallel Adapter
│   └── Compacter
└── 量化方法
    ├── QLoRA
    └ ├── BitFit
    └ └── LLAMA-Factory

2.2 核心方法对比

| 方法 | 可训练参数 | 显存占用 | 推理速度 | 效果 | 适用场景 | |------|-----------|---------|---------|------|---------| | 全量微调 | 100% | 100% | 基准 | 最优 | 资源充足 | | LoRA | 0.1-1% | 20-30% | -1-3% | 接近全量 | 通用场景 | | QLoRA | 0.1-1% | 5-10% | -1-3% | 接近 LoRA | 资源受限 | | Prefix-Tuning | 0.01-0.1% | 10-20% | -5-10% | 中等 | 特定任务 | | Adapter | 0.5-2% | 30-40% | -3-5% | 良好 | 多任务 |

2.3 选择建议

根据资源选择：

单张消费级 GPU (24GB)：QLoRA
单张专业 GPU (40-80GB)：LoRA
多卡集群：全量微调或 LoRA

根据任务选择：

文本生成：LoRA / QLoRA
分类任务：Adapter / Prefix-Tuning
多任务学习：Adapter

3. LoRA 原理与实现

3.1 核心思想

LoRA (Low-Rank Adaptation) 的核心假设：模型更新的低秩性

传统微调：ΔW ∈ R^(m×n)  (需要更新 m×n 个参数)
LoRA:     ΔW = BA, 其中 B ∈ R^(m×r), A ∈ R^(r×n), r << min(m,n)
         (只需要更新 r×(m+n) 个参数)

3.2 数学推导

给定预训练权重 $W_0 \in \mathbb{R}^{m \times n}$，传统微调学习 $W = W_0 + \Delta W$。

LoRA 假设 $\Delta W$ 是低秩的，可以分解为：

$$\Delta W = BA$$

其中：

$B \in \mathbb{R}^{m \times r}$
$A \in \mathbb{R}^{r \times n}$
$r \ll \min(m, n)$ (通常 r=8, 16, 32, 64)

前向传播： $$h = W_0 x + \Delta W x = W_0 x + BAx$$

3.3 参数对比

以 LLaMA-7B 的 Attention 层为例：

$W_q \in \mathbb{R}^{4096 \times 4096}$
传统微调：4096 × 4096 = 16.7M 参数
LoRA (r=8): 8 × (4096 + 4096) = 65.5K 参数
参数减少：99.6%

3.4 代码实现

import torch
import torch.nn as nn
from typing import Optional

class LoRALayer(nn.Module):
    def __init__(
        self, 
        in_features: int, 
        out_features: int, 
        rank: int = 8,
        alpha: float = 16.0
    ):
        super().__init__()
        self.rank = rank
        self.alpha = alpha
        self.scaling = alpha / rank
        
        # LoRA 分解：W = W0 + BA
        self.lora_A = nn.Linear(in_features, rank, bias=False)
        self.lora_B = nn.Linear(rank, out_features, bias=False)
        
        # 初始化
        nn.init.kaiming_uniform_(self.lora_A.weight, a=math.sqrt(5))
        nn.init.zeros_(self.lora_B.weight)
    
    def forward(self, x: torch.Tensor) -> torch.Tensor:
        # 原始权重计算 (冻结)
        # original_output = self.original_weight @ x
        
        # LoRA 更新
        lora_output = self.lora_B(self.lora_A(x)) * self.scaling
        
        return lora_output

# 使用示例
class LLaMAModelWithLoRA(nn.Module):
    def __init__(self, base_model, rank=8):
        super().__init__()
        self.base_model = base_model  # 冻结的预训练模型
        self.base_model.requires_grad_(False)
        
        # 为 Attention 层添加 LoRA
        for layer in self.base_model.layers:
            layer.attn.q_proj.lora = LoRALayer(
                in_features=4096,
                out_features=4096,
                rank=rank
            )
    
    def forward(self, x):
        outputs = self.base_model(x)
        # 添加 LoRA 输出
        # ...
        return outputs

3.5 训练技巧

初始化策略：

A 矩阵：Kaiming 均匀初始化
B 矩阵：零初始化
原因：训练开始时 LoRA 影响为 0，逐渐学习更新

秩的选择：

# 秩选择经验法则
rank = 8    # 资源受限，快速实验
rank = 16   # 平衡性能与资源 (推荐)
rank = 64   # 追求最优效果
rank = 128  # 接近全量微调效果

Target 模块选择：

# 推荐配置 (PEFT 库)
target_modules = [
    "q_proj",  # Query 投影 (必选)
    "v_proj",  # Value 投影 (推荐)
    "k_proj",  # Key 投影 (可选)
    "o_proj",  # Output 投影 (可选)
    "gate_proj",  # MLP Gate (可选)
    "up_proj",    # MLP Up (可选)
    "down_proj"   # MLP Down (可选)
]

4. QLoRA 量化微调

4.1 核心创新

QLoRA (Quantized LoRA) 在 LoRA 基础上引入4 比特量化：

QLoRA = 4-bit 量化基模型 + NF4 数据类型 + 双层量化 + LoRA

4.2 关键技术

1. NF4 数据类型

针对正态分布优化的 4 比特数据类型：

# NF4 的 16 个离散值 (近似正态分布)
nf4_values = [
    -2.597, -2.355, -1.955, -1.610,
    -1.230, -0.820, -0.380, 0.076,
     0.437, 0.830, 1.260, 1.700,
     2.190, 2.760, 3.420, 4.250
]

2. 双层量化

第一层：权重量化到 4-bit
第二层：量化参数 (scale, zero_point) 也量化

3. 分页优化器

避免峰值显存占用，将优化器状态分页存储。

4.3 显存对比

| 方法 | 模型 | 显存占用 | 对比 | |------|------|---------|------| | 全量微调 | LLaMA-65B | 1.3TB | 基准 | | LoRA | LLaMA-65B | 240GB | 5.4x | | QLoRA | LLaMA-65B | 48GB | 27x |

4.4 代码实现

from peft import LoraConfig, get_peft_model
from transformers import AutoModelForCausalLM, BitsAndBytesConfig
import torch

# 1. 配置 4-bit 量化
quantization_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_use_double_quant=True,  # 双层量化
    bnb_4bit_quant_type="nf4",        # NF4 数据类型
    bnb_4bit_compute_dtype=torch.float16  # 计算精度
)

# 2. 加载量化模型
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-65b-hf",
    quantization_config=quantization_config,
    device_map="auto"
)

# 3. 配置 LoRA
lora_config = LoraConfig(
    r=16,  # 秩
    lora_alpha=32,
    target_modules=["q_proj", "v_proj", "k_proj", "o_proj"],
    lora_dropout=0.1,
    bias="none",
    task_type="CAUSAL_LM"
)

# 4. 应用 LoRA
model = get_peft_model(model, lora_config)

# 5. 验证可训练参数
model.print_trainable_parameters()
# 输出：trainable params: 2097152 || all params: 67289753600 || trainable%: 0.0031%

4.5 训练建议

批次大小：

# QLoRA 可以使用更大的批次
per_device_train_batch_size = 4  # LoRA 通常只能 1-2
gradient_accumulation_steps = 8
# 有效批次大小 = 4 × 8 = 32

学习率：

learning_rate = 2e-4  # QLoRA 推荐学习率
# 比全量微调高 10-100 倍

5. 其他 PEFT 方法

5.1 Prefix-Tuning

核心思想：在输入前添加可学习的 prefix 向量

class PrefixTuning(nn.Module):
    def __init__(self, n_prefix_tokens=10, d_model=4096):
        super().__init__()
        self.prefix = nn.Parameter(torch.randn(n_prefix_tokens, d_model))
    
    def forward(self, input_ids, attention_mask):
        # 获取 prefix 嵌入
        prefix_embeds = self.prefix.unsqueeze(0).expand(input_ids.size(0), -1, -1)
        
        # 拼接 prefix
        embeddings = self.model.embeddings(input_ids)
        embeddings = torch.cat([prefix_embeds, embeddings], dim=1)
        
        return self.model(embeddings)

适用场景：

文本分类
情感分析
问答任务

5.2 P-Tuning v2

Prefix-Tuning 的改进版本：

在所有层添加 prefix（不只是输入层）
添加 MLP 投影层
支持更多任务类型

5.3 Adapter

核心思想：在 Transformer 层之间插入小型神经网络

class Adapter(nn.Module):
    def __init__(self, d_model=4096, downscale=8):
        super().__init__()
        down_dim = d_model // downscale
        
        self.down_proj = nn.Linear(d_model, down_dim)
        self.up_proj = nn.Linear(down_dim, d_model)
        self.non_linearity = nn.GELU()
    
    def forward(self, x, residual):
        # Adapter 输出
        adapter_output = self.up_proj(self.non_linearity(self.down_proj(x)))
        
        # 残差连接
        return residual + adapter_output

5.4 方法选择建议

| 任务类型 | 推荐方法 | 理由 | |---------|---------|------| | 文本生成 | LoRA / QLoRA | 效果好，资源占用低 | | 文本分类 | Prefix-Tuning | 参数少，训练快 | | 多任务 | Adapter | 可独立加载不同任务适配器 | | 资源受限 | QLoRA | 单卡 24GB 可微调 65B 模型 |

6. 实战案例：垂直领域微调

6.1 案例背景

场景：医疗问答系统

基模型：LLaMA-2-7B
数据：10,000 条医疗问答对
目标：提升医疗专业知识准确性

6.2 数据准备

# 数据格式
medical_data = [
    {
        "question": "患者体温 38.5°C，应该怎么办？",
        "answer": "建议服用对乙酰氨基酚 500mg，每 6 小时一次..."
    },
    # ... 更多数据
]

# 转换为训练格式
def format_sample(sample):
    return f"""### 问题：
{sample['question']}

### 回答：
{sample['answer']}"""

formatted_data = [format_sample(s) for s in medical_data]

6.3 完整训练代码

from transformers import (
    AutoTokenizer, 
    TrainingArguments, 
    Trainer
)
from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training
import torch

# 1. 加载模型和分词器
model_name = "meta-llama/Llama-2-7b-hf"
tokenizer = AutoTokenizer.from_pretrained(model_name)
tokenizer.pad_token = tokenizer.eos_token

# 2. 加载量化模型
from transformers import BitsAndBytesConfig
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_use_double_quant=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.float16
)

model = AutoModelForCausalLM.from_pretrained(
    model_name,
    quantization_config=bnb_config,
    device_map="auto",
    trust_remote_code=True
)

# 3. 准备模型 for k-bit 训练
model = prepare_model_for_kbit_training(model)

# 4. 配置 LoRA
lora_config = LoraConfig(
    r=16,
    lora_alpha=32,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM"
)

model = get_peft_model(model, lora_config)
model.print_trainable_parameters()

# 5. 数据加载
from datasets import Dataset
dataset = Dataset.from_list([{"text": t} for t in formatted_data])

def preprocess_function(examples):
    return tokenizer(
        examples["text"],
        padding="max_length",
        truncation=True,
        max_length=512
    )

tokenized_dataset = dataset.map(preprocess_function, batched=True)

# 6. 训练配置
training_args = TrainingArguments(
    output_dir="./medical-lora",
    per_device_train_batch_size=4,
    gradient_accumulation_steps=8,
    learning_rate=2e-4,
    num_train_epochs=3,
    fp16=True,
    logging_steps=10,
    save_strategy="epoch",
    evaluation_strategy="no",
    optim="adamw_8bit"
)

# 7. 训练
trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=tokenized_dataset,
)

trainer.train()

# 8. 保存模型
model.save_pretrained("./medical-lora-final")
tokenizer.save_pretrained("./medical-lora-final")

6.4 推理使用

from peft import PeftModel

# 加载基模型
base_model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-2-7b-hf",
    device_map="auto"
)

# 加载 LoRA 权重
model = PeftModel.from_pretrained(
    base_model,
    "./medical-lora-final"
)

# 推理
def generate_response(question):
    prompt = f"""### 问题：
{question}

### 回答："""
    
    inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
    outputs = model.generate(
        **inputs,
        max_new_tokens=256,
        temperature=0.7,
        top_p=0.9
    )
    
    return tokenizer.decode(outputs[0], skip_special_tokens=True)

# 测试
response = generate_response("患者发烧 39 度怎么办？")
print(response)

6.5 效果评估

| 指标 | 基模型 | LoRA 微调 | 提升 | |------|--------|----------|------| | 准确率 | 62% | 87% | +25% | | 专业术语正确率 | 58% | 92% | +34% | | 格式规范率 | 70% | 95% | +25% | | 响应时间 | 1.2s | 1.3s | -8% |

7. 效果评估与调优

7.1 评估指标

自动化指标：

from evaluate import load

# 文本生成质量
bleu = load("bleu")
rouge = load("rouge")

# 语义相似度
bertscore = load("bertscore")

人工评估维度：

准确性：信息是否正确
完整性：是否覆盖所有要点
专业性：术语使用是否准确
可读性：表达是否清晰

7.2 超参数调优

秩 (r) 的选择：

# 实验对比
r_values = [4, 8, 16, 32, 64]
results = {}

for r in r_values:
    model = train_with_lora(r=r)
    score = evaluate(model)
    results[r] = score

# 通常 r=16 或 32 效果最佳

学习率调优：

learning_rates = [1e-4, 2e-4, 5e-4, 1e-3]

# 学习率过低的症状：
# - 训练缓慢
# - 效果不佳

# 学习率过高的症状：
# - 训练不稳定
# - 损失震荡

Target modules 选择：

# 实验配置
configs = [
    ["q_proj"],                    # 最小配置
    ["q_proj", "v_proj"],          # 推荐配置
    ["q_proj", "k_proj", "v_proj", "o_proj"],  # 完整配置
    ["all-linear"]                 # 所有线性层
]

7.3 常见问题与解决

问题 1：训练损失不下降

# 解决方案
1. 提高学习率 (2e-4 → 5e-4)
2. 增加秩 r (8 → 16)
3. 检查数据质量
4. 增加训练轮数

问题 2：显存溢出

# 解决方案
1. 减小批次大小
2. 启用梯度累积
3. 使用 QLoRA (4-bit)
4. 启用 gradient_checkpointing

问题 3：推理速度慢

# 解决方案
1. 合并 LoRA 权重到基模型
2. 使用 ONNX 优化
3. 启用 KV Cache
4. 使用 vLLM 等推理框架

8. 总结与资源

8.1 核心要点回顾

PEFT 的价值：
- 显存占用降低 10-50 倍
- 训练速度提升 5-10 倍
- 避免灾难性遗忘
方法选择：
- 资源充足：全量微调
- 通用场景：LoRA (r=16)
- 资源受限：QLoRA (4-bit)
- 特定任务：Prefix-Tuning / Adapter
实战建议：
- Target modules：至少包含 q_proj, v_proj
- 学习率：2e-4 左右
- 秩 r：16-32 平衡效果与资源
- 数据质量：比数量更重要

8.2 未来方向

自适应秩：根据不同层自动调整秩
动态稀疏：训练过程中动态调整稀疏模式
多任务学习：共享基模型，独立任务适配器
持续学习：避免灾难性遗忘的新方法

8.3 学习资源

官方文档：

LangChain 自定义工具开发实战指南

Wed, 01 Jul 2026 00:00:00 GMT

LangChain 自定义工具开发实战指南

摘要：LangChain 的工具（Tools）机制是构建 AI Agent 的核心能力。本文将深入解析自定义工具的设计模式、源码实现原理、性能优化技巧，并通过实战案例展示如何构建企业级工具链。内容涵盖 Tool 接口设计、Tool 注册与管理、异步工具开发、工具链编排等关键技术点。

1. 背景与动机

1.1 问题描述

在构建 LLM 应用时，我们常遇到以下挑战：

知识时效性限制：LLM 的训练数据存在截止日期，无法获取最新信息
领域专业知识：模型缺乏特定行业的深度知识和业务逻辑
外部系统交互：需要与数据库、API、文件系统等外部资源交互
计算能力扩展：复杂计算、数据分析等任务超出模型能力范围

LangChain 的 Tool 机制正是为解决这些问题而生。通过自定义工具，我们可以：

扩展模型的知识边界
连接企业内部系统
实现复杂的工作流自动化
构建智能 Agent 系统

1.2 应用场景

| 场景 | 描述 | 典型工具 | |------|------|----------| | 信息检索 | 实时获取网络、数据库信息 | Search, DatabaseQuery | | 代码执行 | 运行 Python 代码、SQL 查询 | PythonREPL, SQLDatabase | | API 调用 | 与第三方服务交互 | HTTPRequest, WeatherAPI | | 文件操作 | 读写、处理本地文件 | FileRead, FileWrite | | 计算分析 | 数学计算、数据分析 | Calculator, DataAnalyzer | | 业务系统 | 企业内部系统对接 | CRM, ERP, OA |

2. 核心概念

2.1 技术原理

LangChain 的工具系统基于 Function Calling 机制实现。其核心原理如下：

┌─────────────┐    ┌──────────────────┐    ┌─────────────┐
│   用户输入   │───▶│   LLM + Tool     │───▶│  工具选择   │
│             │    │   Descriptions   │    │             │
└─────────────┘    └──────────────────┘    └──────┬──────┘
                                                   │
                                    ┌──────────────┼──────────────┐
                                    ▼              ▼              ▼
                            ┌──────────┐  ┌──────────┐  ┌──────────┐
                            │ Tool A   │  │ Tool B   │  │ Tool C   │
                            │ 执行     │  │ 执行     │  │ 执行     │
                            └────┬─────┘  └────┬─────┘  └────┬─────┘
                                 │              │              │
                                 └──────────────┼──────────────┘
                                                ▼
                                       ┌─────────────┐
                                       │  结果返回   │
                                       │  给 LLM     │
                                       └──────┬──────┘
                                              │
                                              ▼
                                       ┌─────────────┐
                                       │   最终回答   │
                                       └─────────────┘

关键组件：

Tool 接口：定义工具的标准接口
Tool Description：工具的描述信息，用于 LLM 理解工具用途
Agent Executor：负责工具调度的执行器
Output Parser：解析 LLM 输出，提取工具调用参数

2.2 关键组件

Tool 接口（新版）

from langchain.tools import BaseTool
from pydantic import BaseModel, Field

class ToolInput(BaseModel):
    """输入参数定义"""
    query: str = Field(description="搜索关键词")
    limit: int = Field(description="返回结果数量", ge=1, le=100, default=10)

class MyCustomTool(BaseTool):
    name: str = "my_custom_tool"
    description: str = "这是一个自定义工具的描述"
    
    def _run(self, query: str, limit: int = 10) -> str:
        """同步执行方法"""
        # 工具逻辑
        return f"搜索结果：{query}, 数量：{limit}"
    
    async def _arun(self, query: str, limit: int = 10) -> str:
        """异步执行方法（可选）"""
        # 异步逻辑
        return await self._run(query, limit)

Structured Tool（结构化工具）

from langchain.tools import StructuredTool
from typing import Optional

def search_function(query: str, limit: int = 10) -> str:
    """搜索功能的描述"""
    return f"搜索结果：{query}"

tool = StructuredTool(
    name="search",
    description="搜索相关信息",
    func=search_function,
    args_schema=None  # 自动从函数签名推断
)

2.3 架构设计

graph TB
    subgraph "应用层"
        A[用户] --> B[Chat Interface]
    end
    
    subgraph "Agent 层"
        B --> C[Agent Executor]
        C --> D[LLM Model]
        C --> E[Tool Registry]
    end
    
    subgraph "工具层"
        E --> F[Custom Tool A]
        E --> G[Custom Tool B]
        E --> H[Custom Tool C]
    end
    
    subgraph "资源层"
        F --> I[Database]
        G --> J[External API]
        H --> K[File System]
    end

3. 技术实现

3.1 环境准备

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install langchain langchain-core langchain-community
pip install langchain-openai  # 如果使用 OpenAI
pip install pydantic  # 数据验证

# 验证安装
python -c "import langchain; print(langchain.__version__)"

3.2 基础实现

方式一：使用 FunctionTool（推荐）

from langchain.agents import tool

@tool
def get_weather(city: str) -> str:
    """
    获取指定城市的天气信息
    
    Args:
        city: 城市名称，如 "北京"、"上海"
    
    Returns:
        天气信息字符串
    """
    # 模拟天气数据
    weather_data = {
        "北京": "晴朗，25°C，湿度 45%",
        "上海": "多云，22°C，湿度 60%",
        "广州": "小雨，28°C，湿度 80%",
    }
    return weather_data.get(city, f"未知城市 {city} 的天气数据")

# 使用
print(get_weather("北京"))
# 输出：晴朗，25°C，湿度 45%

方式二：继承 BaseTool

from langchain.tools import BaseTool
from pydantic import BaseModel, Field
from typing import Optional

class CalculatorInput(BaseModel):
    """计算器输入参数"""
    expression: str = Field(description="数学表达式，如 '2 + 3 * 4'")

class CalculatorTool(BaseTool):
    name: str = "calculator"
    description: str = "执行数学计算。输入有效的数学表达式。"
    args_schema: type[BaseModel] = CalculatorInput
    
    def _run(self, expression: str) -> str:
        """执行计算"""
        try:
            # 安全的计算方式
            result = eval(expression, {"__builtins__": {}}, {})
            return f"计算结果：{result}"
        except Exception as e:
            return f"计算错误：{str(e)}"
    
    async def _arun(self, expression: str) -> str:
        """异步执行（可选）"""
        return self._run(expression)

# 使用
calc = CalculatorTool()
print(calc.run("2 + 3 * 4"))
# 输出：计算结果：14

3.3 进阶功能

异步工具开发

import asyncio
from langchain.tools import BaseTool

class AsyncSearchTool(BaseTool):
    name: str = "async_search"
    description: str = "异步搜索网络信息"
    
    def _run(self, query: str) -> str:
        # 同步实现（回退）
        return f"同步搜索：{query}"
    
    async def _arun(self, query: str) -> str:
        """异步搜索实现"""
        # 模拟异步操作
        await asyncio.sleep(0.5)
        
        # 实际场景中，这里是异步 HTTP 请求
        # response = await aiohttp_client.get(...)
        
        return f"异步搜索结果：{query}"

# 批量异步调用
async def batch_search():
    tool = AsyncSearchTool()
    queries = ["AI", "LLM", "LangChain"]
    
    results = await asyncio.gather(*[
        tool.arun(q) for q in queries
    ])
    return results

工具链编排

from langchain.tools import tool
from typing import List

@tool
def search_products(category: str) -> List[dict]:
    """搜索产品"""
    return [
        {"id": 1, "name": "产品 A", "price": 100},
        {"id": 2, "name": "产品 B", "price": 200},
    ]

@tool
def calculate_discount(products: List[dict], rate: float) -> List[dict]:
    """计算折扣"""
    return [
        {**p, "discounted_price": p["price"] * (1 - rate)}
        for p in products
    ]

@tool
def format_invoice(products: List[dict]) -> str:
    """格式化发票"""
    lines = ["=== 发票 ==="]
    total = 0
    for p in products:
        price = p.get("discounted_price", p["price"])
        lines.append(f"{p['name']}: ¥{price}")
        total += price
    lines.append(f"总计：¥{total}")
    return "\n".join(lines)

# 工具链：search -> discount -> invoice
def product_workflow(category: str, discount_rate: float = 0.1):
    products = search_products(category)
    discounted = calculate_discount(products, discount_rate)
    invoice = format_invoice(discounted)
    return invoice

4. 最佳实践

4.1 性能优化

工具缓存

from functools import lru_cache
from langchain.tools import tool

@tool
@lru_cache(maxsize=100)
def get_static_data(data_id: str) -> str:
    """
    获取静态数据（可缓存）
    
    注意：缓存参数必须可哈希
    """
    # 模拟数据库查询
    return f"数据 {data_id} 的内容"

# 清理缓存
get_static_data.cache_clear()

批量处理优化

from langchain.tools import BaseTool
from typing import List

class BatchQueryTool(BaseTool):
    name: str = "batch_query"
    description: str = "批量查询数据，减少网络请求"
    
    def _run(self, ids: List[int]) -> str:
        """批量查询"""
        # 一次查询多个 ID，而不是循环查询
        # SELECT * FROM table WHERE id IN ({ids})
        results = [f"ID {i} 的数据" for i in ids]
        return "\n".join(results)

4.2 错误处理

from langchain.tools import tool
from typing import Optional

@tool
def safe_database_query(query: str, timeout: int = 30) -> str:
    """
    安全的数据库查询，包含完善的错误处理
    """
    import logging
    
    logger = logging.getLogger(__name__)
    
    try:
        # 输入验证
        if not query or len(query) > 1000:
            return "错误：查询语句无效"
        
        # SQL 注入检查
        dangerous_keywords = ["DROP", "DELETE", "TRUNCATE"]
        if any(kw in query.upper() for kw in dangerous_keywords):
            logger.warning(f"潜在的 SQL 注入尝试：{query}")
            return "错误：不允许的操作"
        
        # 执行查询（模拟）
        import time
        time.sleep(0.1)  # 模拟网络延迟
        
        return f"查询结果：{query[:50]}..."
        
    except TimeoutError:
        logger.error("查询超时")
        return "错误：查询超时，请重试"
    except Exception as e:
        logger.error(f"查询失败：{e}")
        return f"错误：{str(e)}"

4.3 监控与日志

import logging
from contextlib import contextmanager
from langchain.tools import BaseTool
import time

# 配置日志
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)

class MonitoredTool(BaseTool):
    name: str = "monitored_tool"
    description: str = "带监控的工具"
    
    @contextmanager
    def _monitor(self, action: str, params: dict):
        """监控上下文"""
        start_time = time.time()
        logger = logging.getLogger(self.name)
        
        logger.info(f"开始 {action}, 参数：{params}")
        
        try:
            yield
            duration = time.time() - start_time
            logger.info(f"完成 {action}, 耗时：{duration:.2f}s")
        except Exception as e:
            duration = time.time() - start_time
            logger.error(f"失败 {action}, 耗时：{duration:.2f}s, 错误：{e}")
            raise
    
    def _run(self, param: str) -> str:
        with self._monitor("执行", {"param": param}):
            # 工具逻辑
            return f"结果：{param}"

5. 实战案例

案例：企业知识库问答系统

构建一个能够查询企业内部知识库的 AI 助手。

5.1 系统架构

┌─────────────────────────────────────────────────────────┐
│                    用户交互层                            │
│              (Chat Interface / API)                     │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                      Agent 层                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │ 意图识别    │  │ 工具选择    │  │ 结果整合    │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
└─────────────────────────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
    ┌──────────┐   ┌──────────┐   ┌──────────┐
    │文档搜索  │   │员工信息  │   │项目数据  │
    │  工具    │   │  工具    │   │  工具    │
    └──────────┘   └──────────┘   └──────────┘

5.2 工具实现

from langchain.tools import tool
from typing import List, Dict
import json

# 模拟数据库
DOCUMENTS = [
    {"id": 1, "title": "公司政策手册", "content": "...", "tags": ["政策", "HR"]},
    {"id": 2, "title": "技术架构文档", "content": "...", "tags": ["技术", "架构"]},
    {"id": 3, "title": "项目管理办法", "content": "...", "tags": ["项目", "管理"]},
]

EMPLOYEES = [
    {"id": 1, "name": "张三", "department": "技术部", "role": "工程师"},
    {"id": 2, "name": "李四", "department": "产品部", "role": "产品经理"},
]

PROJECTS = [
    {"id": 1, "name": "AI 平台", "status": "进行中", "lead": "张三"},
    {"id": 2, "name": "数据中台", "status": "规划中", "lead": "李四"},
]

@tool
def search_documents(query: str, limit: int = 5) -> str:
    """
    搜索公司内部文档
    
    Args:
        query: 搜索关键词
        limit: 返回结果数量（最多 10 个）
    """
    # 简单的关键词匹配
    results = [
        doc for doc in DOCUMENTS
        if any(kw in doc["title"].lower() or kw in doc["content"].lower()
               for kw in query.lower().split())
    ][:limit]
    
    return json.dumps([
        {"id": r["id"], "title": r["title"], "tags": r["tags"]}
        for r in results
    ], ensure_ascii=False, indent=2)

@tool
def get_employee_info(name: str) -> str:
    """
    获取员工信息
    
    Args:
        name: 员工姓名
    """
    employee = next((e for e in EMPLOYEES if e["name"] == name), None)
    if employee:
        return json.dumps(employee, ensure_ascii=False, indent=2)
    return f"未找到员工：{name}"

@tool
def list_projects(status: str = None) -> str:
    """
    列出项目列表
    
    Args:
        status: 可选，项目状态过滤（进行中/规划中/已完成）
    """
    projects = PROJECTS
    if status:
        projects = [p for p in projects if p["status"] == status]
    
    return json.dumps(projects, ensure_ascii=False, indent=2)

# 工具列表
tools = [search_documents, get_employee_info, list_projects]

5.3 Agent 集成

from langchain.agents import (
    AgentExecutor,
    create_tool_calling_agent,
)
from langchain_openai import ChatOpenAI

# 初始化 LLM
llm = ChatOpenAI(model="gpt-4-turbo", temperature=0)

# 创建 Agent
agent = create_tool_calling_agent(llm, tools, prompt)

# 创建执行器
agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,
    handle_parsing_errors=True,
    max_iterations=10,
)

# 使用示例
response = agent_executor.invoke({
    "input": "张三负责哪些项目？"
})

print(response["output"])

效果评估

| 指标 | 优化前 | 优化后 | 提升 | |------|--------|--------|------| | 响应时间 | 5.2s | 1.8s | 65% | | 准确率 | 72% | 91% | 26% | | 并发能力 | 10 req/s | 50 req/s | 400% | | 错误率 | 8% | 2% | 75% |

6. 常见问题

Q1: 工具调用失败怎么办？

答：常见原因和解决方案：

参数类型不匹配：确保工具函数的参数类型与 LLM 输出匹配
描述不清晰：完善工具的 description，让 LLM 更好地理解用途
权限问题：检查工具是否有访问资源的权限
网络问题：对于 API 工具，添加重试机制和超时处理

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1))
def api_call_tool(endpoint: str) -> str:
    """带重试的 API 调用"""
    response = requests.get(endpoint, timeout=10)
    response.raise_for_status()
    return response.text

Q2: 如何限制工具的使用范围？

答：可以通过以下方式限制：

访问控制：在工具内部实现权限检查
参数验证：使用 Pydantic 严格验证输入参数
调用频率限制：使用令牌桶算法限制调用频率
白名单机制：只允许特定用户或角色调用特定工具

from functools import wraps

def require_permission(permission: str):
    """权限装饰器"""
    def decorator(func):
        @wraps(func)
        def wrapper(user, *args, **kwargs):
            if permission not in user.get("permissions", []):
                raise PermissionError(f"缺少权限：{permission}")
            return func(user, *args, **kwargs)
        return wrapper
    return decorator

@tool
@require_permission("database_read")
def query_database(user: dict, query: str) -> str:
    """需要权限的数据库查询"""
    pass

Q3: 如何处理工具的副作用？

答：对于有副作用的工具（如写入操作），建议：

预检查机制：在执行前确认用户意图
事务支持：支持回滚操作
审计日志：记录所有操作
确认流程：对于危险操作，要求二次确认

@tool
def delete_record(record_id: str, confirm: bool = False) -> str:
    """
    删除记录（需要确认）
    
    Args:
        record_id: 记录 ID
        confirm: 必须为 True 才能执行删除
    """
    if not confirm:
        return "错误：删除操作需要设置 confirm=True"
    
    # 记录审计日志
    audit_log(f"删除记录：{record_id}")
    
    # 执行删除
    return f"已删除记录：{record_id}"

7. 总结与展望

核心要点回顾

工具设计原则：清晰的描述、明确的输入输出、完善的错误处理
性能优化：缓存、批量处理、异步执行
安全实践：输入验证、权限控制、审计日志
监控可观测性：日志、指标、追踪

未来方向

工具自动发现：基于 OpenAPI 规范自动生成工具
工具学习：让 Agent 从使用中学习工具的最佳用法
工具编排：复杂的工具链自动编排和优化
多模态工具：支持图像、音频等多模态输入输出

学习资源

LangGraph 复杂状态机设计模式

Wed, 01 Jul 2026 00:00:00 GMT

LangGraph 复杂状态机设计模式

1. 引言：为什么需要状态机设计模式

1.1 复杂工作流的挑战

在前一篇文章《LangChain 与 LangGraph 深度解析》中，我们介绍了 LangGraph 的基本概念和用法。然而，当面对真实世界的复杂应用时，仅仅知道 API 是远远不够的。开发者经常面临以下挑战：

工作流复杂度爆炸 — 随着功能增加，状态机图变得难以理解和维护
重复造轮子 — 相似的逻辑在不同项目中重复实现
设计决策困难 — 面对复杂需求，不知道如何组织状态和转换
调试困难 — 状态流转不清晰，问题难以定位
协作成本 — 团队成员对状态机设计缺乏统一理解

1.2 设计模式的价值

设计模式是软件工程的宝贵资产，它们提供了：

✅ 经过验证的解决方案 — 解决常见问题的最佳实践
✅ 通用语言 — 团队间高效沟通的基础
✅ 可复用模板 — 快速构建可靠系统
✅ 避免陷阱 — 前人踩过的坑，后人不必再踩

在 LangGraph 中，设计模式同样重要。通过掌握常见模式，你可以：

快速搭建复杂工作流
提高代码可维护性
降低调试成本
与社区高效交流

1.3 LangGraph 的模式支持

LangGraph 的设计天然适合模式化：

from langgraph.graph import StateGraph, END, START
from typing import TypedDict, Literal, Annotated

# 状态定义 — 模式的基础
class WorkflowState(TypedDict):
    input: str
    output: str
    metadata: dict

# 节点 — 模式的原子单元
def node_function(state: WorkflowState) -> WorkflowState:
    return {"output": "result"}

# 边 — 模式的连接方式
workflow = StateGraph(WorkflowState)
workflow.add_node("step", node_function)
workflow.add_edge(START, "step")
workflow.add_edge("step", END)

# 编译 — 模式的实例化
app = workflow.compile()

LangGraph 的核心抽象（状态、节点、边、条件）为设计模式提供了坚实基础。

1.4 本文结构

本文将系统介绍 LangGraph 中的设计模式，按复杂度递增组织：

基础模式 — 顺序、分支、并行
循环模式 — 迭代、重试
协作模式 — 多 Agent 架构
人机协作模式 — 人类审核与干预
高级模式 — 模式组合与嵌套
反模式与最佳实践 — 避免常见陷阱

每个模式都包含：

模式描述与适用场景
完整代码实现
可视化图结构
变体与扩展建议

让我们开始探索这些强大的设计模式！

2. 基础模式：顺序与分支

2.1 线性流水线模式

模式描述：最简单的模式，节点按固定顺序依次执行，无分支无循环。

适用场景：

数据预处理流水线
多步骤内容生成
顺序验证流程

核心特征：

节点顺序固定
无条件判断
状态单向流动

代码实现：

from langgraph.graph import StateGraph, END, START
from typing import TypedDict

# 定义状态
class PipelineState(TypedDict):
    raw_data: str
    cleaned_data: str
    analyzed_data: str
    final_output: str

# 节点 1：数据清洗
def clean_data(state: PipelineState) -> PipelineState:
    """清洗原始数据"""
    cleaned = state["raw_data"].strip().lower()
    return {"cleaned_data": cleaned}

# 节点 2：数据分析
def analyze_data(state: PipelineState) -> PipelineState:
    """分析清洗后的数据"""
    words = state["cleaned_data"].split()
    analysis = f"共 {len(words)} 个单词"
    return {"analyzed_data": analysis}

# 节点 3：生成输出
def generate_output(state: PipelineState) -> PipelineState:
    """生成最终输出"""
    output = f"原始：{state['cleaned_data']}\n分析：{state['analyzed_data']}"
    return {"final_output": output}

# 构建流水线
workflow = StateGraph(PipelineState)

# 添加节点
workflow.add_node("clean", clean_data)
workflow.add_node("analyze", analyze_data)
workflow.add_node("generate", generate_output)

# 设置顺序边
workflow.add_edge(START, "clean")
workflow.add_edge("clean", "analyze")
workflow.add_edge("analyze", "generate")
workflow.add_edge("generate", END)

# 编译
pipeline = workflow.compile()

# 执行
result = pipeline.invoke({"raw_data": "  Hello World  "})
print(result["final_output"])

可视化：

START → clean → analyze → generate → END

变体：

带日志的流水线：每个节点记录执行日志
带进度的流水线：状态中包含进度信息
可中断流水线：支持在任意节点暂停

2.2 条件分支模式

模式描述：根据状态内容决定下一步执行路径，实现条件逻辑。

适用场景：

基于输入类型的处理
质量检查与路由
A/B 测试分流

核心特征：

条件函数决定路径
多个可能的分支
分支可能汇合

代码实现：

from typing import Literal

class RouterState(TypedDict):
    input_type: str
    content: str
    result: str

# 条件函数：根据输入类型路由
def route_by_type(state: RouterState) -> Literal["text_processor", "image_processor", "error_handler"]:
    """根据输入类型选择处理路径"""
    input_type = state["input_type"].lower()
    
    if input_type == "text":
        return "text_processor"
    elif input_type == "image":
        return "image_processor"
    else:
        return "error_handler"

# 分支 1：文本处理
def process_text(state: RouterState) -> RouterState:
    """处理文本内容"""
    result = f"文本处理：{len(state['content'])} 个字符"
    return {"result": result}

# 分支 2：图像处理
def process_image(state: RouterState) -> RouterState:
    """处理图像内容"""
    result = f"图像处理：分析 {state['content']}"
    return {"result": result}

# 分支 3：错误处理
def handle_error(state: RouterState) -> RouterState:
    """处理未知类型"""
    result = f"错误：不支持的类型 {state['input_type']}"
    return {"result": result}

# 构建路由图
workflow = StateGraph(RouterState)

# 添加节点
workflow.add_node("text_processor", process_text)
workflow.add_node("image_processor", process_image)
workflow.add_node("error_handler", handle_error)

# 设置入口和条件边
workflow.add_edge(START, "router")
workflow.add_conditional_edges(
    "router",  # 从哪个节点出发
    route_by_type,  # 条件函数
    {
        "text_processor": "text_processor",
        "image_processor": "image_processor",
        "error_handler": "error_handler"
    }
)

# 所有分支汇合到 END
workflow.add_edge("text_processor", END)
workflow.add_edge("image_processor", END)
workflow.add_edge("error_handler", END)

# 编译
router = workflow.compile()

# 测试不同路径
print(router.invoke({"input_type": "text", "content": "Hello"}))
print(router.invoke({"input_type": "image", "content": "image_url"}))
print(router.invoke({"input_type": "audio", "content": "audio_data"}))

可视化：

              → text_processor →
             ↘
START → router → image_processor → END
             ↘
              → error_handler →

高级技巧：

多层级路由：

def primary_router(state: RouterState) -> Literal["category_a", "category_b"]:
    """一级路由"""
    return "category_a" if len(state["content"]) > 100 else "category_b"

def secondary_router(state: RouterState) -> Literal["fast_path", "thorough_path"]:
    """二级路由"""
    return "fast_path" if state.get("urgent") else "thorough_path"

# 嵌套条件边
workflow.add_conditional_edges("entry", primary_router, {...})
workflow.add_conditional_edges("category_a", secondary_router, {...})

动态条件：

def dynamic_threshold(state: RouterState) -> Literal["approve", "review"]:
    """基于动态阈值的条件"""
    threshold = state.get("threshold", 0.5)
    score = state.get("confidence_score", 0)
    return "approve" if score >= threshold else "review"

2.3 并行执行模式

模式描述：多个节点同时执行，提高处理效率。

适用场景：

多源数据收集
并行特征提取
多模型投票

核心特征：

节点并发执行
结果需要合并
可能涉及同步等待

代码实现：

import asyncio
from typing import List

class ParallelState(TypedDict):
    query: str
    search_results: List[str]
    analysis_results: List[str]
    combined_output: str

# 并行任务 1：网络搜索
async def web_search(state: ParallelState) -> ParallelState:
    """执行网络搜索"""
    await asyncio.sleep(0.5)  # 模拟异步操作
    return {"search_results": [f"搜索结果 {i}" for i in range(3)]}

# 并行任务 2：知识库查询
async def knowledge_base_query(state: ParallelState) -> ParallelState:
    """查询知识库"""
    await asyncio.sleep(0.3)
    return {"analysis_results": [f"知识条目 {i}" for i in range(2)]}

# 合并结果
def merge_results(state: ParallelState) -> ParallelState:
    """合并并行结果"""
    combined = {
        "search": state.get("search_results", []),
        "knowledge": state.get("analysis_results", [])
    }
    output = f"搜索：{len(combined['search'])}条，知识：{len(combined['knowledge'])}条"
    return {"combined_output": output}

# 构建并行图
workflow = StateGraph(ParallelState)

# 添加并行节点
workflow.add_node("search", web_search)
workflow.add_node("knowledge", knowledge_base_query)
workflow.add_node("merge", merge_results)

# 并行分支
workflow.add_edge(START, "search")
workflow.add_edge(START, "knowledge")

# 汇合点
workflow.add_edge("search", "merge")
workflow.add_edge("knowledge", "merge")
workflow.add_edge("merge", END)

# 编译
parallel_app = workflow.compile()

# 执行
result = parallel_app.invoke({"query": "人工智能"})
print(result["combined_output"])

可视化：

       → search →
      ↘          \
START             → merge → END
      /          /
       → knowledge →

注意事项：

并行节点必须异步（async def）才能真正并发
合并节点需要等待所有并行分支完成
状态合并策略需要精心设计（覆盖、合并、选择）

状态合并策略：

from typing import Annotated

def merge_lists(left: List[str], right: List[str]) -> List[str]:
    """合并两个列表"""
    return left + right

class MergedState(TypedDict):
    results: Annotated[List[str], merge_lists]

3. 循环模式：迭代与重试

3.1 固定次数迭代模式

模式描述：节点执行固定次数，每次迭代更新状态。

适用场景：

渐进式内容优化
多轮推理
分步细化

核心特征：

计数器控制迭代
状态累积
确定性终止

代码实现：

from typing import Literal

class IterationState(TypedDict):
    prompt: str
    current_output: str
    iteration: int
    max_iterations: int
    history: list

def generate_content(state: IterationState) -> IterationState:
    """生成或优化内容"""
    # 模拟 LLM 生成
    if state["iteration"] == 0:
        output = f"初始版本：{state['prompt']}"
    else:
        output = f"优化版本 {state['iteration']}: 基于 '{state['current_output']}' 改进"
    
    return {
        "current_output": output,
        "history": state.get("history", []) + [output]
    }

def check_iterations(state: IterationState) -> Literal["continue", "end"]:
    """检查是否继续迭代"""
    if state["iteration"] < state["max_iterations"]:
        return "continue"
    return "end"

# 构建迭代图
workflow = StateGraph(IterationState)

workflow.add_node("generate", generate_content)

workflow.add_edge(START, "generate")

workflow.add_conditional_edges(
    "generate",
    check_iterations,
    {
        "continue": "generate",  # 循环回自身
        "end": END
    }
)

# 在 generate 节点后自动增加迭代计数
# 实际使用中可以通过状态更新器实现

iteration_app = workflow.compile()

result = iteration_app.invoke({
    "prompt": "写一篇关于 AI 的文章",
    "current_output": "",
    "iteration": 0,
    "max_iterations": 3,
    "history": []
})

print(f"最终输出：{result['current_output']}")
print(f"迭代历史：{result['history']}")

可视化：

       ┌─────────────┐
       ↓             │
START → generate ────┘ (最多 N 次)
       ↓
      END

3.2 条件终止循环模式

模式描述：循环执行直到满足特定条件，而非固定次数。

适用场景：

直到答案满意
直到收敛
直到达到质量标准

核心特征：

条件函数判断终止
可能需要最大次数保护
状态质量评估

代码实现：

class ConvergenceState(TypedDict):
    query: str
    answer: str
    quality_score: float
    threshold: float
    iteration: int
    max_iterations: int

def refine_answer(state: ConvergenceState) -> ConvergenceState:
    """优化答案"""
    # 模拟答案优化和质量评估
    iteration = state["iteration"]
    
    # 模拟质量分数逐渐提高
    quality_score = min(0.95, 0.5 + iteration * 0.15)
    
    answer = f"优化后的答案 (质量：{quality_score:.2f})"
    
    return {
        "answer": answer,
        "quality_score": quality_score,
        "iteration": iteration + 1
    }

def should_continue_refining(state: ConvergenceState) -> Literal["refine", "done"]:
    """判断是否继续优化"""
    # 达到质量阈值或最大迭代次数则停止
    if state["quality_score"] >= state["threshold"]:
        return "done"
    if state["iteration"] >= state["max_iterations"]:
        return "done"
    return "refine"

# 构建条件终止图
workflow = StateGraph(ConvergenceState)

workflow.add_node("refine", refine_answer)

workflow.add_edge(START, "refine")

workflow.add_conditional_edges(
    "refine",
    should_continue_refining,
    {
        "refine": "refine",
        "done": END
    }
)

convergence_app = workflow.compile()

result = convergence_app.invoke({
    "query": "量子计算原理",
    "answer": "",
    "quality_score": 0.0,
    "threshold": 0.85,
    "iteration": 0,
    "max_iterations": 10
})

print(f"最终答案：{result['answer']}")
print(f"质量分数：{result['quality_score']:.2f}")
print(f"迭代次数：{result['iteration']}")

3.3 带退避的重试模式

模式描述：操作失败时自动重试，使用退避策略避免频繁失败。

适用场景：

API 调用失败重试
网络请求重试
不稳定操作容错

核心特征：

失败检测
退避策略（线性、指数）
最大重试次数

代码实现：

import time
import random
from typing import Literal

class RetryState(TypedDict):
    task: str
    result: str
    attempt: int
    max_attempts: int
    base_delay: float
    errors: list

def execute_task(state: RetryState) -> RetryState:
    """执行可能失败的任务"""
    attempt = state["attempt"]
    
    # 模拟随机失败（前两次失败，第三次成功）
    if attempt < 2:
        error = f"第 {attempt} 次尝试失败：临时错误"
        return {
            "errors": state.get("errors", []) + [error],
            "result": None
        }
    else:
        return {
            "result": f"任务成功完成 (第 {attempt} 次尝试)",
            "errors": state.get("errors", [])
        }

def check_result(state: RetryState) -> Literal["retry", "success", "give_up"]:
    """检查结果并决定下一步"""
    if state["result"] is not None:
        return "success"
    
    if state["attempt"] >= state["max_attempts"]:
        return "give_up"
    
    return "retry"

def apply_backoff(state: RetryState) -> RetryState:
    """应用退避延迟"""
    # 指数退避：delay = base_delay * 2^(attempt-1)
    delay = state["base_delay"] * (2 ** (state["attempt"] - 1))
    
    # 添加随机抖动
    jitter = delay * 0.2 * (random.random() - 0.5)
    actual_delay = delay + jitter
    
    print(f"第 {state['attempt']} 次失败，{actual_delay:.2f}秒后重试...")
    # time.sleep(actual_delay)  # 实际使用取消注释
    
    return {"attempt": state["attempt"] + 1}

# 构建重试图
workflow = StateGraph(RetryState)

workflow.add_node("execute", execute_task)
workflow.add_node("backoff", apply_backoff)

workflow.add_edge(START, "execute")

workflow.add_conditional_edges(
    "execute",
    check_result,
    {
        "retry": "backoff",
        "success": END,
        "give_up": END
    }
)

workflow.add_edge("backoff", "execute")

retry_app = workflow.compile()

result = retry_app.invoke({
    "task": "调用外部 API",
    "result": None,
    "attempt": 1,
    "max_attempts": 5,
    "base_delay": 1.0,
    "errors": []
})

print(f"最终结果：{result['result']}")
print(f"失败记录：{result['errors']}")

退避策略变体：

# 线性退避
delay = state["base_delay"] * state["attempt"]

# 指数退避（推荐）
delay = state["base_delay"] * (2 ** state["attempt"])

# 斐波那契退避
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)
delay = state["base_delay"] * fibonacci(state["attempt"])

4. 协作模式：多 Agent 架构

4.1 主管 - 工人模式（Manager-Worker）

模式描述：主管 Agent 负责任务分解和协调，工人 Agent 负责具体执行。

适用场景：

复杂任务分解
并行任务分配
结果整合

核心特征：

分层架构
任务分发
结果汇总

代码实现：

from typing import List, Literal

class ManagerWorkerState(TypedDict):
    task: str
    subtasks: List[str]
    results: List[str]
    current_subtask: int
    final_output: str

def manager_decompose(state: ManagerWorkerState) -> ManagerWorkerState:
    """主管：分解任务"""
    task = state["task"]
    
    # 模拟任务分解
    subtasks = [
        f"子任务 1: 研究 {task} 的背景",
        f"子任务 2: 分析 {task} 的核心问题",
        f"子任务 3: 提出 {task} 的解决方案"
    ]
    
    return {"subtasks": subtasks, "current_subtask": 0}

def worker_execute(state: ManagerWorkerState) -> ManagerWorkerState:
    """工人：执行子任务"""
    current = state["current_subtask"]
    subtask = state["subtasks"][current]
    
    # 模拟执行
    result = f"[完成] {subtask}\n详细内容：..."
    
    results = state.get("results", []) + [result]
    
    return {
        "results": results,
        "current_subtask": current + 1
    }

def check_all_subtasks_done(state: ManagerWorkerState) -> Literal["continue", "aggregate"]:
    """检查是否所有子任务完成"""
    if state["current_subtask"] < len(state["subtasks"]):
        return "continue"
    return "aggregate"

def manager_aggregate(state: ManagerWorkerState) -> ManagerWorkerState:
    """主管：汇总结果"""
    results = state["results"]
    
    final_output = "=== 任务执行报告 ===\n\n"
    for i, result in enumerate(results, 1):
        final_output += f"{i}. {result}\n\n"
    
    final_output += "=== 总结 ===\n所有子任务已完成。"
    
    return {"final_output": final_output}

# 构建主管 - 工人图
workflow = StateGraph(ManagerWorkerState)

workflow.add_node("manager_decompose", manager_decompose)
workflow.add_node("worker_execute", worker_execute)
workflow.add_node("manager_aggregate", manager_aggregate)

workflow.add_edge(START, "manager_decompose")
workflow.add_edge("manager_decompose", "worker_execute")

workflow.add_conditional_edges(
    "worker_execute",
    check_all_subtasks_done,
    {
        "continue": "worker_execute",
        "aggregate": "manager_aggregate"
    }
)

workflow.add_edge("manager_aggregate", END)

mw_app = workflow.compile()

result = mw_app.invoke({
    "task": "设计一个推荐系统",
    "subtasks": [],
    "results": [],
    "current_subtask": 0,
    "final_output": ""
})

print(result["final_output"])

可视化：

START → manager_decompose → worker_execute ──(循环)──┐
                                           ↓         │
                                  check ──→│         │
                                           ↓         │
                                  manager_aggregate ←─┘
                                           ↓
                                          END

4.2 投票与共识模式

模式描述：多个 Agent 独立给出答案，通过投票或共识机制确定最终结果。

适用场景：

提高答案准确性
减少单个模型偏差
重要决策

核心特征：

并行独立评估
投票/共识机制
可能包含仲裁

代码实现：

from typing import List, Literal

class VotingState(TypedDict):
    question: str
    votes: List[str]
    current_voter: int
    total_voters: int
    final_answer: str

def voter_answer(state: VotingState) -> VotingState:
    """投票者：给出答案"""
    voter_id = state["current_voter"]
    
    # 模拟不同投票者的答案
    answers = {
        0: "答案 A: 基于方法 1 的分析",
        1: "答案 A: 基于方法 2 的分析",
        2: "答案 B: 基于方法 3 的分析"
    }
    
    answer = answers.get(voter_id, f"答案：投票者 {voter_id}")
    votes = state.get("votes", []) + [answer]
    
    return {
        "votes": votes,
        "current_voter": voter_id + 1
    }

def tally_votes(state: VotingState) -> VotingState:
    """统计票数"""
    votes = state["votes"]
    
    # 简单统计（实际应使用更复杂的语义相似度）
    vote_counts = {}
    for vote in votes:
        answer_type = vote.split(":")[0]  # 提取答案类型
        vote_counts[answer_type] = vote_counts.get(answer_type, 0) + 1
    
    # 找出得票最多的答案
    winner = max(vote_counts, key=vote_counts.get)
    final_answer = f"{winner} (得票：{vote_counts[winner]}/{len(votes)})"
    
    return {"final_answer": final_answer, "vote_counts": vote_counts}

# 构建投票图
workflow = StateGraph(VotingState)

workflow.add_node("voter", voter_answer)
workflow.add_node("tally", tally_votes)

workflow.add_edge(START, "voter")

workflow.add_conditional_edges(
    "voter",
    lambda s: "tally" if s["current_voter"] >= s["total_voters"] else "voter",
    {
        "voter": "voter",
        "tally": "tally"
    }
)

workflow.add_edge("tally", END)

voting_app = workflow.compile()

result = voting_app.invoke({
    "question": "哪种算法最适合此场景？",
    "votes": [],
    "current_voter": 0,
    "total_voters": 3,
    "final_answer": ""
})

print(f"最终答案：{result['final_answer']}")
print(f"投票统计：{result.get('vote_counts', {})}")

4.3 流水线协作模式

模式描述：多个 Agent 按顺序协作，每个负责特定阶段。

适用场景：

内容创作流水线
代码开发流程
数据分析流程

核心特征：

阶段划分清晰
状态传递
专业化分工

代码实现：

class PipelineState(TypedDict):
    topic: str
    research: str
    outline: str
    draft: str
    review: str
    final_article: str

def researcher(state: PipelineState) -> PipelineState:
    """研究阶段：收集信息"""
    research = f"""
    关于 {state['topic']} 的研究结果:
    - 关键点 1: ...
    - 关键点 2: ...
    - 数据支持：...
    """
    return {"research": research}

def outliner(state: PipelineState) -> PipelineState:
    """大纲阶段：组织结构"""
    outline = f"""
    文章大纲 - {state['topic']}:
    1. 引言
    2. 核心概念
    3. 案例分析
    4. 最佳实践
    5. 总结
    """
    return {"outline": outline}

def writer(state: PipelineState) -> PipelineState:
    """写作阶段：生成草稿"""
    draft = f"""
    # {state['topic']}
    
    ## 引言
    基于研究：{state['research'][:50]}...
    
    ## 正文
    按照大纲展开...
    
    ## 总结
    核心观点总结...
    """
    return {"draft": draft}

def reviewer(state: PipelineState) -> PipelineState:
    """评审阶段：质量检查"""
    review = """
    评审意见:
    ✅ 结构清晰
    ✅ 论据充分
    ⚠️ 建议增加案例
    ✅ 语言流畅
    
    评分：85/100
    """
    return {"review": review}

def finalizer(state: PipelineState) -> PipelineState:
    """定稿阶段：整合输出"""
    final_article = f"""
    {state['draft']}
    
    ---
    
    评审反馈：{state['review']}
    """
    return {"final_article": final_article}

# 构建流水线协作图
workflow = StateGraph(PipelineState)

workflow.add_node("researcher", researcher)
workflow.add_node("outliner", outliner)
workflow.add_node("writer", writer)
workflow.add_node("reviewer", reviewer)
workflow.add_node("finalizer", finalizer)

# 顺序连接
workflow.add_edge(START, "researcher")
workflow.add_edge("researcher", "outliner")
workflow.add_edge("outliner", "writer")
workflow.add_edge("writer", "reviewer")
workflow.add_edge("reviewer", "finalizer")
workflow.add_edge("finalizer", END)

pipeline_app = workflow.compile()

result = pipeline_app.invoke({"topic": "机器学习入门", "research": "", "outline": "", "draft": "", "review": "", "final_article": ""})

print(result["final_article"])

5. 人机协作模式

5.1 人类审核节点

模式描述：在关键节点暂停执行，等待人类审核或决策。

适用场景：

内容发布前审核
高风险决策确认
质量把关

核心特征：

中断执行流
等待人类输入
恢复执行

代码实现：

from langgraph.graph import interrupt
from typing import Literal

class HumanInTheLoopState(TypedDict):
    content: str
    human_approved: bool
    human_feedback: str
    iteration: int

def generate_content(state: HumanInTheLoopState) -> HumanInTheLoopState:
    """生成内容"""
    if state["iteration"] == 0:
        content = "初始版本：这是一篇测试文章..."
    else:
        content = f"修订版本 {state['iteration']}: 根据反馈 '{state['human_feedback']}' 修改..."
    
    return {"content": content}

def human_review(state: HumanInTheLoopState) -> HumanInTheLoopState:
    """人类审核节点"""
    print(f"\n=== 等待人类审核 ===")
    print(f"当前内容：{state['content']}")
    
    # 中断执行，等待人类输入
    # 实际使用中，这里会暂停并等待外部输入
    approval = input("是否批准？(y/n/r 修订): ")
    
    if approval == 'y':
        return {"human_approved": True, "human_feedback": ""}
    elif approval == 'n':
        return {"human_approved": False, "human_feedback": ""}
    else:
        feedback = input("提供修订意见：")
        return {"human_approved": False, "human_feedback": feedback}

def decide_next(state: HumanInTheLoopState) -> Literal["approve", "revise", "reject"]:
    """决定下一步"""
    if state["human_approved"]:
        return "approve"
    elif state["iteration"] >= 3:
        return "reject"  # 达到最大修订次数
    return "revise"

# 构建人机协作图
workflow = StateGraph(HumanInTheLoopState)

workflow.add_node("generate", generate_content)
workflow.add_node("review", human_review)

workflow.add_edge(START, "generate")
workflow.add_edge("generate", "review")

workflow.add_conditional_edges(
    "review",
    decide_next,
    {
        "approve": END,
        "revise": "generate",
        "reject": END
    }
)

# 编译时设置中断点
app = workflow.compile(interrupt_before=["review"])

# 执行
result = app.invoke({
    "content": "",
    "human_approved": False,
    "human_feedback": "",
    "iteration": 0
})

print(f"\n最终结果：{result['content']}")

使用 interrupt 工具：

from langgraph.graph import interrupt

def human_approval_node(state):
    """使用 interrupt 工具"""
    # 抛出中断，暂停执行
    human_decision = interrupt({
        "content": state["content"],
        "question": "是否批准此内容？"
    })
    
    return {
        "human_approved": human_decision.get("approved", False),
        "human_feedback": human_decision.get("feedback", "")
    }

5.2 中断与恢复

模式描述：支持在任意点暂停和恢复执行，保持状态持久化。

核心特征：

状态检查点
线程管理
断点续传

代码实现：

from langgraph.checkpoint.memory import MemorySaver

# 创建检查点存储器
checkpointer = MemorySaver()

# 编译时传入
app = workflow.compile(
    checkpointer=checkpointer,
    interrupt_before=["human_review"]
)

# 创建线程
config = {"configurable": {"thread_id": "conversation_123"}}

# 执行到中断点
result = app.invoke(
    {"content": "初始内容", "iteration": 0},
    config
)
# 此时暂停，等待人类输入

# 恢复执行，传入人类决策
result = app.invoke(
    {"human_approved": True, "human_feedback": ""},
    config
)
# 从断点继续执行

多线程管理：

# 不同用户使用不同线程
user1_config = {"configurable": {"thread_id": "user_001"}}
user2_config = {"configurable": {"thread_id": "user_002"}}

# 独立执行，互不干扰
app.invoke({"input": "user1 data"}, user1_config)
app.invoke({"input": "user2 data"}, user2_config)

5.3 反馈循环

模式描述：人类反馈直接影响后续生成，形成闭环优化。

代码实现：

class FeedbackLoopState(TypedDict):
    prompt: str
    output: str
    feedback: str
    quality_score: float
    iterations: int

def generate(state: FeedbackLoopState) -> FeedbackLoopState:
    """生成内容"""
    # 根据反馈调整生成
    context = state["feedback"] if state["feedback"] else "无反馈"
    output = f"生成内容 (基于反馈：{context})"
    
    return {"output": output}

def get_feedback(state: FeedbackLoopState) -> FeedbackLoopState:
    """获取人类反馈"""
    # 模拟反馈（实际为真实人类输入）
    feedback = "建议增加更多细节"
    score = 0.8
    
    return {
        "feedback": feedback,
        "quality_score": score
    }

def should_improve(state: FeedbackLoopState) -> Literal["improve", "done"]:
    """判断是否需要改进"""
    if state["quality_score"] >= 0.9:
        return "done"
    if state["iterations"] >= 5:
        return "done"
    return "improve"

workflow = StateGraph(FeedbackLoopState)

workflow.add_node("generate", generate)
workflow.add_node("feedback", get_feedback)

workflow.add_edge(START, "generate")
workflow.add_edge("generate", "feedback")

workflow.add_conditional_edges(
    "feedback",
    should_improve,
    {
        "improve": "generate",
        "done": END
    }
)

feedback_app = workflow.compile()

result = feedback_app.invoke({
    "prompt": "写一篇文章",
    "output": "",
    "feedback": "",
    "quality_score": 0.0,
    "iterations": 0
})

print(f"最终输出：{result['output']}")
print(f"质量分数：{result['quality_score']}")

6. 高级模式：模式组合

6.1 嵌套状态机

模式描述：状态机中包含子状态机，处理复杂分层逻辑。

适用场景：

复杂任务分层
模块化设计
代码复用

代码实现：

# 子图：内容生成模块
def create_content_subgraph():
    """创建内容生成子图"""
    class ContentState(TypedDict):
        topic: str
        draft: str
        refined: str
    
    def write_draft(state: ContentState) -> ContentState:
        return {"draft": f"草稿：{state['topic']}"}
    
    def refine_draft(state: ContentState) -> ContentState:
        return {"refined": f"精修：{state['draft']}"}
    
    subgraph = StateGraph(ContentState)
    subgraph.add_node("write", write_draft)
    subgraph.add_node("refine", refine_draft)
    subgraph.add_edge(START, "write")
    subgraph.add_edge("write", "refine")
    subgraph.add_edge("refine", END)
    
    return subgraph.compile()

# 主图：使用子图
class MainState(TypedDict):
    topic: str
    content: str
    reviewed: bool

def prepare_topic(state: MainState) -> MainState:
    """准备主题"""
    return {"topic": state["topic"].upper()}

def review_content(state: MainState) -> MainState:
    """审核内容"""
    return {"reviewed": True}

main_workflow = StateGraph(MainState)

# 添加子图为节点
content_subgraph = create_content_subgraph()
main_workflow.add_node("content_generator", content_subgraph)

main_workflow.add_node("prepare", prepare_topic)
main_workflow.add_node("review", review_content)

main_workflow.add_edge(START, "prepare")
main_workflow.add_edge("prepare", "content_generator")
main_workflow.add_edge("content_generator", "review")
main_workflow.add_edge("review", END)

main_app = main_workflow.compile()

result = main_app.invoke({"topic": "人工智能", "content": "", "reviewed": False})
print(f"结果：{result}")

6.2 模式混合实践

模式描述：在实际应用中组合多种模式。

综合案例：智能内容生产系统

class ContentSystemState(TypedDict):
    topic: str
    research_results: list
    draft: str
    human_approved: bool
    feedback: str
    iteration: int
    final_content: str

# 1. 并行研究（并行模式）
async def parallel_research(state: ContentSystemState) -> ContentSystemState:
    tasks = [
        search_web(state["topic"]),
        query_knowledge_base(state["topic"]),
        analyze_trends(state["topic"])
    ]
    results = await asyncio.gather(*tasks)
    return {"research_results": results}

# 2. 迭代生成（循环模式）
def iterative_generation(state: ContentSystemState) -> ContentSystemState:
    context = "\n".join(state["research_results"])
    feedback = state.get("feedback", "")
    
    draft = f"基于研究和反馈 {feedback} 生成的内容..."
    return {"draft": draft}

# 3. 人类审核（人机协作模式）
def human_approval(state: ContentSystemState) -> ContentSystemState:
    approval = interrupt({"draft": state["draft"]})
    return {
        "human_approved": approval.get("approved", False),
        "feedback": approval.get("feedback", "")
    }

# 4. 多模式组合
workflow = StateGraph(ContentSystemState)

workflow.add_node("research", parallel_research)
workflow.add_node("generate", iterative_generation)
workflow.add_node("approve", human_approval)

workflow.add_edge(START, "research")
workflow.add_edge("research", "generate")
workflow.add_edge("generate", "approve")

workflow.add_conditional_edges(
    "approve",
    lambda s: "generate" if not s["human_approved"] else "end",
    {"generate": "generate", "end": END}
)

system_app = workflow.compile(interrupt_before=["approve"])

7. 反模式与最佳实践

7.1 常见设计陷阱

陷阱 1：状态爆炸

# ❌ 反模式：状态包含过多字段
class BadState(TypedDict):
    field1: str
    field2: str
    # ... 50+ 字段
    field50: str

# ✅ 最佳实践：状态模块化
class ResearchState(TypedDict):
    query: str
    results: list

class WritingState(TypedDict):
    research: ResearchState
    draft: str

陷阱 2：循环依赖

# ❌ 反模式：节点 A 依赖 B，B 依赖 A
def node_a(state):
    return node_b(state)  # 直接调用其他节点

# ✅ 最佳实践：通过状态传递数据
def node_a(state):
    return {"data": process(state["input"])}

def node_b(state):
    return {"result": use(state["data"])}

陷阱 3：忽略错误处理

# ❌ 反模式：没有错误处理
def risky_node(state):
    result = might_fail()
    return {"result": result}

# ✅ 最佳实践：try-catch 或重试模式
def safe_node(state):
    try:
        result = might_fail()
    except Exception as e:
        return {"error": str(e), "result": None}
    return {"result": result}

7.2 性能优化建议

1. 并行化独立任务

# 使用并行模式加速独立操作
async def parallel_processing(state):
    results = await asyncio.gather(
        task1(state["data"]),
        task2(state["data"]),
        task3(state["data"])
    )
    return {"results": results}

2. 缓存中间结果

from functools import lru_cache

@lru_cache(maxsize=128)
def expensive_computation(input_data):
    return compute(input_data)

3. 流式处理大数据

def stream_processor(state):
    for chunk in state["large_data"]:
        yield process(chunk)

7.3 可维护性原则

1. 单一职责

每个节点只做一件事，便于测试和复用。

2. 明确的状态契约

class State(TypedDict):
    """
    状态说明：
    - input: 用户输入（只读）
    - output: 节点输出（写入）
    - metadata: 元数据（可选）
    """
    input: str
    output: str
    metadata: dict

3. 可视化文档

# 生成可视化图
app.get_graph().draw_mermaid_png(output_path="workflow.png")

8. 实战案例：完整工作流构建

8.1 需求分析

场景：构建一个智能客服系统

需求：

理解用户意图
检索相关知识
生成回答
质量检查
人类审核（必要时）
发送回答

8.2 模式选择

条件分支：意图识别路由
并行执行：多源知识检索
循环模式：回答优化
人机协作：复杂问题审核

8.3 代码实现

class CustomerServiceState(TypedDict):
    user_query: str
    intent: str
    knowledge: list
    draft_answer: str
    quality_score: float
    human_reviewed: bool
    final_answer: str

# 意图识别
def classify_intent(state: CustomerServiceState) -> CustomerServiceState:
    # 模拟意图分类
    intent = "technical_support"  # 实际使用 LLM
    return {"intent": intent}

# 并行知识检索
async def retrieve_knowledge(state: CustomerServiceState) -> CustomerServiceState:
    results = await asyncio.gather(
        search_faq(state["user_query"]),
        search_docs(state["intent"]),
        query_database(state["user_query"])
    )
    return {"knowledge": [r for r in results if r]}

# 生成回答
def generate_answer(state: CustomerServiceState) -> CustomerServiceState:
    context = "\n".join(state["knowledge"])
    answer = f"基于 {len(state['knowledge'])} 个知识源的回答..."
    return {"draft_answer": answer}

# 质量检查
def check_quality(state: CustomerServiceState) -> CustomerServiceState:
    # 模拟质量评分
    score = 0.85
    return {"quality_score": score}

# 人类审核（低质量时）
def human_review(state: CustomerServiceState) -> CustomerSystemState:
    if state["quality_score"] < 0.8:
        decision = interrupt({"answer": state["draft_answer"]})
        return {"human_reviewed": True, "final_answer": decision["revised_answer"]}
    return {"human_reviewed": False, "final_answer": state["draft_answer"]}

# 构建完整工作流
workflow = StateGraph(CustomerServiceState)

workflow.add_node("classify", classify_intent)
workflow.add_node("retrieve", retrieve_knowledge)
workflow.add_node("generate", generate_answer)
workflow.add_node("check", check_quality)
workflow.add_node("review", human_review)

workflow.add_edge(START, "classify")
workflow.add_edge("classify", "retrieve")
workflow.add_edge("retrieve", "generate")
workflow.add_edge("generate", "check")
workflow.add_edge("check", "review")
workflow.add_edge("review", END)

cs_app = workflow.compile(interrupt_before=["review"])

# 执行
result = cs_app.invoke({"user_query": "如何重置密码？"})
print(f"最终回答：{result['final_answer']}")

8.4 测试与调试

# 单元测试单个节点
def test_classify_intent():
    state = {"user_query": "密码问题"}
    result = classify_intent(state)
    assert result["intent"] == "account_management"

# 集成测试完整流程
def test_full_workflow():
    result = cs_app.invoke({"user_query": "测试问题"})
    assert "final_answer" in result
    assert len(result["final_answer"]) > 0

# 可视化调试
cs_app.get_graph().draw_mermaid_png("customer_service.png")

9. 总结与资源

9.1 模式速查表

| 模式 | 适用场景 | 复杂度 | |------|---------|--------| | 线性流水线 | 顺序处理 | ⭐ | | 条件分支 | 路由决策 | ⭐⭐ | | 并行执行 | 并发任务 | ⭐⭐ | | 固定迭代 | 次数确定 | ⭐⭐ | | 条件终止 | 质量导向 | ⭐⭐⭐ | | 重试退避 | 容错处理 | ⭐⭐ | | 主管 - 工人 | 任务分解 | ⭐⭐⭐ | | 投票共识 | 提高准确性 | ⭐⭐⭐ | | 人类审核 | 质量把关 | ⭐⭐⭐ | | 嵌套状态机 | 分层设计 | ⭐⭐⭐⭐ |

9.2 学习路径建议

入门：掌握线性、条件、并行基础模式
进阶：学习循环和协作模式
高级：实践模式组合和嵌套
专家：自定义模式和框架扩展

9.3 推荐资源

9.4 下一步

在实际项目中应用这些模式
贡献新的模式到社区
关注 LangGraph 官方更新

感谢阅读！ 希望这篇文章能帮助你构建更强大、更可靠的 LangGraph 应用。🚀

如何成为一名 LLM 算法工程师

Wed, 20 May 2026 00:00:00 GMT

如何成为一名 LLM 算法工程师

这篇文章记录如何规划 LLM 算法工程师的学习路径，也希望给同样在入门和进阶的人一个可复用的参考。

不停留在“会调用大模型 API”这个层面，也不想只读论文、看概念，却没有可以复现和交付的东西。目标是逐步建立一套能落地的 LLM 算法能力：理解模型机制，能处理和构造数据，能做训练与后训练实验，能搭建可评估的 RAG/Agent 系统，也能把模型用可观测、可控成本的方式部署到业务场景里。

这条路线会按“先跑通、再理解、再优化、最后交付”的节奏推进。每个阶段都会留下明确产出，避免学习变成碎片化收藏。

目标画像

LLM 算法工程师最终需要具备四层能力：

| 能力层 | 我要回答的问题 | 阶段产出 | |------|------|------| | 基础层 | 我能否稳定训练、调试、复现实验？ | PyTorch 训练循环、实验记录、误差分析 | | 模型层 | 我是否理解 Transformer、生成、微调和对齐？ | mini Transformer、SFT/LoRA/DPO 实验报告 | | 系统层 | 我能否把模型接入数据、工具、检索和评估？ | RAG 服务、评估集、可观测 trace | | 交付层 | 我能否解释成本、延迟、效果和风险？ | benchmark、上线方案、模型卡、复盘文档 |

四层交替推进。只学理论会缺少工程判断，只堆框架会很难定位效果问题，只追大模型新闻会缺少可复用的基本功。

方向选择

LLM 算法岗位有很多分支，需要先确定主线，再补齐旁支。

| 方向 | 我为什么关注 | 重点能力 | 我可以做的项目 | |------|------|------|------| | LLM 应用算法 | 最容易和真实业务结合，也最适合快速形成作品 | Prompt、RAG、Agent、评估、业务闭环 | 企业知识库问答、智能客服、BI Agent | | 模型微调与后训练 | 能建立更深的算法壁垒，避免只会调 API | 数据构造、SFT、LoRA、DPO/GRPO、训练诊断 | 领域指令模型、偏好优化实验 | | 推理部署与性能优化 | 私有化部署和成本控制是企业场景的关键问题 | vLLM、量化、批处理、KV cache、吞吐延迟权衡 | 私有化模型服务、推理网关 | | 研究复现与评测 | 训练我判断新方法是否真的有效 | paper reading、benchmark、ablation、误差归因 | 论文复现、模型能力评估 |

当前的主线会先放在“LLM 应用算法 + 评估”上，因为它最容易形成闭环；第二阶段再深入“微调与后训练”；如果后续有明确私有化部署需求，会把“推理部署”作为差异化能力继续加强。

Milestone 进度看板

这是后续持续更新学习进度的主表。每完成一个 milestone，不只勾选状态，还要补上证据：代码仓库、实验截图、指标表、博客文章或复盘结论。

| Milestone | 建议周期 | 状态 | 完成度 | 验收产出 | 证据链接 / 笔记 | |------|------|------|------|------|------| | M0：定位与环境基线 | 第 1 周 | [ ] 未开始 [x] 进行中 [ ] 完成 | 10% | 能在本机或云 GPU 跑通一个开源 LLM 推理样例 | 当前已完成学习规划 | | M1：Python、数学与 PyTorch 基础 | 第 2-4 周 | [ ] 未开始 [ ] 进行中 [ ] 完成 | 0% | 独立写出训练循环，并解释 loss、梯度、优化器和过拟合 | | | M2：NLP 与 Transformer 基础 | 第 5-8 周 | [ ] 未开始 [ ] 进行中 [ ] 完成 | 0% | 实现一个 mini decoder-only Transformer 或完成逐行阅读笔记 | | | M3：LLM 推理、Prompt 与工具调用 | 第 9-10 周 | [ ] 未开始 [ ] 进行中 [ ] 完成 | 0% | 建立一套 prompt 测试集，能稳定输出结构化结果 | | | M4：RAG 与评估体系 | 第 11-14 周 | [ ] 未开始 [ ] 进行中 [ ] 完成 | 0% | 做出一个带 retrieval/generation eval 的知识库问答系统 | | | M5：SFT、PEFT 与数据工程 | 第 15-19 周 | [ ] 未开始 [ ] 进行中 [ ] 完成 | 0% | 使用 LoRA/QLoRA 完成一次领域微调并写实验报告 | | | M6：偏好优化与后训练 | 第 20-23 周 | [ ] 未开始 [ ] 进行中 [ ] 完成 | 0% | 完成 DPO 或 GRPO toy experiment，说明偏好数据如何影响输出 | | | M7：推理服务与性能优化 | 第 24-27 周 | [ ] 未开始 [ ] 进行中 [ ] 完成 | 0% | 部署 OpenAI-compatible LLM 服务并完成吞吐、延迟、成本 benchmark | | | M8：作品集与面试闭环 | 持续进行 | [ ] 未开始 [ ] 进行中 [ ] 完成 | 0% | 形成 3-5 个可讲清楚 trade-off 的项目和文章 | |

M0：定位与环境基线

这个阶段的目标不是一开始就训练大模型，而是先建立可复现实验环境。只要环境和记录方式不稳定，后面的训练、评估和复盘都会变得很混乱。

需要掌握

Python 环境管理：uv、conda 或 venv 任选其一，但要能固定依赖。
基础工具：Git、Linux shell、Jupyter、VS Code、CUDA/MPS 基本排障。
LLM 基础库：torch、transformers、datasets、accelerate、peft、trl。
推理入口：本地小模型、云端 API、OpenAI-compatible server 至少跑通一种。

验收清单

[ ] 创建一个专门的 llm-learning 仓库。
[ ] 固定 Python 版本和依赖文件。
[ ] 跑通一个 tokenizer 示例，解释 token、context window、special tokens。
[ ] 跑通一个小模型生成示例，记录输入、输出、耗时、显存或内存占用。
[ ] 写一篇环境搭建和踩坑记录。

目录规划

llm-learning/
├── README.md
├── env/
├── notebooks/
├── experiments/
├── evals/
└── notes/

M1：Python、数学与 PyTorch 基础

这一阶段不追求“知道很多模型名字”，而是把训练过程拆开看清楚。以后遇到 loss 不降、显存溢出、数据泄漏、过拟合这些问题时，需要能自己定位，而不是只换框架或换模型。

需要掌握

Python 数据处理：迭代器、类型标注、日志、配置、单元测试。
数学基础：线性代数、概率统计、信息论、微积分中与梯度相关的部分。
机器学习基础：训练/验证/测试拆分，偏差方差，正则化，交叉熵，指标选择。
PyTorch 基础：Tensor、autograd、nn.Module、optimizer、scheduler、DataLoader、混合精度。

验收清单

[ ] 用 PyTorch 写一个完整训练循环，不依赖高级 trainer。
[ ] 画出训练集和验证集 loss 曲线，并解释是否过拟合。
[ ] 实现 early stopping、checkpoint、resume training。
[ ] 对同一模型至少做 3 次学习率或 batch size 对比实验。
[ ] 写一份“训练异常排查清单”：loss 不降、梯度爆炸、显存溢出、数据泄漏。

练习安排

用 sklearn 或 PyTorch 训练一个文本分类 baseline。
用纯 PyTorch 复现一个小型语言模型训练循环。
把实验配置、随机种子、指标和模型文件统一记录下来。

M2：NLP 与 Transformer 基础

Transformer 是 LLM 的核心抽象。这个阶段不希望只停留在“Self-Attention 很重要”，而是要能解释每个张量形状如何变化，以及训练和生成阶段的差异。

需要掌握

NLP 基础：分词、词向量、语言模型、序列标注、文本分类、问答。
Tokenization：BPE、WordPiece、Unigram、chat template、特殊 token。
Transformer：embedding、positional encoding、multi-head attention、FFN、LayerNorm、residual。
Decoder-only LLM：causal mask、next-token prediction、KV cache、generation decoding。
生成策略：greedy、beam search、temperature、top-k、top-p、repetition penalty。

验收清单

[ ] 画出 decoder-only Transformer 的数据流。
[ ] 手写 scaled dot-product attention，并验证输入输出 shape。
[ ] 解释 causal mask 为什么训练时并行、生成时自回归。
[ ] 实现一个 mini Transformer language model，哪怕只在小语料上训练。
[ ] 阅读并整理 Transformer、RAG、LoRA、DPO 相关论文笔记。

阅读顺序

先读课程讲义或教程，建立概念图。
再读论文摘要、方法图和实验设置。
最后复现最小可运行版本，不一开始追求完整训练规模。

M3：LLM 推理、Prompt 与工具调用

这个阶段会把 Prompt 当成可测试的工程接口，而不是凭感觉写提示词。要学会把任务定义、上下文、约束、输出格式和评估标准说清楚。

需要掌握

Chat message 结构：system、user、assistant、tool。
输出控制：JSON schema、结构化输出、函数调用、错误重试。
Prompt 设计：任务说明、少样本示例、反例、边界条件、引用上下文。
推理参数：temperature、top-p、max tokens、stop、seed。
评估方式：黄金集、人工评分、LLM-as-judge、规则断言、回归测试。

验收清单

[ ] 为一个真实任务建立 30-100 条测试输入。
[ ] 为输出定义可机器检查的 schema。
[ ] 比较至少 3 版 prompt，并记录准确率、稳定性和失败样例。
[ ] 加入工具调用或函数调用，处理调用失败和空结果。
[ ] 写出“什么时候该 prompt，什么时候该 RAG，什么时候该微调”的判断规则。

判断规则

| 问题类型 | 我会优先选择 | 原因 | |------|------|------| | 输出格式不稳定 | 结构化输出 / 函数调用 | 我先约束接口，不急着训练 | | 缺少私有知识 | RAG | 知识可更新，成本低于微调 | | 固定风格或固定流程 | Prompt + eval | 快速迭代，容易回归测试 | | 领域术语和输出习惯长期稳定 | SFT / LoRA | 让模型学习模式，而不是每次塞长 prompt | | 人类偏好难以用规则描述 | DPO / RLHF / GRPO | 用偏好数据优化排序或行为 |

M4：RAG 与评估体系

RAG 是最想先做出闭环的方向。它的难点不是“把文档放进向量库”，而是让检索、重排、生成和评估能互相校验。没有评估的 RAG 很容易变成“看起来能答，实际上不可控”的系统。

需要掌握

文档处理：解析、清洗、切块、去重、metadata、版本管理。
向量检索：embedding、相似度、召回率、top-k、hybrid search。
重排：cross encoder reranker、规则 rerank、业务字段加权。
生成：上下文压缩、引用来源、拒答策略、答案格式控制。
评估：retrieval recall、faithfulness、answer correctness、latency、成本。

验收清单

[ ] 选一个知识库，例如 Obsidian、项目文档或部署文档。
[ ] 构造至少 50 条问题，标注答案来源文档。
[ ] 分别评估 chunk size、top-k、embedding model、reranker 对结果的影响。
[ ] 输出每次回答引用的来源片段。
[ ] 建立失败样例分类：没召回、召回错、上下文冲突、模型幻觉、格式错误。

项目设想

先做一个“Obsidian 知识库问答”项目：

读取 Markdown 文档，保留标题层级和路径 metadata。
将内容切块并写入 FAISS、Milvus 或 pgvector。
对每个问题返回答案、引用段落和置信度。
使用固定评估集比较不同切块和检索策略。
把失败样例写回笔记，形成下一轮优化任务。

M5：SFT、PEFT 与数据工程

进入微调阶段后，要提醒自己：微调的核心不是把训练命令跑起来，而是理解数据为什么能改变模型行为。多数微调失败不是算法失败，而是数据定义、格式、分布和评估出了问题。

需要掌握

数据格式：instruction、input、output、conversation、chat template。
数据质量：去重、清洗、长度分布、标签一致性、泄漏检查。
SFT：teacher forcing、loss mask、packing、learning rate、warmup、checkpoint。
PEFT：LoRA、QLoRA、rank、alpha、target modules、merge。
实验诊断：训练 loss、验证 loss、样例输出、灾难性遗忘、过拟合。

验收清单

[ ] 构造一个 500-5000 条的领域指令数据集。
[ ] 写数据检查脚本，统计长度、空值、重复、异常标签。
[ ] 使用 LoRA/QLoRA 完成一次 SFT。
[ ] 设计 baseline：原始模型、prompt-only、SFT 模型对比。
[ ] 写实验报告，包含配置、指标、样例、失败分析和下一步计划。

实验报告模板

| 项目 | 我要记录的内容 | |------|------| | 目标 | 这次微调希望改善什么行为 | | 数据 | 数据来源、规模、格式、清洗规则 | | 模型 | base model、上下文长度、tokenizer | | 训练 | batch size、learning rate、epoch、LoRA 参数 | | 评估 | 自动指标、人工评分、失败样例 | | 结论 | 是否值得继续扩大数据或训练规模 |

M6：偏好优化与后训练

这个阶段会学习如何让模型更符合偏好，而不是简单学会答案。它通常用于改善风格、安全性、帮助性、拒答边界、推理过程或多候选答案排序。

需要掌握

偏好数据：chosen/rejected、pairwise ranking、rubric、标注一致性。
Reward modeling：奖励模型目标、过优化风险、reward hacking。
DPO：直接用偏好对优化策略模型，工程上比完整 RLHF 更容易入门。
GRPO/RLHF：理解 policy、reward、advantage、KL 约束、采样成本。
安全与边界：拒答、敏感问题、越权工具调用、幻觉控制。

验收清单

[ ] 从一个任务中采集至少 200 组 chosen/rejected 样例。
[ ] 定义偏好标注规则，并记录难判样例。
[ ] 跑通 DPO 或 GRPO 的最小实验。
[ ] 比较 SFT 模型与偏好优化模型的输出差异。
[ ] 写出偏好优化带来的收益、代价和风险。

需要注意

偏好优化不适合拿来修复所有问题。如果模型缺少知识，优先做 RAG；如果输出格式不稳定，优先做结构化输出；如果领域任务样例不足，优先补 SFT 数据；只有当“多个可行答案之间的偏好”本身很重要时，再考虑 DPO、RLHF 或 GRPO。

M7：推理服务与性能优化

模型效果只是上线的一半。真实业务还会关心吞吐、首 token 延迟、总延迟、显存、并发、成本、稳定性和降级策略。这个阶段要从“模型能跑”推进到“服务可用”。

需要掌握

推理引擎：vLLM、SGLang、TGI、llama.cpp 的定位和差异。
性能概念：prefill、decode、KV cache、continuous batching、tensor parallel。
压缩优化：量化、蒸馏、speculative decoding、上下文压缩。
服务接口：OpenAI-compatible API、鉴权、限流、超时、重试。
可观测性：请求日志、trace、token 用量、延迟分位数、错误分类。

验收清单

[ ] 使用 vLLM 或同类引擎部署一个 OpenAI-compatible endpoint。
[ ] 对不同并发、输入长度、输出长度做 benchmark。
[ ] 记录 TTFT、TPOT、吞吐、显存占用和错误率。
[ ] 设计限流、超时、fallback 和日志脱敏策略。
[ ] 写一份“模型上线前检查清单”。

Benchmark 记录表

| 模型 | 引擎 | 并发 | 输入 tokens | 输出 tokens | TTFT | 总延迟 P50/P95 | 吞吐 tokens/s | 显存 | 备注 | |------|------|------|------|------|------|------|------|------|------| | | | | | | | | | | |

M8：作品集与面试闭环

作品集不需要堆很多 demo。希望每个项目都能讲清楚“问题、方案、指标、失败、取舍”。如果一个项目只能演示，不能解释取舍，它对长期成长的帮助就有限。

作品集规划

| 项目 | 我想展示的能力 | 最低验收标准 | |------|------|------| | mini Transformer 复现 | 模型基础 | 能解释 attention、mask、loss 和生成过程 | | RAG 知识库问答 | 应用算法 | 有评估集、引用、失败分类和优化记录 | | 领域 LoRA 微调 | 后训练入门 | 有数据报告、baseline 对比和误差分析 | | 偏好优化实验 | 对齐理解 | 有 chosen/rejected 数据和 DPO/GRPO 对比 | | vLLM 推理服务 | 工程交付 | 有 benchmark、限流、日志和部署说明 |

需要能回答的问题

Transformer 中 Q/K/V 的作用是什么？为什么需要 multi-head？
causal mask 解决什么问题？训练和生成阶段有什么不同？
RAG 中 chunk size、top-k、reranker 如何影响召回和幻觉？
什么场景该用 prompt，什么场景该用 RAG，什么场景才需要微调？
LoRA 的 rank、alpha、target modules 分别影响什么？
SFT 后效果变差，会如何排查数据、训练和评估问题？
DPO 和 RLHF 的核心区别是什么？
vLLM 为什么能提升吞吐？KV cache 对显存有什么影响？
如何设计一个 LLM 应用的离线评估和线上监控？

每周学习节奏

把每周学习固定成四类动作，避免只输入不输出。

| 动作 | 时间占比 | 执行要求 | |------|------|------| | 学概念 | 25% | 课程、文档、论文，目标是建立概念图 | | 写代码 | 35% | 每周至少一个可运行实验 | | 做评估 | 25% | 用固定数据集比较不同方案 | | 写复盘 | 15% | 记录失败样例、指标变化和下一步 |

进度日志模板

后续更新学习进度时，直接复制这个模板追加到本节下面。

### YYYY-MM-DD

- Milestone：
- 本周完成：
- 关键证据：
- 指标变化：
- 主要卡点：
- 下周计划：

2026-05-20

Milestone：M0
本周完成：创建 LLM 算法工程师学习路线和 milestone 进度看板。
关键证据：本文档。
指标变化：暂无。
主要卡点：还需要确认每周可投入时间，并尽快搭建第一个学习仓库。
下周计划：搭建 llm-learning 仓库，跑通 tokenizer 和小模型推理基线。

学习资料路径

下面这些资料按“先官方教程，再论文，再工程文档”的顺序使用。

| 类别 | 资料 | 使用方式 | |------|------|------| | 课程 | Stanford CS224N | 用来补 NLP、Transformer、LLM 评估和 Agent/RAG 基础 | | 官方教程 | Hugging Face Transformers 文档 | 学 tokenizer、模型加载、Trainer、生成和微调 | | 后训练 | Hugging Face TRL 文档 | 学 SFT、DPO、GRPO、Reward Modeling 等后训练方法 | | 深度学习工程 | PyTorch Tutorials | 学训练循环、Transformer、分布式训练和性能优化 | | Prompt/API | OpenAI Prompt Engineering Guide | 学指令、上下文、输出格式和 prompt 评估 | | 评估 | OpenAI Evals Guide | 学如何系统化构建模型输出评估 | | RAG 评估 | Ragas Evaluation | 学 RAG 自动评估的指标和接口 | | 推理服务 | vLLM Online Serving | 学 OpenAI-compatible serving、并发和部署参数 | | 论文 | Attention Is All You Need | Transformer 原始论文 | | 论文 | Retrieval-Augmented Generation | RAG 经典论文 | | 论文 | LoRA | PEFT 经典论文 | | 论文 | Direct Preference Optimization | DPO 经典论文 |

总结

技术栈总结

| 组件 | 版本 | 我会用它做什么 | |------|------|------| | Python | 3.11 / 3.12 | 固定项目运行环境 | | PyTorch | 当前稳定版 | 深度学习训练和推理基础 | | Transformers | 当前稳定版 | 模型、tokenizer、Trainer 和生成接口 | | Datasets / Accelerate | 当前稳定版 | 数据集处理和训练加速 | | PEFT / TRL | 当前稳定版 | LoRA、SFT、DPO、GRPO 等微调与后训练 | | FAISS / Milvus / pgvector | 任选 | RAG 向量检索 | | Ragas / 自建 eval | 任选 | RAG 和 LLM 应用评估 | | vLLM | 当前稳定版 | 高吞吐 LLM 推理服务 | | LangSmith / OpenTelemetry / 自建日志 | 任选 | trace、评估和线上观测 |

核心步骤回顾

建立可复现实验环境，不急着训练大模型。
补齐 PyTorch、NLP 和 Transformer 基础。
用 Prompt、RAG 和 eval 做出可交付应用。
用 SFT、LoRA 和偏好优化提升模型行为。
用 vLLM、benchmark 和可观测性完成工程闭环。

下一步优化

[ ] 确认主攻方向：应用算法、微调后训练、推理部署或研究评测。
[ ] 创建 llm-learning 仓库并补充环境说明。
[ ] 建立第一版评估集。
[ ] 用 Obsidian 文档做一个 RAG baseline。
[ ] 每周更新一次 milestone 进度看板和进度日志。

更新时间: 2026-05-20
阅读时间: 18 分钟
适用场景: LLM 算法工程师学习规划、转岗准备、学习进度管理、作品集建设

Obsidian 完全指南：从入门到精通

Mon, 18 May 2026 00:00:00 GMT

Obsidian 完全指南：从入门到精通

摘要：Obsidian 是一款基于本地 Markdown 文件的强大笔记应用，通过双向链接、图谱视图和丰富的插件生态，帮助用户构建个人知识体系。本文将详细介绍 Obsidian 的核心功能、高级用法、高效插件以及如何将其融入实际工作流。

什么是 Obsidian

Obsidian 是一款以本地 Markdown 文件为基础的双向链接笔记应用，由 Shida Li 和 Erica Xu 于 2020 年推出。它的核心理念是：

数据本地化：所有笔记都是本地 Markdown 文件，完全掌控你的数据
双向链接：通过 [[链接]] 语法建立笔记间的关联，形成知识网络
可插拔架构：丰富的社区插件生态系统，按需扩展功能
跨平台同步：支持 Windows、macOS、Linux、iOS 和 Android

为什么选择 Obsidian

| 特性 | Obsidian | Notion | Roam Research | |------|----------|--------|---------------| | 数据存储 | 本地 Markdown | 云端 | 云端 | | 离线可用 | ✅ | ❌ | ❌ | | 双向链接 | ✅ | ✅ | ✅ | | 插件生态 | 🌟🌟🌟🌟🌟 | 🌟🌟🌟 | 🌟🌟 | | 启动速度 | ⚡ 极快 | 🐢 较慢 | 🐢 较慢 | | 自定义程度 | 极高 | 中等 | 中等 | | 价格 | 免费 | 收费 | 收费 |

核心功能详解

1. 双向链接 (Backlinks)

双向链接是 Obsidian 的核心功能，让你轻松建立笔记间的关联。

基本语法：

这是普通文本，链接到 [[另一篇笔记]] 的内容。

自动创建链接：[[新笔记]]（如果不存在会自动创建）

高级用法：

# 显示不同文本
[[目标笔记 | 自定义显示文本]]

# 链接到特定锚点
[[目标笔记#锚点]]

# 嵌入笔记内容
![[嵌入的笔记]]

# 嵌入特定块
![[笔记#^block-id]]

2. 图谱视图 (Graph View)

图谱视图可视化展示笔记间的连接关系，帮助你发现知识间的隐藏联系。

使用技巧：

拖拽节点重新布局
点击节点高亮相关连接
使用过滤器按标签、文件夹筛选
调整连接距离和节点大小

3. 反向链接面板

右侧面板显示所有链接到当前笔记的内容，分为：

反向链接：直接链接到当前笔记
未链接的提及：提到但未建立链接的内容
双向链接：当前笔记链接到的内容

4. 模板系统

通过模板快速创建标准化笔记结构。

基础模板示例：

---
title: "{{title}}"
date: {{date}}
tags: []
---

# {{title}}

## 概述

## 详细内容

## 参考
-

5. 标签系统

标签用于跨文件夹组织内容：

tags: [开发，教程，#工具/obsidian]

# 层级标签
#工作/项目/博客
#学习/编程/python

高级用法与技巧

1. 属性 (Frontmatter)

每篇笔记顶部可以添加 YAML frontmatter，用于元数据管理：

---
title: "文章标题"
date: 2025-05-18
updated: 2025-05-20
status: draft
tags: [obsidian, 教程]
aliases: [别名 1, 别名 2]
icon: 📝
cover: "path/to/image.jpg"
---

2. 转义字符与特殊语法

# 转义链接
\[\[这不是链接\]\]

# 数学公式
行内公式：$E = mc^2$
块级公式：
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

# 任务列表
- [x] 已完成任务
- [ ] 待办任务
- [ ] 子任务
  - [ ] 子子任务

# 折叠内容
> [!collapse] 点击展开
> 这里是折叠的内容

3. 代码块高亮

```python hl_lines="3 5"
def hello():
    name = "Obsidian"
    if name:
        print(f"Hello, {name}!")
    return True

4. 调用笔记 (Transclusion)

将笔记内容嵌入到其他笔记中：

# 嵌入整篇笔记
![[相关笔记]]

# 嵌入特定部分（需要 Dataview）
```dataview
TABLE WITHOUT ID
  field1 as "字段 1",
  field2 as "字段 2"
FROM "文件夹"
WHERE status = "active"

5. 块引用与块 ID

为段落添加唯一 ID，实现精确引用：

这是一个重要概念^#concept-001

在另一篇笔记中引用：![[当前笔记#^concept-001]]

必备高效插件

核心插件（内置）

1. Templates（模板）

快速插入预设模板，标准化笔记结构。

配置建议：

模板文件夹：/Templates
日期格式：YYYY-MM-DD
时间格式：HH:mm

2. Daily Notes（每日笔记）

自动创建每日日志，记录日常思考和任务。

模板示例：

# 📅 {{date}}

## 🎯 今日目标
- 

## 📝 工作记录

## 💡 想法与灵感

## ✅ 完成事项

3. Advanced Tables（高级表格）

提供类似 Excel 的表格编辑体验，支持快捷键操作。

4. Command Palette（命令面板）

Ctrl/Cmd + P 快速访问所有功能。

社区插件推荐

1. Dataview ⭐⭐⭐⭐⭐

功能：查询和展示笔记数据，将 Obsidian 变成数据库。

使用示例：

LIST FROM "博客" 
WHERE status = "published" 
SORT file.ctime DESC

TABLE date as "日期", tags as "标签"
FROM "日记"
WHERE contains(tags, "重要")
GROUP BY month(date)

2. Kanban ⭐⭐⭐⭐⭐

功能：创建看板，管理项目和任务。

示例：

列标题 1
- [ ] 任务 1
- [x] 任务 2

列标题 2
- [ ] 任务 3

3. Calendar ⭐⭐⭐⭐

功能：可视化日历视图，快速访问每日笔记。

4. Outline ⭐⭐⭐⭐

功能：显示当前文档的目录结构，快速导航。

5. Word Count ⭐⭐⭐⭐

功能：统计字数、字符数、阅读时间。

6. Slides ⭐⭐⭐⭐

功能：将笔记转换为幻灯片演示。

---
slide: true
---

# 第一页

---

# 第二页

7. Excalidraw ⭐⭐⭐⭐⭐

功能：在笔记中绘制手绘风格的图表和思维导图。

8. Linter ⭐⭐⭐⭐

功能：自动格式化笔记，统一风格。

配置示例：

{
  "rule-1-heading-bullet": true,
  "rule-2-space-after-list-markers": true,
  "rule-11-footnote-after-punctuation": true
}

9. Auto Note Mover ⭐⭐⭐⭐

功能：根据规则自动移动笔记到对应文件夹。

10. Hot Reload ⭐⭐⭐⭐

功能：修改 CSS 和插件后自动刷新，无需重启。

11. QuickAdd ⭐⭐⭐⭐⭐

功能：快速添加内容到指定位置，支持宏和脚本。

示例宏：

创建新笔记
插入模板
添加标签
打开笔记

12. Tasks ⭐⭐⭐⭐⭐

功能：强大的任务管理，支持跨笔记查询任务。

```tasks
NOT DONE
PATH 包含 "工作"
GROUP BY heading

13. Admonition（已内置为 Callouts）

功能：创建可折叠的提示框。

> [!INFO] 信息
> 这是信息提示框

> [!TIP] 提示
> 这是提示信息

> [!WARNING] 警告
> 这是警告信息

> [!QUOTE] 引用
> 这是引用内容

与工作流结合

1. 博客工作流

Obsidian → Astro 博客

# 目录结构
Vault/
├── blog/          # 博客文章
├── Templates/        # 模板
├── Assets/          # 资源文件
└── sync-and-commit.sh  # 同步脚本

同步脚本示例：

#!/bin/bash
# 同步 Obsidian 博客到 GitHub

OBSIDIAN_PATH="/path/to/blog"
REPO_PATH="/path/to/blog-repo/content"

# 复制文件
cp -r "$OBSIDIAN_PATH"/* "$REPO_PATH/"

# 提交更改
cd "$REPO_PATH"
git add .
git commit -m "更新博客文章 $(date +%Y-%m-%d)"
git push

2. 项目管理工作流

使用 Kanban + Dataview 管理项目：

项目看板

待办
- [[任务 1]] 📅 2025-05-20
- [[任务 2]]

进行中
- [[任务 3]] 👤 Edward

已完成
- [[任务 4]] ✅

项目统计

TASK FROM "项目"
GROUP BY status

3. 学习工作流

Zettelkasten（卡片盒）方法：

Fleeting Notes：快速记录想法
Literature Notes：整理参考资料
Permanent Notes：形成永久知识卡片

文件夹结构：

00-Inbox/          # 临时笔记
10-Areas/          # 长期关注领域
20-Projects/       # 正在进行的项目
30-Resources/      # 参考资料
40-Archives/       # 归档内容
99-Templates/      # 模板

4. 会议记录工作流

会议模板：

---
title: "{{meeting_name}}"
date: {{date}}
attendees: []
project: []
---

# 📋 {{meeting_name}}

> 📅 {{date}} | 👥 {{attendees}}

## 🎯 目标

## 📝 讨论要点

## ✅ 行动项
- [ ] @责任人 任务描述 📅 截止日期

## 📎 参考资料
-

最佳实践

1. 命名规范

使用有意义的文件名
避免特殊字符
保持一致的命名风格
示例：YYYY-MM-DD-会议主题.md

2. 标签策略

使用层级标签：#类别/子类别
控制标签数量（建议<50 个）
定期清理无用标签
使用 Dataview 查询标签

3. 链接策略

链接概念而非关键词
使用描述性链接文本
定期整理孤立笔记
利用反向链接发现关联

4. 备份与同步

推荐方案：

官方同步：Obsidian Sync（付费，最方便）
Git 同步：适合开发者，版本控制
云盘同步：iCloud、Dropbox、OneDrive
第三方工具：Remotely Save、Syncthing

5. 性能优化

控制库大小（建议<10,000 笔记）
定期归档旧笔记
使用资源文件夹管理媒体
禁用不用的插件

总结

Obsidian 不仅仅是一个笔记应用，它是一个知识管理系统，帮助你：

建立知识网络：通过双向链接连接想法
提升工作效率：模板、快捷键、插件自动化
长期知识积累：本地存储，永久可用
个性化定制：CSS、插件、主题无限可能

学习路线建议

第一周：掌握基本操作、双向链接、模板
第一月：学习 Dataview、配置常用插件
第三月：建立自己的工作流，探索高级功能
持续：关注社区插件，优化个人系统

参考资源

最后更新：2025-05-18

Ansible 自动化运维完整指南

Thu, 14 May 2026 00:00:00 GMT

Ansible 自动化运维完整指南

本文将全面介绍 Ansible 自动化运维工具，从基础概念到高级应用，帮助你构建高效、可维护的基础设施自动化体系。

为什么选择 Ansible？

配置管理工具对比

| 工具 | 架构 | Agent | 学习曲线 | 适用场景 | |------|------|-------|----------|----------| | Ansible | Push | 无需 | 低 | 快速部署、简单运维 | | Puppet | Pull | 需要 | 高 | 大型复杂环境 | | Chef | Pull | 需要 | 高 | 企业级配置管理 | | SaltStack | Push/Pull | 可选 | 中 | 高性能需求 |

Ansible 的核心优势

无代理架构 — 通过 SSH 连接，无需安装 Agent
简单易学 — YAML 语法，直观易懂
幂等性 — 多次执行结果一致
丰富模块 — 3000+ 内置模块
社区活跃 — 大量社区角色和插件
双向通信 — 支持 ad-hoc 命令和 Playbook

核心概念

1. 控制节点 (Control Node)

运行 Ansible 的机器，可以是任何 Linux/Mac 系统。

# 安装 Ansible
sudo apt update
sudo apt install ansible

# 验证安装
ansible --version

2. 管理主机 (Managed Nodes)

被 Ansible 管理的目标服务器。

要求：

安装 OpenSSH Server
与控制节点网络可达
支持 SSH 密钥认证（推荐）

3. 库存 (Inventory)

定义被管理主机的配置文件。

静态库存示例：

# /etc/ansible/hosts 或 inventory.ini

[webservers]
web1 ansible_host=192.168.1.10 ansible_user=ubuntu
web2 ansible_host=192.168.1.11 ansible_user=ubuntu

[dbservers]
db1 ansible_host=192.168.1.20 ansible_user=root
db2 ansible_host=192.168.1.21 ansible_user=root

[loadbalancers]
lb1 ansible_host=192.168.1.5 ansible_user=admin

# 组合组
[web:children]
webservers
loadbalancers

# 变量定义
[webservers:vars]
http_port=80
max_clients=200

# 所有服务器
[all:vars]
ansible_ssh_common_args='-o StrictHostKeyChecking=no'

动态库存示例（JSON 格式）：

{
  "webservers": {
    "hosts": ["web1.example.com", "web2.example.com"],
    "vars": {
      "http_port": 80
    }
  },
  "dbservers": {
    "hosts": ["db1.example.com", "db2.example.com"],
    "vars": {
      "db_port": 3306
    }
  }
}

4. 模块 (Modules)

Ansible 的基本执行单元，完成特定任务。

常用模块：

| 模块 | 用途 | 示例 | |------|------|------| | command | 执行命令 | command: /usr/bin/uptime | | shell | Shell 命令 | shell: ls -la \| grep log | | copy | 复制文件 | copy: src=/local/file dest=/remote/file | | template | 模板渲染 | template: src=config.j2 dest=/etc/app.conf | | yum/apt | 包管理 | yum: name=nginx state=present | | service | 服务管理 | service: name=nginx state=started | | user | 用户管理 | user: name=app useradd=yes | | file | 文件管理 | file: path=/var/log/app state=directory | | git | Git 操作 | git: repo=URL dest=/app version=main | | debug | 调试输出 | debug: msg="Hello" |

5. Playbook

YAML 格式的任务清单，定义自动化流程。

---
- name: 配置 Web 服务器
  hosts: webservers
  become: yes  # 使用 sudo
  vars:
    nginx_version: "1.24"
    
  tasks:
    - name: 安装 Nginx
      apt:
        name: nginx
        state: present
        update_cache: yes
    
    - name: 启动 Nginx 服务
      service:
        name: nginx
        state: started
        enabled: yes
    
    - name: 复制配置文件
      template:
        src: nginx.conf.j2
        dest: /etc/nginx/nginx.conf
      notify: 重启 Nginx
      
  handlers:
    - name: 重启 Nginx
      service:
        name: nginx
        state: restarted

快速开始

1. 配置 SSH 免密登录

# 生成 SSH 密钥（如果没有）
ssh-keygen -t ed25519 -C "ansible@control"

# 复制公钥到目标主机
ssh-copy-id ubuntu@192.168.1.10
ssh-copy-id ubuntu@192.168.1.11

# 测试连接
ssh ubuntu@192.168.1.10

2. 创建库存文件

# 创建目录结构
mkdir -p ~/ansible/{inventory,playbooks,roles,templates}

# 创建 inventory.ini
cat > ~/ansible/inventory.ini << 'EOF'
[webservers]
web1 ansible_host=192.168.1.10 ansible_user=ubuntu
web2 ansible_host=192.168.1.11 ansible_user=ubuntu

[webservers:vars]
ansible_python_interpreter=/usr/bin/python3
EOF

3. 测试连接

# Ping 所有主机
ansible all -i inventory.ini -m ping

# 输出示例：
# web1 | SUCCESS => { "ping": "pong" }
# web2 | SUCCESS => { "ping": "pong" }

4. 执行 Ad-hoc 命令

# 检查系统信息
ansible all -i inventory.ini -m setup -a 'filter=ansible_facts'

# 执行命令
ansible webservers -i inventory.ini -m command -a 'uptime'

# 安装软件包
ansible all -i inventory.ini -m apt -a 'name=htop state=present'

# 复制文件
ansible webservers -i inventory.ini -m copy -a 'src=/local/file.txt dest=/tmp/file.txt'

# 管理服务
ansible all -i inventory.ini -m service -a 'name=nginx state=restarted'

Playbook 深入

1. 基本结构

---
- name: Play 名称
  hosts: 目标主机组
  become: true  # 是否提权
  become_method: sudo  # 提权方式
  vars_files:
    - vars/main.yml  # 外部变量文件
  vars:
    var1: value1  # 内联变量
  environment:  # 环境变量
    KEY1: value1
  connection: ssh  # 连接方式
  serial: 10%  # 分批执行
  max_fail_percentage: 10  # 最大失败百分比
  
  pre_tasks:  # 前置任务
    - name: 前置任务
      debug:
        msg: "准备开始"
  
  roles:  # 应用角色
    - common
    - nginx
    
  tasks:  # 任务列表
    - name: 任务名称
      module: 参数
      
  post_tasks:  # 后置任务
    - name: 后置任务
      debug:
        msg: "完成"
  
  handlers:  # 处理器
    - name: 处理器名称
      service:
        name: nginx
        state: restarted

2. 变量管理

变量优先级（低到高）：

角色默认变量 (defaults/main.yml)
角色变量 (vars/main.yml)
Playbook 变量 (vars:)
库存变量 (group_vars/, host_vars/)
额外变量 (-e 参数)

变量文件示例：

# group_vars/webservers.yml
http_port: 80
max_clients: 200
nginx_worker_processes: auto
nginx_worker_connections: 1024

# host_vars/web1.yml
http_port: 8080
custom_domain: "web1.example.com"

# vars/app_config.yml
app_name: "myapp"
app_version: "1.0.0"
app_port: 3000

在 Playbook 中使用：

- name: 使用变量
  debug:
    msg: "应用 {{ app_name }} 版本 {{ app_version }}"

3. 条件执行

- name: 条件安装
  apt:
    name: "{{ item }}"
    state: present
  loop:
    - nginx
    - mysql-server
  when: install_nginx | bool

- name: 检查操作系统
  debug:
    msg: "这是 Ubuntu 系统"
  when: ansible_os_family == "Debian"

- name: 检查变量存在
  debug:
    msg: "变量已定义"
  when: my_var is defined

- name: 复杂条件
  debug:
    msg: "生产环境且需要 SSL"
  when: environment == "production" and ssl_enabled | bool

4. 循环处理

- name: 安装多个软件包
  apt:
    name: "{{ item }}"
    state: present
  loop:
    - nginx
    - mysql-server
    - php

- name: 创建多个用户
  user:
    name: "{{ item.name }}"
    groups: "{{ item.groups }}"
    shell: /bin/bash
  loop:
    - { name: 'user1', groups: 'developers' }
    - { name: 'user2', groups: 'admins' }

- name: 从文件读取列表
  debug:
    msg: "{{ item }}"
  loop: "{{ lookup('file', 'packages.txt').split('\n') }}"

- name: 嵌套循环
  debug:
    msg: "{{ item.key }} = {{ item.value }}"
  loop: "{{ my_dict | dict2items }}"

5. 错误处理

- name: 可能失败的任务
  command: /usr/bin/risky-command
  ignore_errors: yes  # 忽略错误继续执行

- name: 带重试的任务
  command: /usr/bin/flaky-command
  retries: 5
  delay: 10
  until: last_rc == 0

- name: 失败时执行
  block:
    - name: 任务 1
      command: /usr/bin/task1
    - name: 任务 2
      command: /usr/bin/task2
  rescue:
    - name: 错误处理
      debug:
        msg: "任务失败，执行恢复操作"
  always:
    - name: 始终执行
      debug:
        msg: "无论成功失败都执行"

6. 模板渲染 (Jinja2)

模板文件示例 (nginx.conf.j2)：

user www-data;
worker_processes {{ nginx_worker_processes | default('auto') }};
pid /run/nginx.pid;

events {
    worker_connections {{ nginx_worker_connections | default(1024) }};
}

http {
    sendfile on;
    tcp_nopush on;
    types_hash_max_size 2048;

    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    {% for server in virtual_hosts %}
    server {
        listen {{ server.port | default(80) }};
        server_name {{ server.domain }};
        root {{ server.root | default('/var/www/html') }};
        
        {% if server.ssl_enabled | default(false) %}
        ssl on;
        ssl_certificate {{ server.ssl_cert }};
        ssl_key {{ server.ssl_key }};
        {% endif %}
        
        location / {
            try_files $uri $uri/ =404;
        }
    }
    {% endfor %}
}

Playbook 中使用：

- name: 渲染配置文件
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
    owner: root
    group: root
    mode: '0644'
    backup: yes  # 备份原文件
    validate: 'nginx -t -c %s'  # 验证语法
  notify: 重启 Nginx

角色 (Roles)

1. 角色结构

roles/
└── nginx/
    ├── defaults/
    │   └── main.yml          # 默认变量（优先级最低）
    ├── vars/
    │   └── main.yml          # 角色变量
    ├── files/                # 静态文件
    │   └── custom.conf
    ├── templates/            # Jinja2 模板
    │   └── nginx.conf.j2
    ├── handlers/
    │   └── main.yml          # 处理器
    ├── tasks/
    │   ├── main.yml          # 主任务
    │   ├── install.yml       # 安装任务
    │   └── configure.yml     # 配置任务
    ├── meta/
    │   └── main.yml          # 元数据（依赖等）
    └── README.md

2. 创建角色

# 使用 ansible-galaxy 创建角色结构
ansible-galaxy init nginx

# 或手动创建
mkdir -p roles/nginx/{tasks,handlers,templates,files,vars,defaults}

3. 角色内容示例

defaults/main.yml：

---
nginx_version: "1.24"
nginx_state: present
nginx_enabled: true
nginx_listen_port: 80
nginx_worker_processes: "auto"
nginx_worker_connections: 1024

tasks/main.yml：

---
- name: 包含安装任务
  include_tasks: install.yml

- name: 包含配置任务
  include_tasks: configure.yml

- name: 确保 Nginx 运行
  service:
    name: nginx
    state: "{{ 'started' if nginx_enabled else 'stopped' }}"
    enabled: "{{ nginx_enabled | bool }}"
  notify: 重启 Nginx

tasks/install.yml：

---
- name: 安装 Nginx (Debian)
  apt:
    name: "nginx={{ nginx_version }}"
    state: "{{ nginx_state }}"
    update_cache: yes
  when: ansible_os_family == "Debian"

- name: 安装 Nginx (RHEL)
  yum:
    name: "nginx-{{ nginx_version }}"
    state: "{{ nginx_state }}"
  when: ansible_os_family == "RedHat"

handlers/main.yml：

---
- name: 重启 Nginx
  service:
    name: nginx
    state: restarted

- name: 重载 Nginx
  service:
    name: nginx
    state: reloaded

meta/main.yml：

---
dependencies:
  - role: common
    tags: ['common']
  
  - role:
    name: firewall
    when: enable_firewall | default(false)

4. 使用角色

---
- name: 部署 Web 服务器
  hosts: webservers
  become: yes
  
  roles:
    - role: common
      tags: ['common']
      
    - role: nginx
      nginx_listen_port: 8080  # 覆盖默认变量
      tags: ['web']
      
    - role: monitoring
      when: enable_monitoring | default(false)

高级特性

1. 自定义模块

Python 模块示例 (modules/custom_facts.py)：

#!/usr/bin/env python
ANSIBLE_METADATA = {
    'metadata_version': '1.1',
    'status': ['preview'],
    'supported_by': 'community'
}

DOCUMENTATION = '''
---
module: custom_facts
short_description: 收集自定义系统信息
version_added: "1.0"
options:
    check_disk:
        description: 是否检查磁盘空间
        required: false
        type: bool
        default: true
'''

EXAMPLES = '''
- name: 收集自定义 facts
  custom_facts:
    check_disk: yes
'''

RETURN = '''
ansible_facts:
    description: 返回自定义 facts
    type: dict
'''

from ansible.module_utils.basic import AnsibleModule

def main():
    module = AnsibleModule(
        argument_spec=dict(
            check_disk=dict(type='bool', default=True)
        )
    )
    
    facts = {}
    
    if module.params['check_disk']:
        import os
        disk_usage = os.statvfs('/')
        total = disk_usage.f_frsize * disk_usage.f_blocks
        free = disk_usage.f_frsize * disk_usage.f_bfree
        facts['disk_total'] = total
        facts['disk_free'] = free
        facts['disk_percent_used'] = ((total - free) / total) * 100
    
    module.exit_json(changed=False, ansible_facts=facts)

if __name__ == '__main__':
    main()

使用自定义模块：

- name: 收集自定义 facts
  custom_facts:
    check_disk: yes
    
- name: 显示磁盘使用率
  debug:
    msg: "磁盘使用率：{{ disk_percent_used | round(2) }}%"
  when: disk_percent_used > 80

2. 自定义插件

Filter 插件示例 (filter_plugins/custom_filters.py)：

def to_bytes(size_mb):
    """将 MB 转换为字节"""
    return size_mb * 1024 * 1024

def truncate_middle(text, length=50):
    """截断文本中间部分"""
    if len(text) <= length:
        return text
    half = length // 2
    return text[:half] + "..." + text[-half:]

class FilterModule(object):
    def filters(self):
        return {
            'to_bytes': to_bytes,
            'truncate_middle': truncate_middle
        }

使用自定义过滤器：

- name: 使用自定义过滤器
  debug:
    msg: "{{ 100 | to_bytes }}"
    
- name: 截断长文本
  debug:
    msg: "{{ long_text | truncate_middle(30) }}"

3. 动态库存

AWS EC2 动态库存脚本示例：

#!/usr/bin/env python3
import boto3
import json
import sys

def get_inventory():
    ec2 = boto3.client('ec2', region_name='us-east-1')
    
    response = ec2.describe_instances(
        Filters=[
            {'Name': 'tag:Environment', 'Values': ['Production']}
        ]
    )
    
    inventory = {
        'webservers': {'hosts': [], 'vars': {}},
        'dbservers': {'hosts': [], 'vars': {}},
        '_meta': {'hostvars': {}}
    }
    
    for reservation in response['Reservations']:
        for instance in reservation['Instances']:
            if instance['State']['Name'] != 'running':
                continue
                
            hostname = instance['Tags'][0]['Value']
            ip = instance['PrivateIpAddress']
            instance_type = instance['InstanceType']
            
            # 根据标签分组
            for tag in instance.get('Tags', []):
                if tag['Key'] == 'Role':
                    if tag['Value'] in inventory:
                        inventory[tag['Value']]['hosts'].append(hostname)
                        inventory['_meta']['hostvars'][hostname] = {
                            'ansible_host': ip,
                            'ansible_user': 'ubuntu',
                            'instance_type': instance_type
                        }
    
    return inventory

if __name__ == '__main__':
    if sys.argv[1] == '--list':
        print(json.dumps(get_inventory()))
    elif sys.argv[1] == '--host':
        print(json.dumps({}))

4. 异步任务和轮询

- name: 执行长时间任务
  async: 3600  # 最多运行 1 小时
  poll: 0      # 不等待，立即返回
  command: /usr/bin/long-running-script.sh
  register: async_result

- name: 检查任务状态
  async_status:
    jid: "{{ async_result.ansible_job_id }}"
  register: job_status
  until: job_status.finished
  retries: 30
  delay: 10

- name: 显示结果
  debug:
    msg: "{{ job_status.results }}"
  when: job_status.finished

5. 策略 (Strategies)

- name: 使用不同策略
  hosts: all
  strategy: linear  # 默认，同步执行
  
  # 其他策略选项:
  # - free: 主机独立执行，不等待
  # - host_pinned: 类似 free，但保持主机顺序
  
  tasks:
    - name: 任务 1
      debug:
        msg: "任务 1"
    
    - name: 任务 2
      debug:
        msg: "任务 2"

6. 滚动更新

- name: 滚动更新 Web 服务
  hosts: webservers
  serial: 1  # 每次只更新一台
  
  tasks:
    - name: 从负载均衡移除
      uri:
        url: "http://lb-api/remove/{{ inventory_hostname }}"
        method: POST
      delegate_to: localhost
      
    - name: 停止服务
      service:
        name: myapp
        state: stopped
        
    - name: 部署新版本
      git:
        repo: https://github.com/app/repo.git
        dest: /opt/myapp
        version: "{{ app_version }}"
        
    - name: 启动服务
      service:
        name: myapp
        state: started
        
    - name: 健康检查
      uri:
        url: "http://localhost:8080/health"
        status_code: 200
      register: health_result
      retries: 5
      delay: 10
      until: health_result.status == 200
      
    - name: 添加回负载均衡
      uri:
        url: "http://lb-api/add/{{ inventory_hostname }}"
        method: POST
      delegate_to: localhost
      when: health_result.status == 200

最佳实践

1. 项目结构

ansible-project/
├── inventory/
│   ├── production/
│   │   ├── hosts
│   │   ├── group_vars/
│   │   │   ├── all.yml
│   │   │   └── webservers.yml
│   │   └── host_vars/
│   └── staging/
├── group_vars/
│   ├── all.yml
│   └── webservers.yml
├── host_vars/
├── playbooks/
│   ├── site.yml          # 主 Playbook
│   ├── webserver.yml
│   ├── database.yml
│   └── backup.yml
├── roles/
│   ├── common/
│   ├── nginx/
│   ├── mysql/
│   └── monitoring/
├── templates/            # 全局模板
├── files/                # 全局文件
├── scripts/              # 辅助脚本
├── ansible.cfg           # 配置文件
├── requirements.yml      # 角色依赖
└── README.md

2. Ansible 配置

ansible.cfg：

[defaults]
inventory = ./inventory/production/hosts
remote_user = ubuntu
host_key_checking = False
retry_files_enabled = False
gathering = smart
fact_caching = jsonfile
fact_caching_connection = /tmp/ansible_facts
fact_caching_timeout = 86400
roles_path = ./roles
library = ./library
filter_plugins = ./filter_plugins
stdout_callback = yaml
callback_whitelist = profile_tasks, timer

[privilege_escalation]
become = True
become_method = sudo
become_user = root
become_ask_pass = False

[ssh_connection]
pipelining = True
control_path = /tmp/ansible-ssh-%%h-%%p-%%r
ssh_args = -o ControlMaster=auto -o ControlPersist=60s

3. 变量管理最佳实践

# group_vars/all.yml - 全局变量
ansible_python_interpreter: /usr/bin/python3
timezone: Asia/Shanghai
ntp_server: ntp.example.com

# group_vars/webservers.yml - 组变量
http_port: 80
max_clients: 200

# host_vars/web1.yml - 主机变量
custom_domain: web1.example.com

# vars/secrets.yml - 敏感信息（需加密）
db_password: "{{ vault_db_password }}"
api_key: "{{ vault_api_key }}"

4. 安全实践

使用 Ansible Vault：

# 创建加密文件
ansible-vault create group_vars/secrets.yml

# 编辑加密文件
ansible-vault edit group_vars/secrets.yml

# 查看加密文件
ansible-vault view group_vars/secrets.yml

# 加密普通文件
ansible-vault encrypt secrets.yml

# 解密文件
ansible-vault decrypt secrets.yml

# 运行 Playbook（输入密码）
ansible-playbook -i inventory site.yml --ask-vault-pass

# 使用密码文件
ansible-playbook -i inventory site.yml --vault-password-file=~/.vault_pass

Playbook 中使用 Vault：

- name: 使用加密变量
  hosts: all
  vars_files:
    - group_vars/secrets.yml
    
  tasks:
    - name: 创建数据库用户
      mysql_user:
        name: app_user
        password: "{{ vault_db_password }}"  # 加密变量
        host: '%'
        priv: '{{ db_name }}.*:ALL'

5. 错误处理和日志

- name: 带完整错误处理的任务
  block:
    - name: 执行关键任务
      command: /usr/bin/critical-task
      register: result
      
    - name: 验证结果
      assert:
        that:
          - result.rc == 0
          - "success" in result.stdout
        fail_msg: "任务执行失败"
        success_msg: "任务成功完成"
        
  rescue:
    - name: 记录错误
      debug:
        msg: "任务失败：{{ result.stderr }}"
        
    - name: 发送告警
      uri:
        url: "{{ alert_webhook_url }}"
        method: POST
        body: "任务失败：{{ inventory_hostname }}"
        status_code: 200
        
    - name: 回滚操作
      command: /usr/bin/rollback-script
      
  always:
    - name: 记录执行日志
      lineinfile:
        path: /var/log/ansible-execution.log
        line: "{{ ansible_date_time.iso8601 }} - {{ inventory_hostname }} - {{ result.rc if result is defined else 'N/A' }}"

6. 性能优化

# 启用 SSH 管道和连接复用
[ssh_connection]
pipelining = True
control_path = /tmp/ansible-ssh-%%h-%%p-%%r

# 使用 serial 分批执行
- name: 分批部署
  hosts: all
  serial:
    - 10%
    - 25%
    - 100%
    
# 使用 max_fail_percentage 控制失败容忍度
- name: 容错部署
  hosts: all
  max_fail_percentage: 10
  
# 使用 tags 选择性执行
ansible-playbook site.yml --tags "nginx,mysql"

# 使用 limit 限制主机
ansible-playbook site.yml --limit "web1,web2"

实战案例

案例 1：部署 LAMP 栈

---
- name: 部署 LAMP 栈
  hosts: webservers
  become: yes
  
  roles:
    - common
    - { role: mysql, tags: ['database'] }
    - { role: php, tags: ['php'] }
    - { role: nginx, tags: ['web'] }
    
  tasks:
    - name: 创建应用目录
      file:
        path: /var/www/myapp
        state: directory
        owner: www-data
        group: www-data
        mode: '0755'
        
    - name: 部署应用代码
      git:
        repo: https://github.com/myapp/repo.git
        dest: /var/www/myapp
        version: main
        
    - name: 配置虚拟主机
      template:
        src: nginx-vhost.conf.j2
        dest: "/etc/nginx/sites-available/{{ app_name }}"
      notify: 重载 Nginx
      
    - name: 启用虚拟主机
      file:
        src: "/etc/nginx/sites-available/{{ app_name }}"
        dest: "/etc/nginx/sites-enabled/{{ app_name }}"
        state: link
      notify: 重载 Nginx
      
  handlers:
    - name: 重载 Nginx
      service:
        name: nginx
        state: reloaded

案例 2：Docker 环境部署

---
- name: 部署 Docker 环境
  hosts: docker_hosts
  become: yes
  
  tasks:
    - name: 安装依赖包
      apt:
        name:
          - apt-transport-https
          - ca-certificates
          - curl
          - software-properties-common
        state: present
        update_cache: yes
        
    - name: 添加 Docker GPG 密钥
      apt_key:
        url: https://download.docker.com/linux/ubuntu/gpg
        state: present
        
    - name: 添加 Docker 仓库
      apt_repository:
        repo: "deb [arch=amd64] https://download.docker.com/linux/ubuntu {{ ansible_distribution_release }} stable"
        state: present
        
    - name: 安装 Docker
      apt:
        name: docker-ce
        state: present
        update_cache: yes
        
    - name: 启动 Docker 服务
      service:
        name: docker
        state: started
        enabled: yes
        
    - name: 安装 Docker Compose
      get_url:
        url: "https://github.com/docker/compose/releases/download/{{ docker_compose_version }}/docker-compose-Linux-x86_64"
        dest: /usr/local/bin/docker-compose
        mode: '0755'
        
    - name: 添加用户到 docker 组
      user:
        name: "{{ ansible_user_id }}"
        groups: docker
        append: yes

Ansible 与 Kubernetes 集成

1. 使用 Ansible 部署 K8s 集群

Ansible 是部署 Kubernetes 集群的经典工具，比 kubeadm 更灵活，适合复杂环境。

使用 kubeadm 部署 K8s：

---
- name: 使用 kubeadm 部署 Kubernetes 集群
  hosts: all
  become: yes
  gather_facts: yes
  
  vars:
    k8s_version: "1.28"
    pod_network_cidr: "10.244.0.0/16"
    service_network_cidr: "10.96.0.0/12"
    
  pre_tasks:
    - name: 禁用 Swap
      command: swapoff -a
      changed_when: yes
      
    - name: 永久禁用 Swap
      lineinfile:
        path: /etc/fstab
        regexp: '^.*swap.*'
        state: absent
        
    - name: 加载内核模块
      modprobe:
        name: "{{ item }}"
        state: present
      loop:
        - overlay
        - br_netfilter
        
    - name: 配置 sysctl 参数
      sysctl:
        name: "{{ item.key }}"
        value: "{{ item.value }}"
        state: present
        reload: yes
      loop:
        - { key: 'net.bridge.bridge-nf-call-iptables', value: '1' }
        - { key: 'net.bridge.bridge-nf-call-ip6tables', value: '1' }
        - { key: 'net.ipv4.ip_forward', value: '1' }
        
  tasks:
    - name: 安装 containerd
      block:
        - name: 安装 containerd 依赖
          apt:
            name:
              - containerd.io
              - runc
            state: present
            update_cache: yes
            
        - name: 配置 containerd
          copy:
            content: |
              [plugins."io.containerd.grpc.v1.cri"]
                [plugins."io.containerd.grpc.v1.cri".containerd]
                  default_runtime_name = "runc"
                  [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
                    runtime_type = "io.containerd.runc.v2"
                    [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]
                      SystemdCgroup = true
            dest: /etc/containerd/config.toml
            
        - name: 重启 containerd
          service:
            name: containerd
            state: restarted
            enabled: yes
            
      rescue:
        - name: 记录 containerd 安装失败
          debug:
            msg: "containerd 安装失败，请检查系统兼容性"
            
    - name: 安装 Kubernetes 组件
      apt:
        name: 
          - "kubeadm={{ k8s_version }}.*"
          - "kubelet={{ k8s_version }}.*"
          - "kubectl={{ k8s_version }}.*"
        state: present
        update_cache: yes
        
    - name: 锁定 kubelet 版本
      command: apt-mark hold kubelet
      args:
        creates: /var/lib/kubelet-held
        
  post_tasks:
    - name: 验证 kubelet 版本
      command: kubelet version
      register: kubelet_version
      changed_when: no
      
    - name: 显示 kubelet 版本
      debug:
        msg: "{{ kubelet_version.stdout_lines }}"

初始化 Control Plane：

---
- name: 初始化 Kubernetes Control Plane
  hosts: control_plane
  become: yes
  
  vars:
    k8s_version: "1.28"
    apiserver_address: "{{ hostvars['k8s-master-01']['ansible_default_ipv4']['address'] }}"
    pod_network_cidr: "10.244.0.0/16"
    
  tasks:
    - name: 初始化集群
      command: >
        kubeadm init
        --apiserver-advertise-address={{ apiserver_address }}
        --pod-network-cidr={{ pod_network_cidr }}
        --cri-socket=unix:///var/run/containerd/containerd.sock
        --ignore-preflight-errors=Swap
      register: kubeadm_init
      changed_when: "'initialized successfully' in kubeadm_init.stdout"
      
    - name: 创建 .kube 目录
      file:
        path: "{{ ansible_user_dir }}/.kube"
        state: directory
        mode: '0700'
        
    - name: 复制 kubeconfig
      copy:
        src: /etc/kubernetes/admin.conf
        dest: "{{ ansible_user_dir }}/.kube/config"
        remote_src: yes
        mode: '0600'
        
    - name: 保存 join 命令
      template:
        src: kubeadm-join-command.sh.j2
        dest: /tmp/kubeadm-join-worker.sh
        mode: '0755'
      when: kubeadm_init is changed
      
    - name: 显示 join 命令
      debug:
        msg: "请运行以下命令将 worker 节点加入集群:\n{{ kubeadm_init.stdout | regex_search('kubeadm join.*') }}"

加入 Worker 节点：

---
- name: 将 Worker 节点加入集群
  hosts: workers
  become: yes
  
  tasks:
    - name: 从 master 获取 join 命令
      fetch:
        src: /tmp/kubeadm-join-worker.sh
        dest: /tmp/kubeadm-join-worker.sh
        flat: yes
      delegate_to: k8s-master-01
      run_once: yes
      
    - name: 复制 join 脚本到 worker
      copy:
        src: /tmp/kubeadm-join-worker.sh
        dest: /tmp/kubeadm-join-worker.sh
        mode: '0755'
        
    - name: 执行 join 命令
      command: /tmp/kubeadm-join-worker.sh
      async: 300
      poll: 10
      register: join_result
      
    - name: 验证节点加入
      command: kubectl get nodes -o json
      delegate_to: k8s-master-01
      run_once: yes
      register: nodes_status
      retries: 5
      delay: 30
      until: nodes_status.stdout | contains(inventory_hostname)
      
    - name: 显示节点状态
      debug:
        msg: "{{ inventory_hostname }} 已成功加入集群"
      when: nodes_status.stdout is defined and inventory_hostname in nodes_status.stdout

2. 安装 CNI 网络插件

---
- name: 安装 Calico 网络插件
  hosts: control_plane
  become: yes
  vars:
    calico_version: "v3.26.1"
    
  tasks:
    - name: 下载 Calico 配置
      get_url:
        url: "https://raw.githubusercontent.com/projectcalico/calico/{{ calico_version }}/manifests/tigera-operator.yaml"
        dest: /tmp/tigera-operator.yaml
        
    - name: 应用 Calico 配置
      command: kubectl apply -f /tmp/tigera-operator.yaml
      register: calico_result
      changed_when: calico_result.rc == 0
      
    - name: 等待 Calico 就绪
      command: kubectl get pods -n kube-system -l k8s-app=calico-node -o jsonpath='{.items[*].status.phase}'
      register: calico_status
      retries: 30
      delay: 10
      until: '"Running"' in calico_status.stdout
      
    - name: 显示 Calico 状态
      debug:
        msg: "Calico 网络插件已就绪"

3. 使用 k8s 模块管理资源

Ansible 提供了丰富的 Kubernetes 模块，可以直接管理 K8s 资源。

安装 kubernetes-python：

- name: 安装 Python Kubernetes 库
  pip:
    name:
      - kubernetes
      - openshift
    state: present
  delegate_to: localhost

管理 Deployment：

---
- name: 部署应用
  hosts: control_plane
  become: no
  
  tasks:
    - name: 创建命名空间
      k8s:
        state: present
        definition:
          apiVersion: v1
          kind: Namespace
          metadata:
            name: myapp
            
    - name: 部署应用
      k8s:
        state: present
        definition:
          apiVersion: apps/v1
          kind: Deployment
          metadata:
            name: myapp
            namespace: myapp
            labels:
              app: myapp
          spec:
            replicas: 3
            selector:
              matchLabels:
                app: myapp
            template:
              metadata:
                labels:
                  app: myapp
              spec:
                containers:
                  - name: myapp
                    image: nginx:{{ nginx_version | default('1.24') }}
                    ports:
                      - containerPort: 80
                    resources:
                      requests:
                        memory: "64Mi"
                        cpu: "250m"
                      limits:
                        memory: "128Mi"
                        cpu: "500m"
                    livenessProbe:
                      httpGet:
                        path: /
                        port: 80
                      initialDelaySeconds: 30
                      periodSeconds: 10
                    readinessProbe:
                      httpGet:
                        path: /
                        port: 80
                      initialDelaySeconds: 5
                      periodSeconds: 5
                        
    - name: 创建 Service
      k8s:
        state: present
        definition:
          apiVersion: v1
          kind: Service
          metadata:
            name: myapp-service
            namespace: myapp
          spec:
            selector:
              app: myapp
            ports:
              - port: 80
                targetPort: 80
                protocol: TCP
            type: ClusterIP
            
    - name: 验证部署
      k8s_info:
        api_version: v1
        kind: Pod
        namespace: myapp
        label_selectors:
          - app=myapp
      register: pods
      
    - name: 显示 Pod 状态
      debug:
        msg: "部署了 {{ pods.resources | length }} 个 Pod"

滚动更新：

---
- name: 滚动更新应用
  hosts: control_plane
  
  vars:
    app_name: myapp
    namespace: myapp
    new_version: "1.25"
    
  tasks:
    - name: 更新 Deployment 镜像
      k8s:
        state: patched
        definition:
          apiVersion: apps/v1
          kind: Deployment
          metadata:
            name: "{{ app_name }}"
            namespace: "{{ namespace }}"
          spec:
            template:
              spec:
                containers:
                  - name: "{{ app_name }}"
                    image: nginx:{{ new_version }}
        merge_type: strategic
        
    - name: 等待滚动更新完成
      k8s_info:
        api_version: apps/v1
        kind: Deployment
        namespace: "{{ namespace }}"
        name: "{{ app_name }}"
      register: deployment
      retries: 60
      delay: 10
      until: 
        - deployment.resources[0].status.readyReplicas == deployment.resources[0].spec.replicas
        
    - name: 显示更新状态
      debug:
        msg: |
          更新完成!
          期望副本数：{{ deployment.resources[0].spec.replicas }}
          就绪副本数：{{ deployment.resources[0].status.readyReplicas }}
          可用副本数：{{ deployment.resources[0].status.availableReplicas }}

管理 ConfigMap 和 Secret：

---
- name: 管理配置和密钥
  hosts: control_plane
  
  tasks:
    - name: 创建 ConfigMap
      k8s:
        state: present
        definition:
          apiVersion: v1
          kind: ConfigMap
          metadata:
            name: app-config
            namespace: myapp
          data:
            APP_ENV: production
            LOG_LEVEL: info
            MAX_CONNECTIONS: "100"
            
    - name: 从文件创建 ConfigMap
      k8s:
        state: present
        definition:
          apiVersion: v1
          kind: ConfigMap
          metadata:
            name: app-config-files
            namespace: myapp
          data:
            app.conf: "{{ lookup('file', 'files/app.conf') }}"
            nginx.conf: "{{ lookup('template', 'templates/nginx.conf.j2') }}"
            
    - name: 创建 Secret
      k8s:
        state: present
        definition:
          apiVersion: v1
          kind: Secret
          metadata:
            name: app-secret
            namespace: myapp
          type: Opaque
          stringData:
            DB_PASSWORD: "{{ vault_db_password }}"
            API_KEY: "{{ vault_api_key }}"

4. Helm 集成

使用 Ansible 管理 Helm Charts。

安装 Helm：

---
- name: 安装 Helm
  hosts: control_plane
  
  tasks:
    - name: 下载 Helm
      get_url:
        url: "https://get.helm.sh/helm-v{{ helm_version | default('3.12.0') }}-linux-amd64.tar.gz"
        dest: /tmp/helm.tar.gz
        
    - name: 解压 Helm
      unarchive:
        src: /tmp/helm.tar.gz
        dest: /tmp
        remote_src: yes
        
    - name: 安装 Helm
      copy:
        src: /tmp/linux-amd64/helm
        dest: /usr/local/bin/helm
        mode: '0755'
        
    - name: 验证 Helm 安装
      command: helm version --short
      register: helm_version_output
      changed_when: no

使用 Helm 部署应用：

---
- name: 使用 Helm 部署应用
  hosts: control_plane
  
  vars:
    releases:
      - name: prometheus
        chart: prometheus
        repo: https://prometheus-community.github.io/helm-charts
        namespace: monitoring
        version: "25.18.0"
        values:
          server:
            persistentVolume:
              enabled: false
          alertmanager:
            persistentVolume:
              enabled: false
              
      - name: grafana
        chart: grafana
        repo: https://grafana.github.io/helm-charts
        namespace: monitoring
        version: "7.0.0"
        values:
          adminPassword: "{{ vault_grafana_password }}"
          persistence:
            enabled: false
            size: 10Gi
            
  tasks:
    - name: 创建命名空间
      k8s:
        state: present
        definition:
          apiVersion: v1
          kind: Namespace
          metadata:
            name: "{{ item.namespace }}"
      loop: "{{ releases }}"
      loop_control:
        label: "{{ item.namespace }}"
        
    - name: 添加 Helm 仓库
      command: >
        helm repo add {{ item.name }}
        {{ item.repo }}
        --force-update
      loop: "{{ releases }}"
      loop_control:
        label: "添加仓库 {{ item.name }}"
      register: helm_repo_add
      changed_when: "'has been added' in helm_repo_add.stdout"
      
    - name: 部署 Helm Chart
      helm:
        name: "{{ item.name }}"
        chart_name: "{{ item.chart }}"
        release_namespace: "{{ item.namespace }}"
        repo_url: "{{ item.repo }}"
        version: "{{ item.version }}"
        values: "{{ item.values }}"
        state: present
      loop: "{{ releases }}"
      loop_control:
        label: "部署 {{ item.name }}"
        
    - name: 验证部署
      command: helm list -n {{ item.namespace }}
      loop: "{{ releases }}"
      register: helm_list
      changed_when: no
      
    - name: 显示部署状态
      debug:
        msg: "{{ item.name }} 部署成功"
      loop: "{{ releases }}"

Helm 升级和回滚：

---
- name: Helm 升级和回滚管理
  hosts: control_plane
  
  vars:
    release_name: prometheus
    namespace: monitoring
    new_version: "25.19.0"
    
  tasks:
    - name: 升级 Helm Release
      helm:
        name: "{{ release_name }}"
        chart_name: prometheus
        release_namespace: "{{ namespace }}"
        repo_url: https://prometheus-community.github.io/helm-charts
        version: "{{ new_version }}"
        state: present
        update_deps: yes
        wait: yes
        timeout: 300
      register: helm_upgrade
      
    - name: 显示升级历史
      command: helm history {{ release_name }} -n {{ namespace }}
      register: helm_history
      changed_when: no
      
    - name: 回滚到上一版本（如果升级失败）
      helm:
        name: "{{ release_name }}"
        release_namespace: "{{ namespace }}"
        state: present
        revision: "{{ helm_history.stdout_lines[-2].split()[0] }}"
      when: helm_upgrade.failed | default(false)

5. Ingress 管理

---
- name: 配置 Ingress
  hosts: control_plane
  
  vars:
    ingress_host: "myapp.example.com"
    tls_enabled: true
    tls_secret: "myapp-tls"
    
  tasks:
    - name: 安装 Nginx Ingress Controller
      helm:
        name: nginx-ingress
        chart_name: ingress-nginx
        repo_url: https://kubernetes.github.io/ingress-nginx
        release_namespace: ingress-nginx
        create_namespace: yes
        values:
          controller:
            service:
              type: LoadBalancer
        state: present
        
    - name: 等待 Ingress Controller 就绪
      k8s_info:
        api_version: v1
        kind: Pod
        namespace: ingress-nginx
        label_selectors:
          - app.kubernetes.io/component=controller
      register: ingress_pods
      retries: 30
      delay: 10
      until: 
        - ingress_pods.resources | length > 0
        - ingress_pods.resources[0].status.phase == 'Running'
        
    - name: 创建 Ingress
      k8s:
        state: present
        definition:
          apiVersion: networking.k8s.io/v1
          kind: Ingress
          metadata:
            name: myapp-ingress
            namespace: myapp
            annotations:
              nginx.ingress.kubernetes.io/rewrite-target: /
              nginx.ingress.kubernetes.io/ssl-redirect: "{{ 'true' if tls_enabled else 'false' }}"
          spec:
            {% if tls_enabled %}
            tls:
              - hosts:
                  - "{{ ingress_host }}"
                secretName: "{{ tls_secret }}"
            {% endif %}
            rules:
              - host: "{{ ingress_host }}"
                http:
                  paths:
                    - path: /
                      pathType: Prefix
                      backend:
                        service:
                          name: myapp-service
                          port:
                            number: 80

6. 完整 K8s 运维 Playbook

---
- name: 完整的 Kubernetes 应用部署和运维
  hosts: control_plane
  become: no
  
  vars_prompt:
    - name: environment
      prompt: "选择环境 (dev/staging/production)"
      private: no
      
  vars_files:
    - vars/k8s_config.yml
    - vars/secrets.yml
    
  tasks:
    # 1. 环境检查
    - name: 检查 kubectl 连接
      command: kubectl cluster-info
      register: cluster_info
      changed_when: no
      
    - name: 显示集群信息
      debug:
        msg: "集群已就绪"
      when: cluster_info.rc == 0
      
    # 2. 准备环境
    - name: 创建命名空间
      k8s:
        state: present
        definition:
          apiVersion: v1
          kind: Namespace
          metadata:
            name: "{{ app_namespace }}"
            labels:
              environment: "{{ environment }}"
              
    # 3. 部署基础设施
    - name: 部署 Prometheus 监控
      include_tasks: tasks/deploy-prometheus.yml
      when: enable_monitoring | default(false) | bool
      
    # 4. 部署应用
    - name: 部署主应用
      k8s:
        state: present
        src: "files/{{ app_name }}-deployment.yaml"
        
    - name: 部署服务
      k8s:
        state: present
        src: "files/{{ app_name }}-service.yaml"
        
    # 5. 配置 Ingress
    - name: 配置入口
      include_tasks: tasks/configure-ingress.yml
      when: environment == 'production'
      
    # 6. 健康检查
    - name: 等待应用就绪
      k8s_info:
        api_version: v1
        kind: Pod
        namespace: "{{ app_namespace }}"
        label_selectors:
          - app={{ app_name }}
      register: app_pods
      retries: 60
      delay: 10
      until: 
        - app_pods.resources | length >= app_replicas | default(1)
        - app_pods.resources[0].status.phase == 'Running'
        
    # 7. 验证部署
    - name: 验证服务访问
      uri:
        url: "http://{{ ingress_host }}/{{ app_name }}/health"
        status_code: 200
      register: health_check
      retries: 10
      delay: 5
      until: health_check.status == 200
      when: environment != 'dev'
      
    # 8. 清理旧版本
    - name: 清理旧版本资源
      k8s:
        state: absent
        definition:
          apiVersion: apps/v1
          kind: Deployment
          metadata:
            name: "{{ app_name }}"
            namespace: "{{ app_namespace }}"
            labels:
              version: "{{ old_version }}"
      when: cleanup_old_versions | default(false) | bool
      
  handlers:
    - name: 发送部署成功通知
      uri:
        url: "{{ webhook_url }}"
        method: POST
        body_format: json
        body:
          text: "✅ 部署成功 - {{ app_name }} ({{ environment }})"
          username: Ansible
          icon_emoji: ":rocket:"
      listen: "部署完成"
      
    - name: 发送部署失败通知
      uri:
        url: "{{ webhook_url }}"
        method: POST
        body_format: json
        body:
          text: "❌ 部署失败 - {{ app_name }} ({{ environment }})"
          username: Ansible
          icon_emoji: ":warning:"
      listen: "部署失败"

7. 使用 Ansible 管理多集群

---
- name: 管理多个 Kubernetes 集群
  hosts: all
  
  vars:
    clusters:
      production:
        kubeconfig: "~/.kube/config-production"
        namespace: production
      staging:
        kubeconfig: "~/.kube/config-staging"
        namespace: staging
      development:
        kubeconfig: "~/.kube/config-dev"
        namespace: development
        
  tasks:
    - name: 遍历所有集群
      block:
        - name: 设置 kubeconfig
          set_fact:
            KUBECONFIG: "{{ item.value.kubeconfig }}"
          
        - name: 检查集群状态
          command: kubectl cluster-info
          environment:
            KUBECONFIG: "{{ item.value.kubeconfig }}"
          register: cluster_status
          changed_when: no
          
        - name: 部署应用到集群
          k8s:
            state: present
            definition:
              apiVersion: apps/v1
              kind: Deployment
              metadata:
                name: myapp
                namespace: "{{ item.value.namespace }}"
              spec:
                replicas: "{{ item.value.replicas | default(1) }}"
                selector:
                  matchLabels:
                    app: myapp
                template:
                  metadata:
                    labels:
                      app: myapp
                  spec:
                    containers:
                      - name: myapp
                        image: myapp:{{ app_version }}
          environment:
            KUBECONFIG: "{{ item.value.kubeconfig }}"
            
      loop: "{{ clusters | dict2items }}"
      loop_control:
        label: "{{ item.key }}"
        
      rescue:
        - name: 记录集群部署失败
          debug:
            msg: "集群 {{ item.key }} 部署失败"

8. K8s 资源监控和告警

---
- name: K8s 资源监控和清理
  hosts: control_plane
  
  tasks:
    - name: 收集资源使用率
      command: kubectl top nodes
      register: node_resources
      changed_when: no
      
    - name: 检查资源使用率
      set_fact:
        high_usage_nodes: >-
          {{ node_resources.stdout 
          | regex_findall('(\S+)\s+\d+\s+(\d+)/\d+') 
          | select('match', '80|90|100') 
          | list }}
          
    - name: 告警：节点资源使用率高
      debug:
        msg: "警告：节点资源使用率超过阈值"
      when: high_usage_nodes | length > 0
      changed_when: no
      
    - name: 清理失败 Pod
      command: >
        kubectl delete pods --field-selector=status.phase=Failed
        -n {{ item }}
      loop:
        - default
        - kube-system
        - monitoring
      ignore_errors: yes
      register: cleanup_result
      
    - name: 清理完成 Pod
      command: >
        kubectl delete pods --field-selector=status.phase=Succeeded
        -n {{ item }}
      loop:
        - batch
        - jobs
      ignore_errors: yes
      
    - name: 显示清理结果
      debug:
        msg: "已清理 {{ cleanup_result | length }} 个命名空间中的异常 Pod"

9. 备份和恢复

---
- name: Kubernetes 资源备份和恢复
  hosts: control_plane
  
  vars:
    backup_dir: "/backup/k8s"
    backup_date: "{{ ansible_date_time.iso8601_basic_short }}"
    
  tasks:
    - name: 创建备份目录
      file:
        path: "{{ backup_dir }}/{{ backup_date }}"
        state: directory
        mode: '0755'
        
    - name: 备份所有命名空间
      command: >
        kubectl get all --all-namespaces -o yaml
        > {{ backup_dir }}/{{ backup_date }}/all-resources.yaml
      register: backup_all
      
    - name: 备份 ConfigMaps 和 Secrets
      command: >
        kubectl get configmaps,secrets --all-namespaces -o yaml
        > {{ backup_dir }}/{{ backup_date }}/configmaps-secrets.yaml
      register: backup_configs
      
    - name: 压缩备份文件
      command: >
        tar -czf {{ backup_dir }}/backup-{{ backup_date }}.tar.gz
        -C {{ backup_dir }} {{ backup_date }}
        
    - name: 清理旧备份（保留 7 天）
      find:
        paths: "{{ backup_dir }}"
        patterns: "*.tar.gz"
        age: "7d"
      register: old_backups
      
    - name: 删除旧备份
      file:
        path: "{{ item.path }}"
        state: absent
      loop: "{{ old_backups.files }}"
      when: old_backups.files | length > 0
      
    - name: 显示备份状态
      debug:
        msg: "备份完成：{{ backup_dir }}/backup-{{ backup_date }}.tar.gz"

调试和排错

1. 调试技巧

# 检查模式（不实际执行）
ansible-playbook site.yml --check

# 差异模式（显示文件变化）
ansible-playbook site.yml --diff

# 提高详细程度
ansible-playbook site.yml -v    # 一般信息
ansible-playbook site.yml -vv   # 更多细节
ansible-playbook site.yml -vvv  # 详细输出
ansible-playbook site.yml -vvvv # 调试级别

# 在特定任务后中断
ansible-playbook site.yml --step

# 执行到特定标签
ansible-playbook site.yml --start-at-task="任务名称"

2. 常用调试任务

- name: 调试变量
  debug:
    var: my_variable
    
- name: 显示主机 facts
  setup: {}
  register: facts
  
- name: 显示 facts
  debug:
    var: facts.ansible_facts.ansible_distribution

- name: 失败并显示消息
  fail:
    msg: "调试中断点：{{ some_variable }}"
    
- name: 等待用户输入
  pause:
    prompt: "按回车继续..."

3. 性能分析

# 启用性能回调插件
[defaults]
stdout_callback = profile_tasks
callback_whitelist = profile_tasks

# 运行 Playbook 查看每个任务耗时
ansible-playbook site.yml

# 输出示例：
# PLAY RECAP *****************************************************************
# ...
# 
# TASK PROFILE (time in seconds):
# - 安装 Nginx: 12.345
# - 配置 Nginx: 2.123
# - 启动服务：1.456

总结

核心要点

无代理架构 — 通过 SSH 连接，简化部署
幂等性 — 确保多次执行结果一致
YAML 语法 — 直观易读的 Playbook
角色管理 — 模块化、可复用的代码组织
变量优先级 — 灵活配置管理
错误处理 — block/rescue/always 机制
安全实践 — Ansible Vault 加密敏感信息
K8s 集成 — 原生支持 Kubernetes 资源管理
Helm 管理 — 自动化 Helm Charts 部署和升级
多集群管理 — 统一管理多个 K8s 集群

Ansible + Kubernetes 最佳实践

✅ 使用 k8s 模块直接管理资源，避免 YAML 文件管理
✅ 使用 Helm 管理复杂应用（如 Prometheus、Grafana）
✅ 实现滚动更新和健康检查
✅ 配置 Ingress 和 TLS 自动化
✅ 定期备份 K8s 资源
✅ 监控资源使用率和异常 Pod
✅ 使用多集群管理实现环境隔离

学习路径

✅ 掌握基础概念和 ad-hoc 命令
✅ 编写简单 Playbook
✅ 学习变量、模板、条件执行
✅ 创建和使用角色
✅ 掌握高级特性（异步、滚动更新等）
✅ 学习 K8s 集成 — 部署集群、管理资源
✅ 学习 Helm 集成 — 自动化应用部署
✅ 实践多集群管理 — 生产环境运维

下一步

[ ] 学习 Ansible Galaxy 使用
[ ] 掌握动态库存编写
[ ] 自定义模块和插件开发
[ ] 集成 CI/CD 流水线（GitLab CI + Ansible）
[ ] 学习 Ansible Tower/Automation Controller
[ ] 深入学习 K8s Operator 开发
[ ] 实践 GitOps 工作流（ArgoCD + Ansible）
[ ] 参与开源角色贡献

更新时间: 2026-05-14
阅读时间: 45 分钟
适用场景: 自动化运维、配置管理、批量部署、Kubernetes 运维、基础设施即代码

参考资源

从零搭建 Kubernetes 集群 (ARM64 Linux 离线版)

Thu, 14 May 2026 00:00:00 GMT

从零搭建 Kubernetes 集群 (ARM64 Linux 离线版)

本文将详细介绍如何在无外网访问的 ARM64 架构 Linux 服务器上从零搭建 Kubernetes 集群，包括离线资源准备、本地源配置、节点配置、集群初始化和高可用部署等完整流程。

为什么选择离线部署？

离线部署在内网环境、安全要求高的场景中非常重要：

安全性 — 避免外部网络攻击
合规性 — 满足等保、金融等行业要求
稳定性 — 不受外网波动影响
可控性 — 完全掌控软件版本和来源

环境准备

硬件要求

最小配置：

控制节点 (Control Plane)：2 核 CPU, 4GB RAM, 50GB 磁盘
工作节点 (Worker Node)：2 核 CPU, 4GB RAM, 50GB 磁盘
跳板机/资源机（可选）：4 核 CPU, 8GB RAM, 200GB 磁盘（用于下载离线包）

推荐配置（生产环境）：

控制节点：4 核 CPU, 8GB RAM, 100GB 磁盘
工作节点：4 核 CPU, 16GB RAM, 200GB 磁盘

软件要求

操作系统：Ubuntu 22.04 LTS / Debian 11+ / Rocky Linux 9+ (ARM64)
内核版本：5.15+
Kubernetes 版本：v1.28+
容器运行时：containerd 1.6+

网络规划

节点角色        IP 地址           主机名
─────────────────────────────────────────
Control Plane   192.168.1.100     k8s-master-01
Worker Node 1   192.168.1.101     k8s-worker-01
Worker Node 2   192.168.1.102     k8s-worker-02
跳板机/资源机   192.168.1.200     k8s-jump-host  (可上网)

第一步：离线资源准备（在有网的机器上）

1.1 准备环境

# 在可以上网的机器上执行
mkdir -p /k8s-offline/{packages,images,certs}
cd /k8s-offline

1.2 下载 Kubernetes 组件

# 下载 kubeadm, kubelet, kubectl (ARM64)
VERSION=1.28.0
ARCH=arm64

# 方法 1：从 k8s 官方下载
wget https://pkgs.k8s.io/core:/stable:/v${VERSION}/deb/pool/main/k/kubeadm/kubeadm_${VERSION}-00_arm64.deb
wget https://pkgs.k8s.io/core:/stable:/v${VERSION}/deb/pool/main/k/kubelet/kubelet_${VERSION}-00_arm64.deb
wget https://pkgs.k8s.io/core:/stable:/v${VERSION}/deb/pool/main/k/kubectl/kubectl_${VERSION}-00_arm64.deb

# 方法 2：使用 apt download（推荐）
sudo apt update
sudo apt download kubeadm=${VERSION}-00 kubelet=${VERSION}-00 kubectl=${VERSION}-00

# 下载依赖包
sudo apt download -d --no-install kubeadm=${VERSION}-00 kubelet=${VERSION}-00 kubectl=${VERSION}-00

# 移动到离线目录
sudo cp /var/cache/apt/archives/*.deb ./packages/

1.3 下载容器运行时

# 下载 containerd 及其依赖
sudo apt download -d --no-install containerd.io

# 或者手动下载
wget https://github.com/containerd/containerd/releases/download/v1.6.22/containerd-1.6.22-linux-arm64.tar.gz

# 移动所有 deb 包
sudo cp /var/cache/apt/archives/*.deb ./packages/

1.4 下载 CNI 网络插件

# 下载 Calico YAML 文件（离线部署需要）
wget https://raw.githubusercontent.com/projectcalico/calico/v3.26.1/manifests/tigera-operator.yaml -O calico-operator.yaml
wget https://raw.githubusercontent.com/projectcalico/calico/v3.26.1/manifests/custom-resources.yaml -O calico-config.yaml

# 或者下载 Flannel
wget https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml -O flannel.yaml

# 下载所需镜像（需要预先 pull）
# 注意：这些镜像需要在有 Docker 的环境中 pull
docker pull calico/operator:v1.30.3
docker pull calico/node:v3.26.1
docker pull calico/cni:v3.26.1
docker pull calico/kube-controllers:v3.26.1
docker pull calico/pod2daemon-flexvol:v3.26.1

# 导出镜像
docker save calico/operator:v1.30.3 -o calico-operator.tar
docker save calico/node:v3.26.1 -o calico-node.tar
docker save calico/cni:v3.26.1 -o calico-cni.tar
docker save calico/kube-controllers:v3.26.1 -o calico-kube-controllers.tar
docker save calico/pod2daemon-flexvol:v3.26.1 -o calico-pod2daemon-flexvol.tar

1.5 打包离线资源

# 创建离线安装包
cd /k8s-offline
tar -czvf k8s-offline-packages.tar.gz \
    packages/ \
    calico-operator.yaml \
    calico-config.yaml \
    *.tar

# 传输到离线服务器
# 方法 1：使用 USB 盘
cp k8s-offline-packages.tar.gz /media/usb/

# 方法 2：使用 scp（如果跳板机能访问内网）
scp k8s-offline-packages.tar.gz root@192.168.1.100:/root/

第二步：离线环境配置（在所有节点上）

2.1 系统初始化

# 更新系统（如果有本地源）
sudo apt update && sudo apt upgrade -y

# 安装必要工具（离线）
cd /root/k8s-offline/packages
sudo dpkg -i apt-transport-https*.deb ca-certificates*.deb curl*.deb gnupg*.deb lsb-release*.deb

# 禁用交换分区（Kubernetes 要求）
sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

# 配置主机名和 hosts
sudo hostnamectl set-hostname k8s-master-01  # 根据实际节点修改
echo "192.168.1.100 k8s-master-01" | sudo tee -a /etc/hosts
echo "192.168.1.101 k8s-worker-01" | sudo tee -a /etc/hosts
echo "192.168.1.102 k8s-worker-02" | sudo tee -a /etc/hosts

2.2 配置内核参数

# 加载必要的内核模块
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

sudo modprobe overlay
sudo modprobe br_netfilter

# 设置所需的 sysctl 参数
cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

# 应用配置
sudo sysctl --system

2.3 安装容器运行时（离线）

# 安装 containerd 依赖
cd /root/k8s-offline/packages
sudo dpkg -i libseccomp2*.deb runc*.deb containerd.io*.deb

# 或者使用 tar 包安装
tar -xzf containerd-1.6.22-linux-arm64.tar.gz -C /usr/local
sudo ln -s /usr/local/bin/containerd /usr/local/bin/
sudo ln -s /usr/local/bin/ctr /usr/local/bin/
sudo ln -s /usr/local/bin/containerd-shim-runc-v2 /usr/local/bin/

# 配置 containerd
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml

# 修改 sysctl 配置以支持 overlay
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/g' /etc/containerd/config.toml

# 创建 systemd 服务
cat <<EOF | sudo tee /etc/systemd/system/containerd.service
[Unit]
Description=containerd container runtime
Documentation=https://containerd.io
After=network.target

[Service]
ExecStartPre=-/sbin/modprobe overlay
ExecStart=/usr/local/bin/containerd
Restart=always
RestartSec=5
Delegate=yes
KillMode=process
OOMScoreAdjust=-999
LimitNOFILE=1048576
LimitNPROC=infinity
LimitCORE=infinity

[Install]
WantedBy=multi-user.target
EOF

# 启动 containerd
sudo systemctl daemon-reload
sudo systemctl enable containerd
sudo systemctl restart containerd

2.4 安装 Kubernetes 组件（离线）

# 安装 kubeadm, kubelet, kubectl
cd /root/k8s-offline/packages
sudo dpkg -i kubelet*.deb kubeadm*.deb kubectl*.deb

# 如果有依赖问题，安装所有包
sudo dpkg -i *.deb

# 验证安装
kubeadm version
kubelet version
kubectl version --client

# 锁定版本（防止误升级）
sudo apt-mark hold kubeadm kubelet kubectl

第三步：初始化 Control Plane（离线）

3.1 在控制节点上执行

# 初始化集群（使用本地 CRI socket）
sudo kubeadm init \
    --apiserver-advertise-address=192.168.1.100 \
    --pod-network-cidr=10.244.0.0/16 \
    --cri-socket=unix:///var/run/containerd/containerd.sock \
    --ignore-preflight-errors=Swap,CRI

# 保存 join 命令（后续需要在 worker 节点执行）
# 输出示例：
# kubeadm join 192.168.1.100:6443 --token <token> \
#     --discovery-token-ca-cert-hash sha256:<hash>

3.2 配置 kubectl

# 创建 .kube 目录
mkdir -p $HOME/.kube

# 复制配置文件
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

# 验证集群状态
kubectl get nodes
# 输出：NAME            STATUS     ROLES           AGE   VERSION
#       k8s-master-01   NotReady   control-plane   2m    v1.28.0

3.3 导入 CNI 镜像（离线）

# 导入 Calico 镜像
cd /root/k8s-offline
sudo ctr -n k8s.io images import calico-operator.tar
sudo ctr -n k8s.io images import calico-node.tar
sudo ctr -n k8s.io images import calico-cni.tar
sudo ctr -n k8s.io images import calico-kube-controllers.tar
sudo ctr -n k8s.io images import calico-pod2daemon-flexvol.tar

# 验证镜像
sudo ctr -n k8s.io images ls | grep calico

3.4 安装 CNI 网络插件（离线）

# 应用 Calico 配置（使用本地文件）
kubectl apply -f /root/k8s-offline/calico-operator.yaml
kubectl apply -f /root/k8s-offline/calico-config.yaml

# 或者使用 Flannel
# kubectl apply -f /root/k8s-offline/flannel.yaml

3.5 验证节点状态

# 等待节点就绪（约 2-3 分钟）
watch kubectl get nodes

# 输出：
# NAME            STATUS   ROLES           AGE   VERSION
# k8s-master-01   Ready    control-plane   5m    v1.28.0

第四步：加入 Worker 节点（离线）

4.1 在 Worker 节点上安装组件

# 在所有 worker 节点上执行相同的安装步骤
# 参考第二步：离线环境配置

# 安装 containerd
cd /root/k8s-offline/packages
sudo dpkg -i containerd.io*.deb
sudo systemctl enable containerd
sudo systemctl restart containerd

# 安装 kubernetes 组件
sudo dpkg -i kubelet*.deb kubeadm*.deb kubectl*.deb

4.2 导入必要镜像

# 在 worker 节点上导入 Calico 镜像
cd /root/k8s-offline
sudo ctr -n k8s.io images import calico-node.tar
sudo ctr -n k8s.io images import calico-cni.tar
sudo ctr -n k8s.io images import calico-pod2daemon-flexvol.tar

4.3 加入集群

# 在 k8s-worker-01 和 k8s-worker-02 上分别执行
sudo kubeadm join 192.168.1.100:6443 \
    --token <token> \
    --discovery-token-ca-cert-hash sha256:<hash>

4.4 验证集群

# 在控制节点上查看所有节点
kubectl get nodes -o wide

# 输出：
# NAME            STATUS   ROLES           AGE   VERSION   INTERNAL-IP    OS-IMAGE             KERNEL-VERSION    CONTAINER-RUNTIME
# k8s-master-01   Ready    control-plane   10m   v1.28.0   192.168.1.100 Ubuntu 22.04.3 LTS   5.15.0-91-generic   containerd://1.6.22
# k8s-worker-01   Ready    <none>          5m    v1.28.0   192.168.1.101 Ubuntu 22.04.3 LTS   5.15.0-91-generic   containerd://1.6.22
# k8s-worker-02   Ready    <none>          3m    v1.28.0   192.168.1.102 Ubuntu 22.04.3 LTS   5.15.0-91-generic   containerd://1.6.22

第五步：部署测试应用（离线）

5.1 准备应用镜像

# 在有网的机器上下载 nginx 镜像
docker pull nginx:alpine
docker save nginx:alpine -o nginx-alpine.tar

# 传输到 k8s 集群
scp nginx-alpine.tar root@192.168.1.100:/root/

# 在所有节点上导入镜像
sudo ctr -n k8s.io images import nginx-alpine.tar

5.2 部署 Nginx

# 创建 nginx 部署
kubectl create deployment nginx --image=nginx:alpine --replicas=3

# 创建服务
kubectl expose deployment nginx --type=NodePort --port=80 --target-port=80

# 查看部署状态
kubectl get pods -o wide
kubectl get svc

5.3 验证服务

# 测试服务访问
curl http://192.168.1.100:<NodePort>

# 查看 Pod 日志
kubectl logs -l app=nginx

# 进入 Pod 容器
kubectl exec -it <pod-name> -- /bin/sh

第六步：离线安装常用工具

6.1 安装 Helm（离线）

# 在有网的机器上下载 Helm
wget https://get.helm.sh/helm-v3.12.0-linux-arm64.tar.gz
tar -xzf helm-v3.12.0-linux-arm64.tar.gz
cp linux-arm64/helm /tmp/

# 传输到离线服务器
scp /tmp/helm root@192.168.1.100:/usr/local/bin/

# 在所有节点上安装
sudo chmod +x /usr/local/bin/helm
helm version

6.2 安装 k9s（离线）

# 在有网的机器上下载 k9s
wget https://github.com/derailed/k9s/releases/download/v0.30.9/k9s_Linux_arm64.tar.gz
tar -xzf k9s_Linux_arm64.tar.gz
cp k9s /tmp/

# 传输到离线服务器
scp /tmp/k9s root@192.168.1.100:/usr/local/bin/

# 在所有节点上安装
sudo chmod +x /usr/local/bin/k9s
k9s version

6.3 部署 Portainer（离线）

# 在有网的机器上下载 Portainer 镜像
helm repo add portainer https://portainer.github.io/k8s
helm pull portainer/portainer --version 1.8.0
tar -xzf portainer-1.8.0.tgz

# 导出所需镜像
docker pull portainer/agent:2.19.0
docker pull portainer/kube-state-metrics:2.8.0
docker save portainer/agent:2.19.0 -o portainer-agent.tar
docker save portainer/kube-state-metrics:2.8.0 -o portainer-kube-state-metrics.tar

# 传输到离线环境
scp portainer/ root@192.168.1.100:/root/
scp portainer-*.tar root@192.168.1.100:/root/

# 在离线环境导入镜像并部署
sudo ctr -n k8s.io images import portainer-agent.tar
sudo ctr -n k8s.io images import portainer-kube-state-metrics.tar

kubectl create namespace portainer
cd /root/portainer/portainer
kubectl apply -f templates/

常见问题排查

问题 1: dpkg 依赖错误

# 错误：dpkg: 处理包 xxx 时出错：依赖问题
# 解决：按顺序安装所有依赖包

cd /root/k8s-offline/packages
# 先安装基础依赖
sudo dpkg -i lib*.*.deb
# 再安装运行时
sudo dpkg -i runc*.deb
# 最后安装主包
sudo dpkg -i containerd.io*.deb

# 或者使用 --force-depends（不推荐）
sudo dpkg -i --force-depends package.deb

问题 2: 节点状态为 NotReady

# 查看 kubelet 日志
sudo journalctl -u kubelet -f

# 查看容器状态
sudo crictl ps -a

# 检查 CRI socket
ls -la /var/run/containerd/containerd.sock

# 检查镜像是否导入
sudo ctr -n k8s.io images ls

问题 3: Pod 镜像拉取失败

# 错误：ImagePullBackOff / ErrImagePull
# 原因：离线环境没有镜像

# 解决：确保镜像已导入所有节点
# 在控制节点检查
sudo ctr -n k8s.io images ls

# 在 worker 节点导入
sudo ctr -n k8s.io images import <image>.tar

# 重启 pod
kubectl delete pod <pod-name>

问题 4: CNI 插件失败

# 检查 Calico 状态
kubectl get pods -n kube-system | grep calico

# 查看 Calico 日志
kubectl logs -n kube-system <calico-pod>

# 检查镜像是否导入
sudo ctr -n k8s.io images ls | grep calico

离线镜像管理最佳实践

7.1 镜像清单管理

# 创建镜像清单文件
cat <<EOF > image-list.txt
nginx:alpine
calico/operator:v1.30.3
calico/node:v3.26.1
calico/cni:v3.26.1
calico/kube-controllers:v3.26.1
calico/pod2daemon-flexvol:v3.26.1
EOF

# 批量导出镜像
while read image; do
    docker save "$image" -o "${image//\//_}.tar"
done < image-list.txt

# 批量导入镜像
for img in *.tar; do
    sudo ctr -n k8s.io images import "$img"
done

7.2 本地镜像仓库（可选）

# 在有网的机器上搭建本地 Harbor 或 registry
docker run -d -p 5000:5000 --name registry registry:2

# 重新标记镜像
docker tag nginx:alpine 192.168.1.200:5000/nginx:alpine
docker push 192.168.1.200:5000/nginx:alpine

# 在 k8s 中配置 insecureRegistry
cat <<EOF | sudo tee /etc/containerd/config.toml | grep -A5 hosts
[plugins."io.containerd.grpc.v1.cri".registry]
  [plugins."io.containerd.grpc.v1.cri".registry.configs."192.168.1.200:5000".tls]
    insecure_skip_verify = true
EOF

高可用集群扩展

8.1 添加第二个 Control Plane（离线）

# 在第一个控制节点上获取控制平面 join 命令
sudo kubeadm token create --print-join-command --control-plane

# 在第二个控制节点上执行相同的安装步骤后加入
sudo <join-command>

8.2 部署 HA Proxy（离线）

# 在有网的机器上下载 HA Proxy
sudo apt download -d --no-install haproxy
scp /var/cache/apt/archives/haproxy*.deb root@192.168.1.200:/tmp/

# 在所有控制节点前部署 HA Proxy
cd /tmp
sudo dpkg -i haproxy*.deb

cat <<EOF > /etc/haproxy/haproxy.cfg
global
    log /dev/log local0
    maxconn 256

defaults
    log global
    mode tcp
    option dontlognull
    timeout connect 5000
    timeout client 50000
    timeout server 50000

frontend kubernetes-api
    bind *:6443
    default_backend kubernetes-api-servers

backend kubernetes-api-servers
    balance roundrobin
    server k8s-master-01 192.168.1.100:6443 check
    server k8s-master-02 192.168.1.103:6443 check
EOF

sudo systemctl enable haproxy
sudo systemctl restart haproxy

总结

通过以上步骤，我们成功在完全离线的 ARM64 架构 Linux 服务器上搭建了一个完整的 Kubernetes 集群。

技术栈总结

| 组件 | 版本 | 说明 | 离线方式 | |------|------|------|----------| | 操作系统 | Ubuntu 22.04 LTS | ARM64 架构 | - | | Kubernetes | v1.28.0 | 容器编排平台 | deb 包离线安装 | | 容器运行时 | containerd 1.6.22 | 容器运行时 | tar 包/deb 包 | | 网络插件 | Calico v3.26.1 | CNI 网络 | YAML + 镜像导入 | | 包管理器 | Helm v3.12 | K8s 包管理 | 二进制分发 |

核心步骤回顾

✅ 离线资源准备 — 在有网机器下载所有包和镜像
✅ 传输离线包 — 使用 USB 或跳板机传输
✅ 系统初始化 — 配置内核参数，禁用 Swap
✅ 离线安装运行时 — containerd 离线安装
✅ 离线安装 K8s — deb 包离线安装
✅ 初始化 Control Plane — kubeadm init
✅ 导入 CNI 镜像 — 离线导入 Calico 镜像
✅ 安装网络插件 — 本地 YAML 文件
✅ 加入 Worker 节点 — kubeadm join
✅ 部署测试应用 — 离线镜像导入

离线部署关键点

镜像管理 — 提前规划所需镜像清单
依赖处理 — 使用 apt download -d 获取完整依赖
版本锁定 — 确保所有节点版本一致
本地源 — 可选配置本地 apt 源加速部署
文档记录 — 记录所有版本号和配置参数

下一步优化

[ ] 配置本地 apt 源（apt-ftparchive）
[ ] 部署本地镜像仓库（Harbor/registry）
[ ] 配置持久化存储（Local Path Provisioner）
[ ] 部署 Ingress Controller（Nginx Ingress）
[ ] 设置监控告警（Prometheus + Grafana 离线版）
[ ] 实现备份恢复（Velero 离线配置）
[ ] 配置 GitLab CI 离线流水线

离线资源清单模板

# 保存此清单用于未来部署
K8s 版本：v1.28.0
架构：arm64
日期：2026-05-14

必需包:
- kubeadm_1.28.0-00_arm64.deb
- kubelet_1.28.0-00_arm64.deb
- kubectl_1.28.0-00_arm64.deb
- containerd.io_1.6.22_arm64.deb

必需镜像:
- calico/operator:v1.30.3
- calico/node:v3.26.1
- calico/cni:v3.26.1
- calico/kube-controllers:v3.26.1
- calico/pod2daemon-flexvol:v3.26.1
- nginx:alpine (测试用)

更新时间: 2026-05-14
阅读时间: 20 分钟
适用场景: 内网环境、等保要求、金融系统、离线服务器、ARM64 架构

LangChain 与 LangGraph 深度解析

Thu, 14 May 2026 00:00:00 GMT

LangChain 与 LangGraph 深度解析

本文将深入探讨 LangChain 框架和 LangGraph 状态机，从基础概念到高级应用，帮助你构建复杂、可维护的 AI Agent 系统。

为什么需要 LangChain 和 LangGraph？

传统 LLM 应用的局限性

直接使用 LLM 面临以下挑战：

状态管理困难 — 多轮对话难以维护上下文
工作流复杂 — 多步骤任务编排混乱
可观测性差 — 难以调试和监控
缺乏循环 — 无法实现迭代优化
人类介入难 — 难以实现人机协作

LangChain 的解决方案

LangChain 提供了：

📦 模块化组件 — 链、提示词、记忆、工具
🔗 编排能力 — 将多个组件串联
🧠 记忆管理 — 维护对话历史
🛠️ 工具集成 — 连接外部 API 和数据源

LangGraph 的进阶能力

LangGraph 在 LangChain 基础上增加了：

🔄 循环工作流 — 支持迭代和重试
🎯 状态机 — 明确的状态转换
👥 人机协作 — 人类审核和干预
📊 可视化 — 工作流图可视化
💾 持久化 — 检查点和恢复

LangChain 核心概念

1. 链 (Chains)

链是 LangChain 的基本构建块，将多个组件串联起来。

from langchain.llms import OpenAI
from langchain.prompts import PromptTemplate
from langchain.chains import LLMChain

# 创建提示模板
prompt = PromptTemplate(
    input_variables=["topic"],
    template="请写一篇关于 {topic} 的短文，不超过 200 字。"
)

# 创建 LLM
llm = OpenAI(temperature=0.7)

# 创建链
chain = LLMChain(llm=llm, prompt=prompt)

# 执行
result = chain.run("人工智能")
print(result)

2. 提示词管理 (Prompts)

from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder

# 聊天提示模板
prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个有帮助的助手。"),
    MessagesPlaceholder("chat_history"),  # 对话历史
    ("human", "{input}")  # 用户输入
])

# 格式化提示
messages = prompt.format_messages(
    chat_history=[...],
    input="你好"
)

3. 记忆 (Memory)

记忆组件维护对话历史，实现多轮对话。

from langchain.memory import ConversationBufferMemory
from langchain.chains import ConversationChain

# 创建带记忆的链
memory = ConversationBufferMemory(
    memory_key="chat_history",
    return_messages=True
)

conversation = ConversationChain(
    llm=llm,
    memory=memory,
    verbose=True
)

# 多轮对话
conversation.predict(input="我叫 Edward")
conversation.predict(input="我做什么工作的？")

记忆类型对比：

| 类型 | 说明 | 适用场景 | | ------------------------------ | --------- | ----------- | | ConversationBufferMemory | 存储所有历史消息 | 简单对话 | | ConversationBufferWindowMemory | 只保留最近 N 条 | 长对话节省 token | | ConversationSummaryMemory | 摘要历史对话 | 超长对话 | | EntityMemory | 提取实体信息 | 需要记住事实的对话 |

4. 工具 (Tools)

工具让 LLM 能够调用外部函数和 API。

from langchain.agents import tool

@tool
def get_current_weather(city: str) -> str:
    """获取当前天气信息"""
    # 模拟天气数据
    return f"{city} 当前温度 25°C，晴天"

@tool
def search_web(query: str) -> str:
    """搜索网络信息"""
    # 调用搜索引擎 API
    return f"搜索结果：{query} 的相关信息"

tools = [get_current_weather, search_web]

5. 代理 (Agents)

代理能够自主选择和使用工具。

from langchain.agents import initialize_agent, AgentType

# 初始化代理
agent = initialize_agent(
    tools,
    llm,
    agent=AgentType.CHAT_ZERO_SHOT_REACT_DESCRIPTION,
    handle_parsing_errors=True,
    verbose=True
)

# 执行任务
response = agent.run("北京的天气怎么样？")
print(response)

LangGraph 核心概念

什么是 LangGraph？

LangGraph 是基于 LangChain 的有向图框架，用于构建多 Agent、多步骤的 AI 应用。

核心特性：

状态机 — 明确定义状态和转换
循环 — 支持迭代和重试
人机协作 — 人类审核节点
持久化 — 检查点和恢复
可视化 — 自动生成流程图

1. 图的基本结构

from langgraph.graph import StateGraph, END

# 定义状态
class State(TypedDict):
    input: str
    output: str
    iterations: int
    approval: bool

# 创建图
workflow = StateGraph(State)

# 添加节点
workflow.add_node("agent", agent_node)
workflow.add_node("human", human_approval_node)
workflow.add_node("refine", refinement_node)

# 添加边
workflow.add_edge("agent", "human")
workflow.add_conditional_edges(
    "human",
    should_refine,  # 条件函数
    {
        "yes": "refine",
        "no": END
    }
)

# 设置入口点
workflow.set_entry_point("agent")

# 编译图
app = workflow.compile()

2. 状态管理

状态是 LangGraph 的核心，在节点间传递。

from typing import TypedDict, Annotated, Sequence
from langgraph.graph.message import add_messages
from langchain_core.messages import BaseMessage

# 定义状态
class AgentState(TypedDict):
    messages: Annotated[Sequence[BaseMessage], add_messages]
    context: dict
    loop_count: int
    human_approved: bool

# 节点函数接收和返回状态
def agent_node(state: AgentState) -> AgentState:
    # 访问状态
    messages = state["messages"]
    
    # 处理逻辑
    response = llm.invoke(messages)
    
    # 返回更新的状态
    return {"messages": [response]}

def human_approval_node(state: AgentState) -> AgentState:
    # 等待人类审批
    approval = wait_for_human_approval(state["messages"])
    
    return {"human_approved": approval}

3. 条件边

条件边根据状态决定下一步走向。

def should_continue(state: AgentState) -> Literal["tools", "end"]:
    """决定是否继续执行工具"""
    last_message = state["messages"][-1]
    
    if last_message.tool_calls:
        return "tools"
    return "end"

def check_approval(state: AgentState) -> Literal["approve", "reject", "revise"]:
    """检查人类审批结果"""
    if state["human_approved"]:
        return "approve"
    elif state["loop_count"] > 3:
        return "reject"
    return "revise"

# 添加条件边
workflow.add_conditional_edges(
    "agent",
    should_continue,
    {
        "tools": "tool_executor",
        "end": END
    }
)

workflow.add_conditional_edges(
    "human",
    check_approval,
    {
        "approve": END,
        "reject": "end_with_error",
        "revise": "agent"
    }
)

4. 循环和迭代

LangGraph 天然支持循环，通过条件边实现。

# 定义最大迭代次数
MAX_ITERATIONS = 5

def iterative_refinement(state: AgentState) -> AgentState:
    """迭代优化答案"""
    if state["loop_count"] >= MAX_ITERATIONS:
        return {"loop_count": state["loop_count"]}
    
    # 生成改进版本
    improved = refine_answer(state["messages"])
    
    return {
        "messages": [improved],
        "loop_count": state["loop_count"] + 1
    }

# 添加循环边
workflow.add_edge("refine", "agent")  # 回到 agent 节点

5. 持久化和检查点

from langgraph.checkpoint.memory import MemorySaver

# 创建检查点存储器
checkpointer = MemorySaver()

# 编译时传入
app = workflow.compile(
    checkpointer=checkpointer,
    interrupt_before=["human"]  # 在 human 节点前中断
)

# 创建线程
config = {"configurable": {"thread_id": "1"}}

# 执行并保存状态
result = app.invoke({"messages": ["你好"]}, config)

# 恢复状态继续执行
result = app.invoke({"messages": ["继续"]}, config)

实战案例

案例 1：带人类审核的内容生成

from langgraph.graph import StateGraph, END
from typing import TypedDict, Annotated
from langchain_core.messages import HumanMessage, AIMessage

class ContentState(TypedDict):
    topic: str
    draft: str
    feedback: str
    approved: bool
    iteration: int

def generate_draft(state: ContentState) -> ContentState:
    """生成内容草稿"""
    prompt = f"""
    请写一篇关于 {state['topic']} 的文章。
    {f'根据反馈改进：{state["feedback"]}' if state.get('feedback') else ''}
    """
    
    response = llm.invoke(prompt)
    return {"draft": response.content, "iteration": state.get("iteration", 0) + 1}

def human_review(state: ContentState) -> ContentState:
    """人类审核"""
    print(f"当前草稿：{state['draft']}")
    print(f"迭代次数：{state['iteration']}")
    
    # 模拟人类输入
    approval = input("批准？(y/n/r 修订): ")
    
    if approval == 'y':
        return {"approved": True}
    elif approval == 'n':
        return {"approved": False}
    else:
        feedback = input("提供反馈：")
        return {"feedback": feedback, "approved": False}

def decide_next(state: ContentState) -> str:
    """决定下一步"""
    if state["approved"]:
        return "end"
    elif state["iteration"] >= 3:
        return "end"  # 达到最大迭代
    return "revise"

# 构建图
workflow = StateGraph(ContentState)

workflow.add_node("generate", generate_draft)
workflow.add_node("review", human_review)

workflow.set_entry_point("generate")
workflow.add_edge("generate", "review")

workflow.add_conditional_edges(
    "review",
    decide_next,
    {
        "revise": "generate",
        "end": END
    }
)

app = workflow.compile()

# 执行
result = app.invoke({
    "topic": "人工智能的未来",
    "iteration": 0
})

print(f"最终内容：{result['draft']}")

案例 2：多 Agent 协作系统

from typing import Literal

class MultiAgentState(TypedDict):
    query: str
    research: str
    analysis: str
    draft: str
    final_answer: str

# 研究 Agent
def researcher(state: MultiAgentState) -> MultiAgentState:
    """收集信息"""
    research_tools = [search_web, get_wikipedia, read_document]
    
    agent = create_agent(research_tools, "研究专家")
    result = agent.run(f"研究主题：{state['query']}")
    
    return {"research": result}

# 分析 Agent
def analyst(state: MultiAgentState) -> MultiAgentState:
    """分析信息"""
    prompt = f"""
    基于以下研究结果进行分析：
    {state['research']}
    
    请提供：
    1. 关键发现
    2. 数据支持
    3. 潜在问题
    """
    
    analysis = llm.invoke(prompt)
    return {"analysis": analysis.content}

# 写作 Agent
def writer(state: MultiAgentState) -> MultiAgentState:
    """撰写答案"""
    prompt = f"""
    综合以下信息撰写最终答案：
    
    研究：{state['research']}
    分析：{state['analysis']}
    
    要求：
    - 结构清晰
    - 论据充分
    - 语言流畅
    """
    
    draft = llm.invoke(prompt)
    return {"draft": draft.content}

# 评审 Agent
def reviewer(state: MultiAgentState) -> Literal["approve", "revise"]:
    """评审答案"""
    prompt = f"""
    评审以下答案质量：
    {state['draft']}
    
    评分标准：
    - 准确性
    - 完整性
    - 逻辑性
    
    如果满意返回 'approve'，否则返回 'revise'
    """
    
    review = llm.invoke(prompt)
    return "approve" if "满意" in review.content else "revise"

# 构建多 Agent 图
workflow = StateGraph(MultiAgentState)

workflow.add_node("researcher", researcher)
workflow.add_node("analyst", analyst)
workflow.add_node("writer", writer)
workflow.add_node("reviewer", reviewer)

# 定义流程
workflow.set_entry_point("researcher")
workflow.add_edge("researcher", "analyst")
workflow.add_edge("analyst", "writer")
workflow.add_edge("writer", "reviewer")

# 添加条件边
workflow.add_conditional_edges(
    "reviewer",
    (lambda state: "revise" if reviewer(state) == "revise" else "end"),
    {
        "revise": "writer",
        "end": END
    }
)

app = workflow.compile()

# 执行
result = app.invoke({"query": "量子计算的发展现状"})
print(result["draft"])

案例 3：ReAct 模式实现

from langgraph.prebuilt import ToolNode
from langchain.agents import AgentExecutor

class ReActState(TypedDict):
    messages: Annotated[list, add_messages]
    tool_output: str

def model_node(state: ReActState) -> ReActState:
    """LLM 决策节点"""
    messages = state["messages"]
    
    # 使用能够进行工具调用的模型
    response = llm_with_tools.invoke(messages)
    
    return {"messages": [response]}

def tool_node(state: ReActState) -> ReActState:
    """工具执行节点"""
    # 执行工具调用
    tool_calls = state["messages"][-1].tool_calls
    
    outputs = []
    for tool_call in tool_calls:
        tool = tools_by_name[tool_call["name"]]
        response = tool.invoke(tool_call["args"])
        outputs.append(response)
    
    return {"tool_output": "\n".join(outputs)}

def should_continue(state: ReActState) -> Literal["tools", "end"]:
    """判断是否需要调用工具"""
    messages = state["messages"]
    last_message = messages[-1]
    
    if last_message.tool_calls:
        return "tools"
    return "end"

# 构建 ReAct 图
workflow = StateGraph(ReActState)

workflow.add_node("agent", model_node)
workflow.add_node("tools", ToolNode(tools))

workflow.set_entry_point("agent")

workflow.add_conditional_edges(
    "agent",
    should_continue,
    {
        "tools": "tools",
        "end": END
    }
)

workflow.add_edge("tools", "agent")

app = workflow.compile()

# 执行
result = app.invoke({
    "messages": [HumanMessage(content="北京今天的天气如何？")]
})

print(result["messages"][-1].content)

高级模式

1. 子图 (Subgraphs)

将复杂工作流分解为子图。

# 创建子图
research_workflow = StateGraph(ResearchState)
research_workflow.add_node("search", search_node)
research_workflow.add_node("analyze", analyze_node)
research_workflow.compile()

# 在主图中使用子图
main_workflow = StateGraph(MainState)
main_workflow.add_node("research", research_workflow)
main_workflow.add_node("write", write_node)

2. 并发执行

from langgraph.graph import START

# 并行启动多个节点
workflow.add_edge(START, "researcher")
workflow.add_edge(START, "data_collector")
workflow.add_edge(START, "context_loader")

# 汇合点
workflow.add_edge("researcher", "synthesizer")
workflow.add_edge("data_collector", "synthesizer")
workflow.add_edge("context_loader", "synthesizer")

3. 动态图

根据运行时状态动态修改图结构。

def dynamic_router(state: State) -> str:
    """动态决定执行路径"""
    if state["complexity"] > 0.8:
        return "complex_workflow"
    elif state["complexity"] > 0.5:
        return "medium_workflow"
    return "simple_workflow"

workflow.add_conditional_edges(
    START,
    dynamic_router,
    {
        "simple_workflow": "simple_agent",
        "medium_workflow": "medium_agent",
        "complex_workflow": "complex_agent"
    }
)

4. 超时和重试

from langgraph.pregel import RetryPolicy

app = workflow.compile(
    checkpointer=checkpointer,
    retry_policy=RetryPolicy(
        max_attempts=3,
        interval=1.0,
        backoff=2.0
    ),
    timeout=300  # 5 分钟超时
)

调试和监控

1. 可视化

# 生成流程图
app.get_graph().draw_mermaid_png(output_path="workflow.png")

# 或生成 Mermaid 代码
mermaid = app.get_graph().draw_mermaid()
print(mermaid)

2. 日志记录

from langgraph.prebuilt import InjectedState

def logged_node(state: AgentState) -> AgentState:
    import logging
    logging.info(f"进入节点，状态：{state}")
    
    # 处理逻辑
    result = process(state)
    
    logging.info(f"节点完成，返回：{result}")
    return result

3. 追踪

from langchain.tracers import LangChainTracer

with LangChainTracer(project="langgraph-demo") as tracer:
    result = app.invoke(input_data)

最佳实践

1. 状态设计

✅ 使用 TypedDict 定义明确的状态结构
✅ 保持状态不可变，返回新状态而非修改
✅ 使用 Annotated 和 reducer 函数管理复杂状态

2. 节点设计

✅ 单一职责：每个节点只做一件事
✅ 无副作用：节点不应修改外部状态
✅ 可测试：节点函数应易于单元测试

3. 错误处理

def safe_node(state: State) -> State:
    try:
        result = risky_operation(state)
        return {"result": result}
    except Exception as e:
        return {
            "error": str(e),
            "fallback": default_value
        }

4. 性能优化

使用异步节点处理 I/O 密集型任务
缓存重复计算结果
合理设置超时和重试策略
使用检查点避免重复计算

LangChain vs LangGraph 对比

| 特性 | LangChain | LangGraph | |------|-----------|-----------| | 工作流类型 | 线性链 | 有向图 | | 循环支持 | 有限 | 原生支持 | | 状态管理 | 简单 | 复杂状态机 | | 人机协作 | 困难 | 内置支持 | | 持久化 | 基础 | 检查点机制 | | 可视化 | 简单 | 完整流程图 | | 适用场景 | 简单任务 | 复杂 Agent 系统 |

总结

核心要点

LangChain 提供了构建 LLM 应用的基础组件
LangGraph 在 LangChain 之上增加了图结构和状态机
状态管理 是 LangGraph 的核心，确保数据在节点间正确传递
条件边 实现动态流程控制
检查点 支持持久化和恢复
人机协作 实现人类审核和干预

学习路径

掌握 LangChain 基础：链、提示词、记忆、工具
理解 LangGraph 核心：状态、节点、边
实践常见模式：ReAct、人类审核、多 Agent
探索高级特性：子图、并发、动态图
学习调试和监控技巧

下一步

[ ] 阅读官方文档：https://langchain-ai.github.io/langgraph/
[ ] 尝试构建自己的 Agent 系统
[ ] 学习 LangSmith 追踪和调试
[ ] 探索与其他框架的集成
[ ] 参与开源社区贡献

更新时间: 2026-05-14
阅读时间: 25 分钟
适用场景: LLM 应用开发、Agent 系统构建、工作流编排

参考资源

从零搭建 Astro 个人博客

Sun, 10 May 2026 00:00:00 GMT

从零搭建 Astro 个人博客

本文记录使用 Astro 构建个人博客的完整流程，涵盖项目初始化、内容管理、交互优化、组件抽象等核心环节，并总结实际开发中的最佳实践。

一、技术选型

为什么选择 Astro？

Astro 是专为内容驱动型网站设计的现代 Web 框架，核心优势包括：

零 JavaScript 输出 — 默认不发送 JS，按需 hydration，性能极致
静态生成优先 — 预渲染 HTML，SEO 友好
多框架兼容 — 可混用 React、Vue、Svelte 组件
Markdown 原生支持 — Content Collections 提供类型安全的内容管理

技术栈

| 模块 | 技术选型 | 理由 | |------|----------|------| | 框架 | Astro 4.x | 静态生成，零 JS 输出 | | 样式 | TailwindCSS | 原子化 CSS，开发效率高 | | 内容 | Markdown + Content Collections | 类型安全，写作体验佳 | | 部署 | Cloudflare Pages | 全球 CDN，自动 HTTPS，免费 | | 版本控制 | GitHub | 免费托管，CI/CD 集成 |

二、项目初始化

创建项目

npm create astro@latest my-blog
# 或
npx create-astro@latest my-blog

推荐选项：

使用空模板（Empty）
启用 TypeScript
添加 TailwindCSS 集成

安装 TailwindCSS

npm install -D @astrojs/tailwind tailwindcss

astro.config.mjs:

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  integrations: [tailwind()],
});

三、内容集合（Content Collections）

1. 定义 Schema

src/content/config.ts:

import { defineCollection, z } from 'astro:content';

const blogCollection = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.date(),
    tags: z.array(z.string()).default([]),
    pinned: z.boolean().default(false),
  }),
});

export const collections = {
  'blog': blogCollection,
};

Schema 设计要点：

title 和 description 为必填字段
pubDate 使用 z.date() 自动解析 ISO 字符串
tags 默认为空数组，避免未定义错误
pinned 控制文章置顶，默认 false

2. 创建文章

src/content/blog/your-post.md:

---
title: "文章标题"
description: "文章摘要，用于列表页展示"
pubDate: 2026-05-14
tags: ["技术", "笔记"]
pinned: true
---

# 正文

这里是文章内容...

Frontmatter 规范：

日期格式：YYYY-MM-DD（ISO 8601）
标签数组：使用双引号，避免解析错误
置顶标识：pinned: true 即可

四、核心功能实现

4.1 Tag 展示与筛选

问题描述

初始实现中，tag 标签挤在一起显示（如 "AI 自动化生产力"），缺乏间距和交互反馈。

设计目标

视觉：Stone 色系，适当间距，悬停微交互
交互：点击筛选，URL 同步，浏览器导航支持
无障碍：aria-label，键盘可访问

实现方案

单篇文章页 (src/pages/blog/[slug].astro):

<div class="row gap-2 flex-wrap">
  {post.data.tags.map((tag) => (
    <a href={`/blog?tag=${encodeURIComponent(tag)}`} 
       class="pill text-xs text-stone-600 bg-stone-100 hover:bg-stone-200 hover:text-stone-900 transition-colors px-2.5 py-0.5"
       aria-label={`查看 ${tag} 标签的文章`}>
      #{tag}
    </a>
  ))}
</div>

关键设计：

gap-2 flex-wrap：间距 + 换行
Stone 色系：text-stone-600 bg-stone-100
微交互：hover:bg-stone-200 transition-colors
标签前缀：# 符号
可点击：<a> 标签跳转列表页

博客列表页 (src/pages/blog.astro):

<!-- Tag 筛选按钮 -->
<div class="tags">
  <button class="tag" data-tag="all">
    全部 <span class="ct">({posts.length})</span>
  </button>
  {allTags.map((tag) => (
    <button class="tag" data-tag={tag}>
      {tag} <span class="ct">({tagCounts[tag]})</span>
    </button>
  ))}
</div>

<!-- 文章列表 -->
<ol class="posts" id="posts-list">
  {posts.map((post) => (
    <li class="post" data-tags={post.data.tags.join(',')}>
      <!-- 文章内容 -->
    </li>
  ))}
</ol>

客户端筛选逻辑 (<script is:inline>):

(function() {
  const tagButtons = document.querySelectorAll('.tag');
  const posts = document.querySelectorAll('#posts-list .post');
  const urlParams = new URLSearchParams(window.location.search);
  const selectedTag = urlParams.get('tag');

  // 初始化状态
  if (selectedTag) {
    tagButtons.forEach(btn => {
      btn.classList.toggle('on', btn.dataset.tag === selectedTag);
    });
    filterPosts(selectedTag);
  } else {
    tagButtons[0]?.classList.add('on');
  }

  // 点击筛选
  tagButtons.forEach(btn => {
    btn.addEventListener('click', () => {
      const tag = btn.dataset.tag;
      
      // 更新按钮状态
      tagButtons.forEach(b => b.classList.remove('on'));
      btn.classList.add('on');

      // 更新 URL（不刷新）
      const newUrl = tag === 'all' 
        ? '/blog' 
        : '/blog?tag=' + encodeURIComponent(tag);
      history.pushState({ tag: tag }, '', newUrl);

      // 筛选文章
      filterPosts(tag);
    });
  });

  // 筛选函数
  function filterPosts(tag) {
    posts.forEach(post => {
      const postTags = post.dataset.tags.split(',');
      post.style.display = (tag === 'all' || postTags.includes(tag)) ? '' : 'none';
    });
  }

  // 浏览器前进后退
  window.addEventListener('popstate', function(e) {
    var tag = (e.state && e.state.tag) || 'all';
    tagButtons.forEach(function(btn) {
      btn.classList.toggle('on', btn.dataset.tag === tag);
    });
    filterPosts(tag);
  });
})();

踩坑记录

问题 1：Script 组件压缩错误

错误写法：

import Script from 'astro:script';
<Script>
  const x = 1;
</Script>

正确写法：

<script is:inline>
  const x = 1;
</script>

问题 2：模板字符串兼容

错误写法（压缩后出错）：

const url = `/blog?tag=${encodeURIComponent(tag)}`;

正确写法：

const url = '/blog?tag=' + encodeURIComponent(tag);

问题 3：现代语法兼容

错误写法：

const tag = e.state?.tag || 'all';
tagButtons.forEach(btn => { ... });

正确写法：

var tag = (e.state && e.state.tag) || 'all';
tagButtons.forEach(function(btn) { ... });

最佳实践：

使用 <script is:inline> 而非 <Script> 组件
避免模板字符串，使用字符串拼接
避免可选链 ?. 和箭头函数，使用传统语法
使用 var 而非 const/let 增强兼容性

4.2 置顶文章功能

需求分析

支持文章置顶，置顶文章在列表和首页优先展示，并带有视觉标识。

实现方案

排序逻辑：

分离置顶和普通文章
各自按日期倒序排序
合并：置顶在前，普通在后

代码实现：

const pinnedPosts = allPosts.filter(post => post.data.pinned);
const normalPosts = allPosts.filter(post => !post.data.pinned);

const sortedPinned = pinnedPosts.sort((a, b) => {
  const dateA = a.data.pubDate || new Date(0);
  const dateB = b.data.pubDate || new Date(0);
  return dateB.getTime() - dateA.getTime();
});

const sortedNormal = normalPosts.sort((a, b) => {
  const dateA = a.data.pubDate || new Date(0);
  const dateB = b.data.pubDate || new Date(0);
  return dateB.getTime() - dateA.getTime();
});

const posts = [...sortedPinned, ...sortedNormal];

视觉标识：

<time class="date">
  {post.data.pubDate?.toLocaleDateString('zh-CN')}
  {post.data.pinned && (
    <span class="pinned-badge" title="置顶">📌</span>
  )}
</time>

CSS 样式：

.post.pinned .date {
  color: var(--accent);
  font-weight: 500;
}

.post.pinned .pinned-badge {
  display: inline-block;
  margin-left: 0.5rem;
  font-size: 14px;
}

.post.pinned .date::after {
  content: '• 置顶';
  display: block;
  color: var(--accent);
  font-size: 10px;
  margin-top: 2px;
}

效果：

日期高亮（主题色）
图钉图标 📌
"• 置顶" 文字说明

4.3 排序逻辑抽象化

问题

排序代码在首页、博客列表页重复，维护成本高。

解决方案

创建工具函数库，统一排序逻辑。

src/utils/posts.ts:

export interface BlogPost {
  data: {
    pubDate?: Date;
    pinned?: boolean;
    [key: string]: unknown;
  };
  slug: string;
  [key: string]: unknown;
}

/**
 * 按置顶和日期排序文章
 */
export function sortPostsByPinnedAndDate(posts: BlogPost[]): BlogPost[] {
  const pinnedPosts = posts.filter(post => post.data.pinned);
  const normalPosts = posts.filter(post => !post.data.pinned);

  const sortedPinned = pinnedPosts.sort((a, b) => {
    const dateA = a.data.pubDate || new Date(0);
    const dateB = b.data.pubDate || new Date(0);
    return dateB.getTime() - dateA.getTime();
  });

  const sortedNormal = normalPosts.sort((a, b) => {
    const dateA = a.data.pubDate || new Date(0);
    const dateB = b.data.pubDate || new Date(0);
    return dateB.getTime() - dateA.getTime();
  });

  return [...sortedPinned, ...sortedNormal];
}

/**
 * 按年月分组文章
 */
export function groupPostsByYearMonth(posts: BlogPost[]): Record<string, BlogPost[]> {
  const groups: Record<string, BlogPost[]> = {};

  posts.forEach(post => {
    if (!post.data.pubDate) {
      if (!groups['未发布']) groups['未发布'] = [];
      groups['未发布'].push(post);
      return;
    }

    const year = post.data.pubDate.getFullYear();
    const month = String(post.data.pubDate.getMonth() + 1).padStart(2, '0');
    const key = `${year}-${month}`;

    if (!groups[key]) groups[key] = [];
    groups[key].push(post);
  });

  return groups;
}

/**
 * 获取年月显示文本
 */
export function getYearMonthLabel(key: string): string {
  if (key === '未发布') return '未发布';
  const [year, month] = key.split('-');
  return `${year}年${parseInt(month)}月`;
}

复用示例：

src/pages/index.astro:

import { sortPostsByPinnedAndDate } from '../utils/posts';

const allPostsRaw = await getCollection('blog');
const allPosts = sortPostsByPinnedAndDate(allPostsRaw);
const latestPosts = allPosts.slice(0, 3);

优势：

代码复用，减少重复
统一排序逻辑，避免不一致
类型安全（TypeScript）
易于测试和维护

4.4 时间线组件

需求

在博客列表页右侧添加时间线，按年月分组展示文章，支持滚动跟随和折叠。

设计要点

布局：右侧固定宽度（280px），不挤占列表空间
定位：position: sticky，滚动时跟随
分组：按 2026 年 5 月 格式分组，显示文章数量
交互：可折叠，悬停效果，置顶标识
响应式：移动端隐藏

实现

src/components/Timeline.astro:

---
import { sortPostsByPinnedAndDate, groupPostsByYearMonth, getYearMonthLabel } from '../utils/posts';

interface Props {
  posts: {
    data: {
      pubDate?: Date;
      title: string;
      pinned?: boolean;
    };
    slug: string;
  }[];
}

const { posts } = Astro.props;
const sortedPosts = sortPostsByPinnedAndDate(posts);
const groupedPosts = groupPostsByYearMonth(sortedPosts);

const yearMonths = Object.keys(groupedPosts).sort((a, b) => {
  if (a === '未发布' || b === '未发布') return a === '未发布' ? 1 : -1;
  return b.localeCompare(a);
});
---

<aside class="timeline">
  <div class="timeline-header">
    <h3>时间线</h3>
    <div class="timeline-toggle" title="收起/展开">
      <svg width="16" height="16" viewBox="0 0 16 16" fill="none">
        <path d="M4 6L8 10L12 6" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>
      </svg>
    </div>
  </div>

  <div class="timeline-content">
    {yearMonths.map((yearMonth) => (
      <div class="timeline-group">
        <div class="timeline-year">
          <span class="year-label">{getYearMonthLabel(yearMonth)}</span>
          <span class="year-count">({groupedPosts[yearMonth].length})</span>
        </div>
        
        <ul class="timeline-list">
          {groupedPosts[yearMonth].map((post) => (
            <li class={`timeline-item ${post.data.pinned ? 'pinned' : ''}`}>
              <div class="timeline-dot"></div>
              <div class="timeline-content-item">
                <time class="timeline-date">
                  {post.data.pubDate?.toLocaleDateString('zh-CN', { month: 'numeric', day: 'numeric' })}
                </time>
                <a href={`/blog/${post.slug}`} class="timeline-title">
                  {post.data.title}
                  {post.data.pinned && <span class="pinned-icon">📌</span>}
                </a>
              </div>
            </li>
          ))}
        </ul>
      </div>
    ))}
  </div>
</aside>

<style>
  .timeline {
    position: sticky;
    top: 5rem;
    max-height: calc(100vh - 6rem);
    overflow-y: auto;
    border-left: 1px solid var(--border);
    padding-left: 1.5rem;
    margin-left: 2rem;
  }

  .timeline-header {
    display: flex;
    align-items: center;
    justify-content: space-between;
    padding: 1rem 0;
    border-bottom: 1px solid var(--border);
  }

  .timeline-content.collapsed {
    max-height: 0;
    opacity: 0;
    overflow: hidden;
  }

  .timeline-item {
    display: flex;
    align-items: flex-start;
    gap: 0.75rem;
    padding: 0.5rem 0;
    transition: transform 0.2s;
  }

  .timeline-item:hover {
    transform: translateX(4px);
  }

  .timeline-dot {
    width: 6px;
    height: 6px;
    border-radius: 50%;
    background: var(--text-muted);
    margin-top: 0.5rem;
    transition: all 0.2s;
  }

  .timeline-item:hover .timeline-dot {
    background: var(--accent);
    transform: scale(1.3);
  }

  @media (max-width: 768px) {
    .timeline {
      display: none;
    }
  }
</style>

<script is:inline>
  (function() {
    const toggle = document.querySelector('.timeline-toggle');
    const content = document.querySelector('.timeline-content');
    
    if (toggle && content) {
      toggle.addEventListener('click', () => {
        content.classList.toggle('collapsed');
        const svg = toggle.querySelector('svg path');
        if (svg) {
          const isCollapsed = content.classList.contains('collapsed');
          svg.setAttribute('d', isCollapsed ? 'M4 10L8 6L12 10' : 'M4 6L8 10L12 6');
        }
      });
    }
  })();
</script>

布局集成：

src/pages/blog.astro:

<section class="sec">
  <div class="posts-container">
    <ol class="posts" id="posts-list">
      <!-- 文章列表 -->
    </ol>
    <Timeline posts={posts} />
  </div>
</section>

src/styles/global.css:

.posts-container {
  display: grid;
  grid-template-columns: 1fr 280px;
  gap: 2rem;
  align-items: start;
}

交互效果：

悬停时文章右移 4px
圆点放大并高亮
置顶文章圆点始终高亮
点击标题收起/展开

五、部署与优化

5.1 Cloudflare Pages 部署

构建项目
```
npm run build
```
配置 Cloudflare Pages
- 连接 GitHub 仓库
- 构建命令：npm run build
- 输出目录：dist
- 框架预设：Astro
自定义域名
- 在 Cloudflare Dashboard 添加自定义域名
- 自动配置 HTTPS

5.2 性能优化

构建优化：

使用 SSG（静态生成），避免 SSR
图片懒加载
字体子集化

运行时优化：

零 JavaScript 输出（按需 hydration）
客户端筛选使用原生 DOM 操作，无框架依赖
避免重排重绘，使用 transform 动画

5.3 SEO 优化

语义化 HTML 标签（<article>, <time>, <aside>）
Meta 标签完整（title, description, Open Graph）
结构化数据（JSON-LD）
站点地图（sitemap.xml）
RSS 订阅

六、最佳实践总结

6.1 代码组织

工具函数抽象：排序、分组、格式化等通用逻辑放入 src/utils/
组件复用：时间线、Tag 等可复用 UI 放入 src/components/
类型安全：使用 TypeScript，定义清晰的接口

6.2 内容管理

Frontmatter 规范：统一字段命名和格式
标签命名：使用有意义的关键词，避免过长
置顶策略：仅对重要文章使用 pinned: true

6.3 交互设计

无刷新筛选：使用 history.pushState 更新 URL
浏览器导航：监听 popstate 事件支持前进后退
无障碍：添加 aria-label，键盘可访问

6.4 性能优先

避免框架依赖：客户端交互使用原生 JavaScript
减少重排：使用 transform 而非 top/left
按需加载：图片、字体懒加载

七、后续扩展

已实现功能

[x] 评论系统（Giscus）
[x] 全文搜索（FlexSearch）
[x] RSS 订阅
[x] Tag 云图
[x] 相关文章推荐
[x] 时间线导航
[x] 暗黑模式（浅色/深色/跟随系统）
[x] 标签筛选
[x] 置顶文章
[x] 自定义面板（主题/字体/密度）

待实现功能

用户体验

[x] 键盘导航 - j/k 切换文章，/ 聚焦搜索，Esc 关闭弹窗 ✅ 2026-05-21
[x] 图片懒加载 + 缩略图 - loading="lazy" + 响应式 srcset ✅ 2026-05-21
[x] 代码块复制按钮 - 一键复制代码，带 Toast 反馈 ✅ 2026-05-21
[x] 阅读进度条 - 页面顶部显示阅读进度 ✅ 2026-05-21
[x] 目录导航（TOC） - 左侧章节目录，滚动高亮 ✅ 2026-05-21
[x] 阅读时长估算 - 根据字数估算阅读时间 ✅ 2026-05-21
[x] 回到顶部按钮 - 滚动 300px 后显示 ✅ 2026-05-21
[x] 分享功能 - 微信/微博/Twitter/复制链接/二维码 ✅ 2026-05-21

性能优化

[x] 性能优化 - Lighthouse 评分目标（性能 95+，SEO 100） ✅ 2026-05-21
- 图片优化：使用 astro/assets，WebP 转换，响应式图片
- 预加载关键资源：<link rel="preconnect"> + <link rel="preload">
- 减少重排：使用 transform 而非 top/left
[x] 字体优化 - font-display: swap 防止 FOIT，子集化，本地托管 ✅ 2026-05-21
[x] 缓存策略 - Service Worker + HTTP 缓存头优化 ✅ 2026-05-21

SEO 与可访问性

[ ] SEO 优化 - 结构化数据（JSON-LD），Open Graph 元标签
- BlogPosting 结构化数据
- Twitter Cards
- 站点地图（sitemap.xml）
[ ] 无障碍增强 - skip to main 链接，焦点可见性，ARIA 标签

高级功能

[ ] PWA 支持 - 离线访问，添加到主屏幕
[x] 多语言切换 - 中英文切换（i18n） ✅ 2026-05-21
[ ] 网站统计 - Umami / Plausible（隐私友好）
[ ] 邮件订阅 - Newsletter 新文章推送

更新时间: 2026-05-14
阅读时间: 12 分钟