04｜LangChain / LlamaIndex 核心与高级用法

1. LangChain 与 LangGraph

1.1 LangChain 1.x 的核心心智模型

当前 LangChain 将 create_agent 作为构建 Agent 的标准入口。一个 Agent 主要由模型、工具、系统指令和中间件组成，其底层运行基于 LangGraph，因此可获得状态、持久化、流式输出和人机协同能力。

from langchain.agents import create_agent
from langchain.tools import tool

@tool
def get_course_hours(module: str) -> str:
    """查询课程模块的建议学时。"""
    mapping = {"RAG": "10 学时", "Memory": "8 学时"}
    return mapping.get(module, "未找到")

agent = create_agent(
    model="openai:gpt-5.5",  # 可替换为其他供应商或本地模型
    tools=[get_course_hours],
    system_prompt="你是课程助教。只在需要课程数据时调用工具。",
)

result = agent.invoke({
    "messages": [{"role": "user", "content": "RAG 模块建议学多久？"}]
})
print(result["messages"][-1].content)

模型名称与供应商配置会更新，实践时以官方文档和账户实际可用模型为准。课程重点是工具 Schema、状态和执行链，而不是绑定某个模型名称。

1.2 Prompt、Tool、Middleware 与 State

• Prompt / Instructions：定义角色、边界、输出格式和工具选择原则；
• Tool：模型可调用的受控函数；
• Middleware：在模型调用和工具调用前后插入路由、审计、限额和安全检查；
• State：保存消息、业务字段和中间结果；
• Checkpoint：支持暂停、恢复与失败重试。

1.3 Workflow 与 Agent 的差异

LangGraph 官方将 Workflow 描述为预定代码路径，将 Agent 描述为动态决定流程和工具。真实系统常把二者组合：外层用固定工作流保证可控，局部节点使用 Agent 处理不确定任务。

固定入口 → 权限检查 → [Agent 进行问题理解与工具选择] → 引用校验 → 人工审批 → 固定输出

1.4 条件状态图示例

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

class State(TypedDict):
    query: str
    risk: str
    answer: str


def classify(state: State):
    high_risk_words = ("诊断", "转账", "删除")
    risk = "high" if any(x in state["query"] for x in high_risk_words) else "normal"
    return {"risk": risk}


def answer(state: State):
    return {"answer": f"已处理：{state['query']}"}


def request_human(state: State):
    return {"answer": "该任务需要人工确认"}


def route(state: State):
    return "human" if state["risk"] == "high" else "answer"

builder = StateGraph(State)
builder.add_node("classify", classify)
builder.add_node("answer", answer)
builder.add_node("human", request_human)
builder.add_edge(START, "classify")
builder.add_conditional_edges("classify", route, {"human": "human", "answer": "answer"})
builder.add_edge("human", END)
builder.add_edge("answer", END)
graph = builder.compile()

2. LlamaIndex 数据与知识框架

LlamaIndex 将知识型应用拆为数据加载、节点化、索引、检索、后处理、响应合成和评估。它也提供基于工具调用的 Agent 和事件驱动 Workflow。

2.1 文档到索引

from llama_index.core import SimpleDirectoryReader, VectorStoreIndex

# data/ 中可放 txt、md、pdf 等；PDF 解析质量需单独评估
records = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(records)
query_engine = index.as_query_engine(similarity_top_k=4)
response = query_engine.query("课程如何区分 MCP 与 A2A？")
print(response)

真正项目中还应配置：

• 文档 ID 和版本；
• 分块策略与元数据；
• 部门、用户或项目权限；
• Embedding 与向量库；
• Top-K、重排与引用；
• 增量更新和删除传播。

2.2 FunctionAgent

LlamaIndex 官方当前示例使用 FunctionAgent 将 LLM、Memory 和 Tools 组合为 Agent。

import asyncio
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI


def multiply(a: float, b: float) -> float:
    """计算两个数的乘积。"""
    return a * b

agent = FunctionAgent(
    tools=[multiply],
    llm=OpenAI(model="gpt-4o-mini"),
    system_prompt="你是数学助教，需要计算时调用工具。",
)

async def main():
    result = await agent.run("1234 × 4567 是多少？")
    print(result)

asyncio.run(main())

2.3 检索器、后处理器与响应合成器

• Retriever 决定候选证据；
• Node Postprocessor 过滤、重排或压缩；
• Response Synthesizer 将证据转换为答案；
• Evaluator 检查检索和回答质量。

