LangChain / LangGraph 生态套件完全指南版本参考:2026年4月(LangChain v1.1+、L

版本参考:2026年4月(LangChain v1.1+、LangGraph v0.3.x、LangSmith 持续演进) 适用读者:已经在用 LangChain 或 LangGraph、希望系统性掌握周边工具链以搭建完整生产栈的资深工程师主仓库:

github.com/langchain-a…

github.com/langchain-a…

github.com/langchain-a…

生态全景图
LangSmith:可观测与评估平台
LangGraph Platform:Agent 部署运行时
LangGraph Studio:可视化调试器
LangServe:Runnable → REST
LangChain Hub:Prompt 共享
LangGraph CLI 与 LangChain CLI
预构建 Agent 组件家族
LangMem:长期记忆 SDK
Partner 包:模型与向量库
Checkpointer 与 Store 实现
MCP:Model Context Protocol 接入
前端 / UI 集成
评估框架生态
可观测替代方案
检索增强:Reranker / Embeddings
第三方工具聚合平台
典型生产栈组合
选型速查表

1. 生态全景图

┌────────────────────────────────────────────────────────────────┐
│                        终端用户 / 前端                           │
│    CopilotKit · assistant-ui · Chainlit · Streamlit · Gradio    │
└────────────────────────┬───────────────────────────────────────┘
                         │ HTTP / WebSocket / SSE
┌────────────────────────▼───────────────────────────────────────┐
│                   部署层 / API Gateway                          │
│    LangGraph Platform · LangServe · 自建 FastAPI                │
└────────────────────────┬───────────────────────────────────────┘
                         │
┌────────────────────────▼───────────────────────────────────────┐
│                  Agent 应用层                                   │
│    langchain (create_agent + middleware)                        │
│    langgraph (StateGraph + Pregel runtime)                      │
│    prebuilt: supervisor / swarm / bigtool / codeact            │
└───┬───────────────────┬────────────────┬──────────────┬────────┘
    │                   │                │              │
    │ trace             │ persist        │ tools        │ memory
    ▼                   ▼                ▼              ▼
┌─────────┐  ┌───────────────────┐  ┌────────┐  ┌────────────┐
│LangSmith│  │ Checkpointer      │  │  MCP   │  │ LangMem    │
│Langfuse │  │  sqlite/pg/redis  │  │Composio│  │ BaseStore  │
│Phoenix  │  │  mongodb          │  │Arcade  │  │ pgvector   │
└─────────┘  └───────────────────┘  └────────┘  └────────────┘
                         │
┌────────────────────────▼───────────────────────────────────────┐
│                   底层依赖:langchain-core                       │
│     Runnable · BaseMessage · BaseTool · Callbacks               │
└────────────────────────┬───────────────────────────────────────┘
                         │
              ┌──────────▼──────────┐
              │   Partner Packages  │
              │ openai/anthropic/   │
              │ google/aws/ollama…  │
              └─────────────────────┘

分层原则:

langchain-core 是唯一"中轴":所有套件都依赖它的 Runnable / BaseMessage / BaseTool 协议。
LangChain 和 LangGraph 是两套互为兼容的上层框架(v1.0 起 create_agent 编译为 LangGraph 图)。
LangSmith 贯穿所有层,零侵入挂载。
Platform / Studio / Hub / CLI 是开发运维工具链。
Partner / MCP / LangMem 是扩展点。

2. LangSmith

2.1 定位

LangSmith 是 LangChain Inc. 的 SaaS 可观测 + 评估 + 提示管理平台,也是整个生态里最值得先接入的套件。

核心能力:

Tracing:自动捕捉每次 Runnable / 节点 / 工具 / LLM 调用的嵌套 run 树
Datasets:把线上 trace 一键保存为测试集
Evaluators:LLM-as-judge / 规则 / 人工标注
Experiments:同一 dataset 跑多个版本对比指标
Prompt Hub:托管 prompt、版本化、playground 调试
Annotation Queues:人工审核队列
Monitoring:线上延迟/token/错误率 dashboard

2.2 零侵入接入

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=lsv2_...
export LANGSMITH_PROJECT=my-agent

只要设了环境变量,任何 LangChain Runnable / LangGraph 图执行都自动上传 trace。无需修改代码。

2.3 SDK 用法

from langsmith import Client, traceable

client = Client()

# 把任意函数变 traceable(非 LangChain 代码也可)
@traceable(run_type="tool", name="my_custom_fn")
def compute(x: int) -> int:
    return x * x

# 手动创建 dataset
dataset = client.create_dataset("triage-v1", description="线上采样")
client.create_examples(
    inputs=[{"text": "..."}],
    outputs=[{"label": "P0"}],
    dataset_id=dataset.id,
)

# 跑实验
from langsmith.evaluation import evaluate

def correctness(run, example):
    return {"score": run.outputs["label"] == example.outputs["label"]}

evaluate(
    lambda inputs: agent.invoke({"messages": [HumanMessage(inputs["text"])]}),
    data="triage-v1",
    evaluators=[correctness],
    experiment_prefix="triage-baseline",
)

2.4 Prompt Hub

from langchain import hub

# 拉远程 prompt(版本化)
prompt = hub.pull("hwchase17/react")

# 推送自己的 prompt
hub.push("my-org/triage-prompt", prompt)

好处:prompt 与代码解耦,产品/prompt engineer 可以在 UI 里迭代而不发版。

2.5 自托管(Self-hosted)

企业版提供 LangSmith Platform(Kubernetes部署),数据不出内网。API 兼容 SaaS,SDK 通过 LANGSMITH_ENDPOINT 切换。

2.6 为什么是"先接入的"

零代码改动、零运行时开销(异步上报)
线上问题 90% 的答案都在 trace 里(model 输入、tool 参数、中间步骤)
免费 tier 对个人/小团队足够
Datasets + Experiments 让你从第一天就有回归基线

3. LangGraph Platform

3.1 定位

专为 LangGraph 应用打造的托管部署平台,把一张 StateGraph 变成生产级 HTTP 服务:

Threads API:POST /threads、POST /threads/{id}/runs,天然的多轮会话
Runs API:同步 / 流式 / 后台
Cron:定时触发 graph
Store API:跨 thread 长期记忆(BaseStore 托管实现)
Human-in-the-loop:interrupt 与 resume 走 HTTP
Assistants:同一 graph 不同配置的版本化快照
Scheduling:按优先级排队、双文本(double-texting)策略(interrupt/rollback/reject/enqueue)
Webhooks:run 结束回调

3.2 部署模式

模式	场景
Cloud (SaaS)	最快路径,按使用计费
Hybrid	控制面在 LangChain Cloud,数据面自建
Self-hosted Enterprise	完全本地(K8s helm chart)
Self-hosted Lite	免费版,单机 docker compose

3.3 开发 → 部署工作流

# 1. 定义 langgraph.json
{
  "dependencies": ["."],
  "graphs": {"my_agent": "./agent.py:graph"},
  "env": ".env"
}

# 2. 本地 dev server(含 Studio)
langgraph dev

# 3. 构建 docker 镜像
langgraph build -t my-agent:latest

# 4. 部署
langgraph up     # 本地 docker
# 或推到 Cloud 控制台

3.4 Threads 示例

from langgraph_sdk import get_client

client = get_client(url="https://my-deployment.langgraph.app")

# 新会话
thread = await client.threads.create()

# 流式 run
async for event in client.runs.stream(
    thread["thread_id"],
    assistant_id="my_agent",
    input={"messages": [{"role": "user", "content": "Hi"}]},
    stream_mode="messages",
):
    print(event)

# 恢复 interrupt
await client.runs.wait(thread["thread_id"], run_id, command={"resume": "OK"})

3.5 与 FastAPI 自建的取舍

用 Platform:

Thread/Checkpoint/Store 基础设施全免
Double-texting、rate limit、retry 策略内置
与 Studio 无缝连接

自建 FastAPI + LangGraph:

完全自控,无供应商绑定
需要自己实现 thread 管理 / checkpointer 连接池 / 认证
适合重定制或已有 K8s 平台

4. LangGraph Studio

4.1 是什么

桌面应用(Mac/Windows/Linux)+ 浏览器版,连到 langgraph dev 本地 server 或 Platform 部署,提供图形化调试:

图结构可视化:看清节点、边、条件边、子图
状态时间旅行:点任意 superstep 回看状态快照
单步执行:跟 IDE 断点一样推进图
Interrupt 人工干预:UI 里直接 resume / update state
Thread 管理:多轮对话 / checkpoint 树浏览
Assistant 配置:对比不同 prompt / tool 配置的运行结果

4.2 典型工作流

# 在项目根目录
langgraph dev
# → 自动打开 Studio(或手动 https://smith.langchain.com/studio)

对开发 Agent 特别好用:

一边改代码,Studio 自动 hot reload
一边在左侧聊天区触发,右侧看节点状态变化
出问题点节点看 input/output,比 print 强 10 倍

4.3 与 LangSmith 的区别

Studio	LangSmith
开发期交互式调试	生产期 trace / eval / 监控
本地 graph + 实时单步	线上数据聚合与回放
免费(连本地 dev 或 Platform)	免费 tier + 付费

两者配合:Studio 负责"我的图是不是对的",LangSmith 负责"上线后还对不对"。

5. LangServe:LangChain v1 后的定位

5.1 它做什么

LangServe 是把 Runnable 一键变成 FastAPI 路由的小库:

from fastapi import FastAPI
from langserve import add_routes

app = FastAPI()
add_routes(app, chain, path="/rag")
# 自动生成:
#   POST /rag/invoke
#   POST /rag/batch
#   POST /rag/stream
#   POST /rag/stream_log
#   GET  /rag/playground    ← 内置 UI
#   GET  /rag/input_schema  ← OpenAPI

5.2 v1.0 时代的定位变化

对 Chain / 简单 Runnable:LangServe 仍然最短路径。
对 Agent / LangGraph 图:官方推荐用 LangGraph Platform(或 langgraph.server 的 self-host 模式),因为 Platform 提供了 Threads / Checkpointer / Interrupt / Store 等 Agent 专属基础设施,这些 LangServe 不具备。

一句话:LCEL chain 用 LangServe,Agent 用 Platform。

5.3 自建混合

在 FastAPI 里既挂 LangServe 路由(暴露链),又手写 Agent 路由(调用编译好的 LangGraph app),是中型团队常见选择。

6. LangChain Hub

6.1 内容

社区 + 官方 prompt、chain、example 的托管仓库(smith.langchain.com/hub):

Prompt 模板(ChatPromptTemplate、FewShotChatMessagePromptTemplate)
复合 Runnable(带版本号)
公共 evaluator prompt

6.2 用法

from langchain import hub

prompt = hub.pull("langchain-ai/openai-functions-template")
prompt_v2 = hub.pull("langchain-ai/openai-functions-template:v2")

# 私有
hub.pull("my-org/triage-prompt", include_model=True)

6.3 推送

hub.push("my-org/triage-prompt", prompt, new_repo_is_public=False)

版本自动递增,可在 LangSmith UI 里 diff 两版 prompt。

7. CLI 工具

7.1 LangGraph CLI

pip install langgraph-cli

核心命令:

命令	用途
`langgraph dev`	启动本地 API + Studio
`langgraph build -t IMG`	构建 docker 镜像
`langgraph up`	本地 docker compose 启动
`langgraph dockerfile -o Dockerfile`	导出 Dockerfile 自定义
`langgraph test`	跑项目测试

langgraph.json 是配置中心:

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./src/agent.py:graph",
    "reviewer": "./src/reviewer.py:graph"
  },
  "env": ".env",
  "python_version": "3.11",
  "store": {"index": {"embed": "openai:text-embedding-3-small", "dims": 1536}},
  "auth": {"path": "./auth.py:auth"}
}

7.2 LangChain CLI

pip install langchain-cli

生成 FastAPI + LangServe 骨架,以及模板项目:

langchain app new my-rag --package rag-chroma
cd my-rag
poetry install
poetry run uvicorn app.server:app --reload

在 v1.0 之后,LangChain CLI 的地位没有 LangGraph CLI 高——主要用于起 LangServe 项目;Agent 项目建议直接用 langgraph new。

8. 预构建 Agent 组件家族

8.1 langgraph-prebuilt

基础组件,create_agent 和 create_react_agent(legacy)都来自这里:

ToolNode:接 AIMessage.tool_calls → 执行 → 写回 ToolMessage
tools_condition:判断是否有 tool_call 的条件边函数
InjectedState / InjectedStore:工具参数注入标记

8.2 langgraph-supervisor

集中式多 Agent 调度:

from langgraph_supervisor import create_supervisor

supervisor = create_supervisor(
    agents=[research_agent, coder_agent, writer_agent],
    model=model,
    prompt="You are a supervisor. Route tasks to the right expert.",
).compile()

Supervisor 自动生成 handoff tool(transfer_to_<agent>),每个 subagent 都是一个 LangGraph 子图,主图负责路由决策。

8.3 langgraph-swarm

去中心化蜂群:没有中央 supervisor,每个 Agent 都能 handoff 给任何其他 Agent。