把这些组件拆开，才能准确定位 Bad Case：是“没召回”，还是“召回后排序错”，抑或“有证据但生成错误”。

3. CoT、ReAct 与工具调用

Chain-of-Thought 论文展示了中间推理步骤对复杂推理任务的帮助；ReAct 将推理与行动交替，使模型能通过外部环境获取信息。工程应用中，应避免把冗长私有推理直接展示给用户，改为记录简洁的行动计划和证据链。

3.1 ReAct 的可审计表示

{
  "goal": "回答制度有效期",
  "action_summary": "查询最新制度版本",
  "tool": "search_policy",
  "tool_input": {"keyword": "差旅管理"},
  "observation": {"document_id": "P-2026-04", "effective_date": "2026-04-01"},
  "next": "生成带引用答案"
}

这比保存模型的自由文本推理更容易做权限控制、质量分析和数据脱敏。

4. 高级工程化用法

4.1 动态上下文

不同节点只加载所需上下文：分类节点不需要全文文档，生成节点不需要所有历史工具日志。可通过状态字段和检索器按需注入，减少 Token 和干扰。

4.2 长文档摘要压缩

推荐两级结构：

1. 保存原文切片和章节摘要；
2. 检索时先找章节，再在章节内部找细粒度证据；
3. 最终上下文保留原文片段，摘要只用于导航，避免摘要错误成为事实来源。

4.3 Prompt 资产管理

Prompt 应具备 ID、版本、适用模型、变量 Schema、评测集和变更记录。上线前跑批量回归测试，不通过则不能发布。

prompt_id: policy_answer_v3
owner: knowledge-team
inputs: [question, evidence, user_role]
output_schema: AnswerWithCitations
required_tests: [policy_basic, outdated_policy, permission_denied]

4.4 Token 成本管理

• 使用小模型处理分类和抽取；
• 对静态系统指令使用供应商支持的缓存；
• 历史对话压缩为结构化状态；
• 限制检索数量并去重；
• 记录每节点 Token，定位成本热点；
• 为 Agent 设置最大轮次和总预算。

5. 应用案例：课程问答助手

5.1 组合方案

• LlamaIndex：读取课程 Markdown、建立索引、返回证据片段；
• LangGraph：权限检查、检索、回答、引用验证和低置信度转人工；
• LangChain Tool：将检索器包装为工具；
• 评估：准备 30 个问题，标注正确章节和关键词。

5.2 项目步骤

1. 将本站课程文件复制到 data/course/；
2. 用 LlamaIndex 建立本地索引；
3. 定义 search_course 工具；
4. 用 LangGraph 编排回答与引用检查；
5. 针对“无答案、跨章节、过时信息、恶意指令”测试；
6. 对失败样例分别标记 retrieval / generation / policy / tool。

5.3 可复现的框架迁移实验

cd repository/enterprise-agent-lab
python -m unittest discover -s tests -v
python -m app.cli --question "设备 P-100 的高温处理依据是什么？"

先保存标准库基线的状态、证据和测试结果，再建立独立虚拟环境，按官方安装页固定 LangChain/LangGraph/LlamaIndex 版本。迁移时只替换编排和索引适配层，继续复用 schemas.py、tools.py 的权限与幂等规则；框架不能成为业务规则的唯一存放处。

对同一评估集比较基线与框架版的任务成功率、证据命中、P95 延迟和 Token。部署时导出锁文件，启动前重建索引并验证 checkpoint 存储；项目 DEPLOY.md 提供服务、反向代理和回滚基线。验收必须给出版本锁、最小可运行命令、30 条评估结果和框架升级回滚步骤。

6. 可靠参考资料

• LangChain Agents最新 create_agent、Tools 与 Middleware。
• LangGraph Overview持久化、流式、人机协同与记忆。
• LlamaIndex AgentsFunctionAgent、工具与运行循环。
• LlamaIndex Evaluation检索与响应评估。
• LangChain Academy：Introduction to LangGraph官方课程，配合当前文档练习状态图、持久化和人机协同。
• LangChain：LangGraph Introduction官方视频入口；涉及 API 时以对应版本文档为准。
• Chain-of-Thought 原始论文理解复杂推理提示的研究背景。
• ReAct 原始论文推理与行动交替。
• DSPy: Compiling Declarative Language Model Calls into Self-Improving Pipelines （ICLR 2024）Paper and venue are linked above. Code: https://github.com/stanfordnlp/dspy.
• SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering （NeurIPS 2024）NeurIPS 正式出版页。Code: https://github.com/SWE-agent/SWE-agent.