from langgraph_swarm import create_swarm, create_handoff_tool

handoff_to_coder = create_handoff_tool(agent_name="coder")
research_agent = create_agent(model, tools=[search, handoff_to_coder], ...)

swarm = create_swarm(
    agents=[research_agent, coder_agent, writer_agent],
    default_active_agent="research_agent",
).compile()

Active agent 由状态字段跟踪,handoff tool 切换 active agent 而不换 thread。

8.4 langgraph-bigtool

处理上千工具的 Agent:把 tool 存成向量索引,每步检索 top-k 给 LLM。

from langgraph_bigtool import create_agent as create_bigtool_agent
from langgraph.store.memory import InMemoryStore

store = InMemoryStore(index={"embed": embeddings, "dims": 1536})
# 注册 tools 到 store
for t in tools_10000:
    store.put(("tools",), t.name, {"description": t.description})

agent = create_bigtool_agent(model, tool_registry=tools_10000, store=store)

解决"把 1000 个工具 schema 全喂给 LLM"带来的 context 爆炸。

8.5 langgraph-codeact

Code-as-Action 模式:LLM 直接生成 Python 代码(而不是 JSON tool call),在沙箱里执行。适合数据分析、计算密集任务。

8.6 官方参考实现

项目	内容
open-deep-research	深度研究 Agent(多轮搜索 → 报告)
open_agent_platform	企业级 Agent 管理后台参考实现
executive-ai-assistant	邮件自动化 Agent
chat-langchain	LangChain 官方文档问答 Bot,RAG 参考实现
data-enrichment	数据增强 Agent 模板

全部在 github.com/langchain-ai/* 下,可 fork 作为起点。

9. LangMem

9.1 定位

构建在 langgraph.store.BaseStore 上的长期记忆 SDK,三类记忆:

类型	内容
Semantic	事实、用户偏好("我喜欢 Python")
Episodic	过往交互片段(用于 few-shot)
Procedural	学到的操作流程、system prompt 的自我调整

9.2 用法

from langmem import create_memory_manager, create_memory_store_manager
from langgraph.store.postgres import PostgresStore

store = PostgresStore.from_conn_string("postgresql://...")

# 自动提取记忆的工具
manager = create_memory_manager(
    model="anthropic:claude-sonnet-4-6",
    instructions="Extract user preferences and facts.",
    enable_inserts=True,
    enable_updates=True,
)

# 在 agent 里调用
memories = await manager.ainvoke({"messages": conversation})

# 存进 store
for m in memories:
    await store.aput(("users", user_id, "facts"), m.id, m.content)

9.3 与 create_agent 协作

from langmem import create_manage_memory_tool, create_search_memory_tool

agent = create_agent(
    model,
    tools=[
        create_manage_memory_tool(namespace=("memories", "{user_id}")),
        create_search_memory_tool(namespace=("memories", "{user_id}")),
    ],
    store=store,
)

这两个 tool 让 LLM 自己决定"该记什么、该查什么"。

10. Partner 包

10.1 模型 Provider

包	主要类
`langchain-openai`	`ChatOpenAI`, `AzureChatOpenAI`, `OpenAIEmbeddings`
`langchain-anthropic`	`ChatAnthropic`, prompt caching / text-editor / memory-tool middleware
`langchain-google-genai`	`ChatGoogleGenerativeAI`(v4 后统一 Dev API + Vertex)
`langchain-google-vertexai`	Vertex 专属能力(PaLM legacy、Discovery Engine)
`langchain-aws`	`ChatBedrockConverse`, Bedrock Agents, Kendra, Neptune
`langchain-ollama`	`ChatOllama`(本地)
`langchain-mistralai`	`ChatMistralAI`
`langchain-cohere`	`ChatCohere`, `CohereEmbeddings`, `CohereRerank`
`langchain-together`	Together.ai OSS 模型
`langchain-groq`	Groq 超高速推理
`langchain-fireworks`	Fireworks AI
`langchain-nvidia-ai-endpoints`	NVIDIA NIM
`langchain-huggingface`	HF Inference / TGI / 本地 transformers
`langchain-deepseek`	DeepSeek
`langchain-xai`	xAI Grok

10.2 向量库

包	场景
`langchain-chroma`	本地/嵌入式,开发首选
`langchain-pinecone`	托管 SaaS,规模大
`langchain-milvus`	OSS,K8s 友好
`langchain-qdrant`	OSS,Rust 高性能
`langchain-weaviate`	OSS,支持图+向量
`langchain-mongodb`	Atlas Vector Search
`langchain-elasticsearch`	已有 ES 栈
`langchain-postgres`	pgvector,事务+向量
`langchain-redis`	RediSearch
`langchain-astradb`	DataStax AstraDB

10.3 标准化

所有 partner 跑 standard-tests 一致性套件,确保 BaseChatModel / Embeddings / VectorStore 接口行为一致。你写的代码可以通过 init_chat_model("provider:model") 无缝切换。

11. Checkpointer 与 Store 实现

11.1 Checkpointer(thread 内持久化)

实现	包	场景
`InMemorySaver` / `MemorySaver`	`langgraph`	开发、单元测试
`SqliteSaver` / `AsyncSqliteSaver`	`langgraph-checkpoint-sqlite`	本地文件、单机 prod
`PostgresSaver` / `AsyncPostgresSaver`	`langgraph-checkpoint-postgres`	生产主流选择
`RedisSaver` / `AsyncRedisSaver`	`langgraph-checkpoint-redis`	低延迟、短生命周期 thread
`MongoDBSaver`	`langgraph-checkpoint-mongodb`	MongoDB 栈

所有 Checkpointer 实现 BaseCheckpointSaver:put / get_tuple / list / put_writes,支持跨 thread 时间旅行。

11.2 Store(跨 thread 长期记忆)

实现	场景
`InMemoryStore`	开发
`PostgresStore`	生产,支持 pgvector 语义搜索
`RedisStore`	低延迟键值记忆

Store 支持命名空间向量索引:

from langgraph.store.postgres import PostgresStore

store = PostgresStore.from_conn_string(
    "postgresql://...",
    index={"dims": 1536, "embed": embeddings, "fields": ["text"]},
)
await store.aput(("memories", user_id), "fact-1", {"text": "喜欢 Python"})
hits = await store.asearch(("memories", user_id), query="编程偏好", limit=3)

11.3 选型建议

需求	推荐
本地 POC	InMemory / Sqlite
中小生产(单 PG 集群)	PostgresSaver + PostgresStore
极低延迟 chatbot	RedisSaver + PostgresStore(冷热分离)
已有 Mongo 栈	MongoDBSaver
多区域	自建 Checkpointer(BaseCheckpointSaver 子类)

12. MCP:Model Context Protocol

12.1 定义

Model Context Protocol 是 Anthropic 于 2024 年底推出、2025 年迅速成为行业标准的工具协议。核心思想:

让任何工具 / 数据源以统一 JSON-RPC 协议暴露,LLM 应用通过 MCP client 动态发现与调用。

生态相当于"LLM 的 USB-C"——有 MCP server 的东西(GitHub、Slack、Notion、Postgres、文件系统、浏览器...)都能被任何支持 MCP 的 Agent 用。

12.2 `langchain-mcp-adapters`

LangChain / LangGraph 官方适配器:

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient(
    {
        "filesystem": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
            "transport": "stdio",
        },
        "github": {
            "url": "https://mcp.github.com/sse",
            "transport": "sse",
            "headers": {"Authorization": f"Bearer {token}"},
        },
    }
)

tools = await client.get_tools()   # list[BaseTool]

agent = create_agent(model, tools=tools)

就这么简单——MCP server 的每个 tool 都被包装成标准 BaseTool,LangChain 栈完全无感。

12.3 反向:把 Agent 暴露为 MCP server

from langchain_mcp_adapters.server import create_mcp_server

server = create_mcp_server(
    agent,
    name="my-research-agent",
    description="Deep research on any topic",
)
server.run(transport="stdio")

这样你的 Agent 能被 Claude Desktop、Cursor、其他 MCP client 直接调用。

12.4 MCP 生态

官方 servers:filesystem、github、slack、postgres、sqlite、puppeteer、memory、brave-search
社区 servers:Linear、Notion、Jira、Confluence、Stripe、Gmail、Google Drive、Figma...(hundreds)
hosted:Anthropic/OpenAI 等在推"远程 MCP server",无需本地 spawn

13. 前端 / UI 集成

13.1 CopilotKit

React 组件 + 后端桥,把 LangGraph Agent 嵌入 web 应用:

<CopilotSidebar> / <CopilotPopup>:开箱即用聊天 UI
<CopilotKit runtimeUrl="/api/copilotkit"> + CopilotRuntime(langGraphCloudEndpoint=...):接 LangGraph Platform
Generative UI:LLM 决定渲染什么 React 组件
Shared state:前端 React state 与 Agent state 双向同步
Human-in-the-loop:interrupt 自动渲染成按钮/表单

社区与 LangChain 官方合作紧密,文档有独立一章讲 CopilotKit。

13.2 assistant-ui

专为 LangGraph 设计的 React 组件库:

import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
import { Thread } from "@assistant-ui/react";

const runtime = useLangGraphRuntime({
  assistantId: "agent",
  threadId,
  stream: async (messages) => client.runs.stream(threadId, "agent", { input: { messages } }),
});

export default () => <Thread runtime={runtime} />;

比 CopilotKit 更轻,专注对话场景。

13.3 Chainlit

Python 原生的聊天 UI 框架,几行代码把 LangGraph agent 变 web app:

import chainlit as cl

@cl.on_message
async def on_message(msg: cl.Message):
    async for event in agent.astream_events({"messages": [...]}, version="v2"):
        if event["event"] == "on_chat_model_stream":
            await cl.Message(content=event["data"]["chunk"].content).send()

自带文件上传、Markdown 渲染、反馈按钮、LangSmith 集成。

13.4 Streamlit / Gradio

更通用的数据应用框架,也常用:

st.write_stream(chain.stream(...)) 一行流式渲染
gr.ChatInterface(fn=lambda m, h: agent.invoke(...)) 一行聊天机器人

适合内部工具 / demo;生产级 chat 推荐 CopilotKit / assistant-ui。

14. 评估框架生态

14.1 LangSmith Evaluators(一等公民)

from langsmith.evaluation import evaluate, LangChainStringEvaluator

results = evaluate(
    my_chain.invoke,
    data="triage-v1",
    evaluators=[
        LangChainStringEvaluator("qa", config={"llm": judge_model}),
        LangChainStringEvaluator("criteria", config={
            "criteria": "conciseness", "llm": judge_model,
        }),
        custom_evaluator,
    ],
    experiment_prefix="v1.2-prompt",
    metadata={"prompt_version": "1.2"},
)

LangSmith 自带的 evaluator 覆盖:QA、cot_qa、criteria、labeled_criteria、embedding_distance、string_distance、trajectory(agent 轨迹)、json_edit_distance。

14.2 RAGAS

RAG 专用评估库,指标学术化、覆盖全:

Faithfulness(回答是否忠于上下文)
Answer Relevancy
Context Precision / Recall
Context Entities Recall
Answer Correctness
Noise Sensitivity

from ragas import evaluate as ragas_eval
from ragas.metrics import faithfulness, answer_relevancy, context_precision

ragas_eval(dataset, metrics=[faithfulness, answer_relevancy, context_precision])

与 LangSmith 互补:RAGAS 出指标,LangSmith 做实验管理。

14.3 DeepEval

单测风格评估,pytest 集成:

from deepeval import assert_test
from deepeval.test_case import LLMTestCase
from deepeval.metrics import HallucinationMetric

def test_no_hallucination():
    case = LLMTestCase(input="...", actual_output="...", context=["..."])
    assert_test(case, [HallucinationMetric(threshold=0.3)])

适合"eval as test",CI 里直接跑。

14.4 promptfoo

YAML 驱动的 prompt 对比评估,面向 prompt engineer 多过开发者:

providers: [openai:gpt-5, anthropic:claude-sonnet-4-6]
prompts: [prompt_v1.txt, prompt_v2.txt]
tests:
  - vars: { question: "..." }
    assert:
      - type: contains
        value: "correct answer"
      - type: llm-rubric
        value: "应该礼貌且准确"

命令行跑、HTML 报告,非常适合 A/B prompt。

15. 可观测替代方案

不用 LangSmith 时的选择:

15.1 Langfuse

OSS + SaaS,接口与 LangSmith 非常像:

from langfuse.callback import CallbackHandler

handler = CallbackHandler(public_key="...", secret_key="...", host="https://cloud.langfuse.com")
chain.invoke({"q": "..."}, config={"callbacks": [handler]})

优势:完全开源、self-host 简单(docker compose up)。适合"不能把数据传第三方"的企业。

15.2 Arize Phoenix

专注 AI/LLM observability,本地 Jupyter 内嵌 UI:

import phoenix as px
from phoenix.trace.langchain import LangChainInstrumentor

px.launch_app()
LangChainInstrumentor().instrument()

强在:本地零配置启动 + ML team 熟悉 Arize 生态。

15.3 Helicone / OpenLLMetry / Traceloop

Helicone:代理模式,拦截 OpenAI/Anthropic API 流量,无需改代码。
OpenLLMetry:OpenTelemetry 标准扩展,接任意 OTEL 后端(Datadog / Honeycomb / Jaeger)。
Traceloop:OpenLLMetry 背后的公司,提供 SaaS。

适合已有 APM 体系,想把 LLM trace 并入同一平台。

15.4 选型速查

场景	推荐
最快上手、与 LangChain 最契合	LangSmith
数据不出内网、开源偏好	Langfuse
已有 Datadog/Honeycomb	OpenLLMetry
ML 团队 + 本地调试	Phoenix
只想监控 token 花费	Helicone

16. 检索增强:Reranker / Embeddings

16.1 Reranker

召回后的二阶段精排,几乎总是值得加:

服务	LangChain 包
Cohere Rerank(v3)	`langchain-cohere` → `CohereRerank`
Voyage Rerank	`langchain-voyageai`
Jina Reranker	`langchain-community`
FlashRank(本地)	`langchain-community` → `FlashrankRerank`
BGE-Reranker(HF)	通过 HF Inference 或自建

用法:

from langchain_cohere import CohereRerank
from langchain.retrievers import ContextualCompressionRetriever

base = vectorstore.as_retriever(search_kwargs={"k": 25})
reranker = CohereRerank(model="rerank-v3.5", top_n=5)
retriever = ContextualCompressionRetriever(
    base_compressor=reranker,
    base_retriever=base,
)

经验:k=25 粗召回 → rerank 选 top 5,质量提升最明显的一步。

16.2 高质量 Embeddings

Provider	包	亮点
OpenAI `text-embedding-3-large`	`langchain-openai`	默认首选,通用
Voyage `voyage-3-large`	`langchain-voyageai`	专业领域(code / finance / law 有专版)
Cohere `embed-v4`	`langchain-cohere`	多模态、多语言强
Jina	`langchain-community`	长文本窗口
BGE-M3 / GTE	`langchain-huggingface`	开源、自托管
Nomic	`langchain-nomic`	开源 + 专业版

17. 第三方工具聚合平台

17.1 Composio

1000+ 预集成 API 的 tool 平台(Gmail / Slack / GitHub / Jira / Salesforce / Hubspot...),内置 OAuth 处理:

from composio_langchain import ComposioToolSet, App

toolset = ComposioToolSet(api_key="...")
tools = toolset.get_tools(apps=[App.GITHUB, App.SLACK, App.GMAIL])

agent = create_agent(model, tools=tools)

最大价值:OAuth / token 刷新 / rate limit 全托管,你不用再写 GitHub App 登录。

17.2 Arcade

类似 Composio,侧重 tool 执行的权限控制 + 人机审批:

from langchain_arcade import ArcadeToolManager

manager = ArcadeToolManager(api_key="...")
tools = manager.get_tools(toolkits=["Google", "GitHub"])

# 带授权流
agent = create_agent(model, tools=tools)

用户 OAuth 流在 Arcade 的 UI 里完成,agent 代码不用处理。

17.3 Portia AI

专注"需要审批"的 Agent 动作——Portia 生成执行计划,高风险步骤(发邮件、付款)自动转人工审批,再交回 Agent 继续。

17.4 何时选它们 vs MCP

Composio / Arcade:SaaS,OAuth 集中管,适合 B2B Agent 接客户账号。
MCP:协议开放,自建 MCP server 完全自控,企业内部集成优选。
混合:外部 SaaS 走 Composio,内部系统走自建 MCP。

18. 典型生产栈组合

18.1 "标准 SaaS 栈"(最快路径)

前端:      Next.js + CopilotKit
部署:      LangGraph Platform (Cloud)
Agent:     langchain.create_agent + middleware
Memory:    PostgresSaver + PostgresStore(Platform 托管)
LLM:       langchain-openai + langchain-anthropic(fallback)
RAG:       langchain-pinecone + Cohere Rerank
Tools:     MCP(GitHub/Slack)+ Composio(Gmail)
可观测:    LangSmith Cloud
评估:      LangSmith Experiments + RAGAS
Prompt:    LangChain Hub

团队规模:1–5 人,最快 2 周上线。

18.2 "企业内网栈"(数据不出内网)

前端:      React + assistant-ui(内网 CDN)
部署:      LangGraph Platform Self-hosted Enterprise(K8s)
Agent:     langgraph StateGraph(自建,更灵活)
Memory:    自建 PG 集群 + PGVector
LLM:       Azure OpenAI + 自建 vLLM(Llama 3)
RAG:       langchain-elasticsearch + BGE-Reranker
Tools:     自建 MCP server 集群
可观测:    Langfuse self-hosted
评估:      DeepEval(CI)+ Langfuse datasets
Prompt:    Git 管理(不用 Hub)

团队规模:10+ 人,合规要求高。

18.3 "极简 OSS 栈"(学习 / 小产品)

前端:      Streamlit
部署:      单台 VPS + docker
Agent:     langchain.create_agent
Memory:    SqliteSaver
LLM:       Ollama(本地 Llama 3)+ Groq(快速推理)
RAG:       Chroma + Nomic embeddings + FlashRank(本地)
Tools:     @tool 装饰器自写
可观测:    Phoenix local
评估:      promptfoo

成本 < $50/月。

19. 选型速查表

19.1 按问题选工具

问题	答案
怎么看 Agent 内部发生了什么	LangSmith / Langfuse / Phoenix
怎么部署 Agent	LangGraph Platform;自建用 Platform self-host / FastAPI
怎么调试图	LangGraph Studio
怎么暴露链为 REST	LangServe(简单)/ Platform(复杂)
怎么管 prompt 版本	LangChain Hub
怎么写多 Agent	langgraph-supervisor / langgraph-swarm
1000+ 工具怎么办	langgraph-bigtool
Agent 要写代码	langgraph-codeact
怎么给 Agent 长期记忆	LangMem + BaseStore(PG / Redis)
怎么接第三方工具	MCP(自控)/ Composio / Arcade(SaaS)
怎么在 React 里嵌 Agent	CopilotKit / assistant-ui
怎么快速做聊天 UI	Chainlit
怎么评估 RAG	RAGAS + LangSmith
怎么做 CI eval	DeepEval / promptfoo
怎么提高检索质量	Cohere/Voyage Rerank + MMR + MultiQueryRetriever
怎么控制 prompt 费用	Anthropic cache middleware + OpenAI auto-cache
怎么持久化会话	PostgresSaver(生产)/ SqliteSaver(本地)
怎么多区域 HA	自建 Checkpointer on 分布式 DB

19.2 依赖安装速查

# 核心
pip install langchain langchain-core langgraph

# 常用 partner
pip install langchain-openai langchain-anthropic langchain-google-genai

# 部署
pip install langgraph-cli langsmith

# Checkpointer
pip install langgraph-checkpoint-postgres langgraph-checkpoint-sqlite
pip install langgraph-checkpoint-redis

# 预构建 Agent
pip install langgraph-supervisor langgraph-swarm langgraph-bigtool

# 记忆
pip install langmem

# MCP
pip install langchain-mcp-adapters

# 向量 / 检索
pip install langchain-chroma langchain-pinecone langchain-cohere

# UI(可选)
pip install chainlit
# npm install @copilotkit/react-ui @copilotkit/runtime
# npm install @assistant-ui/react @assistant-ui/react-langgraph

# 评估
pip install ragas deepeval
# npm install -g promptfoo

# 观测替代
pip install langfuse arize-phoenix openllmetry-instrumentation-langchain

19.3 每个套件的 github 入口

套件	地址
LangChain	github.com/langchain-a…
LangGraph	github.com/langchain-a…
LangSmith SDK	github.com/langchain-a…
LangServe	github.com/langchain-a…
LangChain CLI	github.com/langchain-a…
LangGraph CLI	github.com/langchain-a…
langgraph-supervisor	github.com/langchain-a…
langgraph-swarm	github.com/langchain-a…
langgraph-bigtool	github.com/langchain-a…
langgraph-codeact	github.com/langchain-a…
langchain-mcp-adapters	github.com/langchain-a…
LangMem	github.com/langchain-a…
CopilotKit	github.com/CopilotKit/…
assistant-ui	github.com/Yonom/assis…
Chainlit	github.com/Chainlit/ch…
Langfuse	github.com/langfuse/la…
Phoenix	github.com/Arize-ai/ph…
RAGAS	github.com/explodinggr…
DeepEval	github.com/confident-a…
promptfoo	github.com/promptfoo/p…
Composio	github.com/ComposioHQ/…
MCP 协议	github.com/modelcontex…
MCP servers	github.com/modelcontex…

结语

整个生态可以按"一句话心智模型"理解:

langchain-core 是协议,所有套件共享。
LangChain 做应用层封装(create_agent、middleware、chain)。
LangGraph 做执行运行时(StateGraph、Checkpointer、Interrupt)。
LangSmith 贯穿观测,零成本就该开。
Platform / Studio / CLI 是开发运维工具链。
Prebuilt / LangMem / MCP 是扩展点。
Partner / Composio / Arcade 是集成点。
CopilotKit / assistant-ui / Chainlit 是前端出口。
RAGAS / DeepEval / promptfoo 是质量闸门。

选型原则:协议遵循官方(core / MCP),实现按需替换。你可以随时把 LangSmith 换 Langfuse、把 PG 换 Redis、把 OpenAI 换本地 Llama——只要都通过 langchain-core 的接口,代码层几乎零改动。这就是"协议型"架构的红利。

LangChain / LangGraph 生态套件完全指南

目录