langchainrust：用 Rust 构建 LLM 应用的全功能框架（附 6 个实战）

langchainrust 是 LangChain 的 Rust 实现，一套覆盖 LLM 调用、Agent、工具、记忆、Chain、RAG、LangGraph、MCP、安全护栏的完整框架。本文面向初次接触的开发者，讲清楚它能做什么、怎么用，并给出 6 个可运行的实战示例。

---

一、langchainrust 是什么

langchainrust 就是：调模型、写 Agent、挂工具、做 RAG、管记忆、编排工作流。

为什么用 Rust 重新做一遍？

• 性能：无 GIL，异步并发天然，适合高吞吐的 Agent / RAG 服务。
• 类型安全：工具入参、结构化输出、Chain 拼接都在编译期检查。
• 部署简单：编译成单个二进制，无运行时依赖，适合内网/边缘部署。

支持的模型 Provider：OpenAI、Ollama、DeepSeek、Moonshot（Kimi）、通义千问、智谱 ChatGLM、Anthropic Claude、Google Gemini。

---

二、功能版图

板块	能力
LLM	OpenAI / Ollama / DeepSeek / Moonshot / Qwen / 智谱 / Anthropic / Gemini，支持流式
Agent	ReActAgent、FunctionCallingAgent、Plan-Execute、Handoffs（多 Agent 交接）、Streaming Tool Calls
工具	Calculator / DateTime / Math / URLFetch / Wikipedia / PythonREPL / DuckDuckGo / HTTPTool / FileTool / SQLTool，+ MCP 协议接入任意外部工具
记忆	Buffer / Window / Summary / SummaryBuffer，+ MongoDB 持久化
Chain	LLMChain / Sequential / Conversation / Router / RetrievalQA，+ Stuff/Refine/MapReduce/MapRerank 文档链
检索	向量检索 / BM25 / 混合检索 / MultiQuery / HyDE / Reranking
向量库	InMemory / Qdrant / MongoDB / Redis / SQLite / Chroma / PGVector / Pinecone
LangGraph	StateGraph / Checkpointer / 中断恢复 / 子图 / 并行执行
安全	Guardrails（输入/输出双向护栏）
可观测	Callbacks / LangSmith 追踪 / Token 计数 / 成本估算
多模态	Vision（图片理解）
会话	Sessions（多轮对话生命周期管理）
文档加载	Text / JSON / Markdown / PDF / CSV / HTML

---

三、安装

langchainrust = "0.3.0"

默认零重依赖，按需开启 feature：

feature	作用
sqlite-storage	SQLite 存储 + SQLTool
pgvector-storage	PGVector 向量库（需自配 sqlx/pgvector 依赖）
qdrant-integration	Qdrant 向量库
mongodb-persistence	MongoDB 持久化
redis-storage	Redis 存储

# 开启 SQLite 工具 + Qdrant
langchainrust = { version = "0.3.0", features = ["sqlite-storage", "qdrant-integration"] }

---

四、实战：6 个核心场景

1. LLM 调用（多 Provider）

最基础的用法：构造消息、调用模型。OpenAIConfig::default() 会从 OPENAI_API_KEY 环境变量读取密钥。

use langchainrust::{OpenAIChat, OpenAIConfig, Message};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let llm = OpenAIChat::new(OpenAIConfig::default());

    let messages = vec![
        Message::system("你是一个简洁的助手"),
        Message::human("用一句话解释什么是 RAG"),
    ];

    let resp = llm.chat(messages, None).await?;
    println!("{}", resp.content);
    Ok(())
}

要点：

• 消息用 Message::system/human/ai 构造，chat 返回的 LLMResult 含 content 和 token_usage。
• DeepSeek / Moonshot / Qwen / 智谱走 OpenAI 兼容接口，Anthropic / Gemini 走原生 API，Ollama 跑本地模型——切换 Provider 只需换一个 Chat 类型。
• 也支持 stream_chat 流式输出，逐 token 返回。

---

2. Agent + 工具调用

Agent 的核心是让 LLM 自主决定调用哪个工具。langchainrust 的 FunctionCallingAgent 用模型原生 function calling（不靠文本解析），更可靠。

use langchainrust::{
    OpenAIChat, OpenAIConfig, BaseTool, BaseAgent,
    Calculator, URLFetchTool,
    FunctionCallingAgent, AgentExecutor,
};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let llm = OpenAIChat::new(OpenAIConfig::default());

    // 准备工具：计算器 + 网页抓取
    let tools: Vec<Arc<dyn BaseTool>> = vec![
        Arc::new(Calculator::new()) as Arc<dyn BaseTool>,
        Arc::new(URLFetchTool::new()) as Arc<dyn BaseTool>,
    ];

    // FunctionCallingAgent：第三参是 system prompt（可选）
    let agent = FunctionCallingAgent::new(llm, tools.clone(), None);
    let executor = AgentExecutor::new(
        Arc::new(agent) as Arc<dyn BaseAgent>,
        tools,
    ).with_max_iterations(10);

    // Agent 会自己决定先抓汇率、再算账
    let answer = executor
        .invoke("查一下当前美元对人民币汇率，计算 100 美元是多少人民币".to_string())
        .await?;
    println!("{answer}");
    Ok(())
}

要点：

• 所有工具实现 BaseTool trait（name/description/args_schema/run），用 Arc<dyn BaseTool> 装箱。
• AgentExecutor 控制迭代上限（.with_max_iterations），防止 Agent 死循环。
• 内置工具开箱即用；自定义工具实现 BaseTool 即可，或用 Tool trait 获得类型安全的入参/出参。

---

3. RAG 检索问答

RAG（检索增强生成）是 LLM 应用的高频场景：先检索相关文档，再让 LLM 基于上下文作答。RetrievalQA 把整条流水线封装成一行 query()。

use langchainrust::{
    OpenAIChat, OpenAIConfig,
    OpenAIEmbeddings, OpenAIEmbeddingsConfig, Embeddings,
    InMemoryVectorStore, VectorStore, Document,
    SimilarityRetriever, RetrieverTrait, RetrievalQA,
};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let llm = OpenAIChat::new(OpenAIConfig::default());

    // 1. 嵌入模型 + 向量库 + 检索器
    let embeddings: Arc<dyn Embeddings> =
        Arc::new(OpenAIEmbeddings::new(OpenAIEmbeddingsConfig::default()));
    let store: Arc<dyn VectorStore> = Arc::new(InMemoryVectorStore::new());
    let retriever: Arc<dyn RetrieverTrait> =
        Arc::new(SimilarityRetriever::new(store, embeddings));

    // 2. 灌入知识库
    retriever.add_documents(vec![
        Document::new("langchainrust 是 LangChain 的 Rust 实现，支持 Agent、工具、RAG 等。"),
        Document::new("FunctionCallingAgent 使用模型原生 function calling，不依赖文本解析。"),
        Document::new("RetrievalQA 封装了检索 + 组装 prompt + 生成 的完整 RAG 流程。"),
    ]).await?;

    // 3. 一行问答
    let qa = RetrievalQA::new(llm, retriever).with_k(3);
    let answer = qa.query("langchainrust 的 FunctionCallingAgent 有什么特点？").await?;
    println!("{answer}");

    // 想拿到来源文档？用 query_with_sources
    // let (answer, sources) = qa.query_with_sources("...").await?;
    Ok(())
}

要点：

• 三件套：Embeddings（向量化）+ VectorStore（存向量）+ SimilarityRetriever（检索）。
• InMemoryVectorStore 适合开发；生产可换 Qdrant / PGVector / Pinecone（都实现了 VectorStore trait，改一行即可）。
• RetrievalQA 自动完成：检索 → 拼 prompt（上下文+问题）→ LLM 生成。.with_k(n) 控制检索条数，.with_return_source_documents(true) 返回来源。
• 除向量检索外，还支持 BM25、混合检索、MultiQuery、HyDE、Reranking，可按需替换 retriever。

---

4. MCP 协议接入：一行把外部工具接进 Agent

MCP（Model Context Protocol）是 Anthropic 推出的工具协议标准，生态里有大量现成 MCP Server（文件系统、数据库、浏览器……）。langchainrust 内置 MCP Client，as_tools() 一行就能把某个 MCP Server 的全部工具变成 Agent 可用的 BaseTool。

use langchainrust::mcp::{MCPClient, MCPConfig};
use langchainrust::{
    OpenAIChat, OpenAIConfig, BaseTool, BaseAgent,
    FunctionCallingAgent, AgentExecutor,
};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 连接文件系统 MCP Server（需本地有 npx）
    let config = MCPConfig::stdio(
        "npx",
        vec!["@anthropic/mcp-server-filesystem".into(), "/tmp".into()],
    );
    let client = MCPClient::connect(config).await?;

    // 拉取工具清单
    let tools = client.list_tools().await?;
    println!("MCP 工具: {:?}", tools.iter().map(|t| &t.name).collect::<Vec<_>>());

    // 一键转为 BaseTool 列表，直接接入 Agent
    let mcp_tools = client.as_tools().await;

    let llm = OpenAIChat::new(OpenAIConfig::default());
    let agent = FunctionCallingAgent::new(llm, mcp_tools.clone(), None);
    let executor = AgentExecutor::new(
        Arc::new(agent) as Arc<dyn BaseAgent>,
        mcp_tools,
    );

    let answer = executor.invoke("读取 /tmp/notes.txt 的内容并总结".to_string()).await?;
    println!("{answer}");
    Ok(())
}

要点：

• 支持 Stdio（启动子进程）和 SSE（HTTP）两种传输。
• as_tools() 是最简入口：先 list_tools() 填充工具表，再调用即可拿到 Vec<Arc<dyn BaseTool>>，与原生工具无差别。
• 也可 client.call_tool(name, args) 手动调用单个工具，返回 MCPToolResult，用 .text() 取文本。
• 这意味着 langchainrust 的 Agent 能直接复用整个 MCP 工具生态，不用自己重写工具。

---

5. Guardrails 安全护栏：输入/输出双向拦截

生产环境的 Agent 必须拦住恶意输入和敏感输出。GuardedAgent 在 invoke 时先验输入、再执行 Agent、最后验输出。内置校验器：MaxLengthGuardrail（输入长度）、ForbiddenWordsGuardrail（禁用词）、SensitiveInfoGuardrail（API Key / 邮箱 / 信用卡 / 敏感关键词）。

下面这个例子不需要 API Key——输入超长会在调用 Agent 前被拦截，根本不触网：

use langchainrust::{
    GuardedAgent, GuardrailsConfig, GuardrailError,
    MaxLengthGuardrail, SensitiveInfoGuardrail,
    FunctionCallingAgent, AgentExecutor, BaseAgent,
    OpenAIChat, OpenAIConfig,
};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let llm = OpenAIChat::new(OpenAIConfig::default());
    let agent = FunctionCallingAgent::new(llm, vec![], None);
    let executor = Arc::new(AgentExecutor::new(
        Arc::new(agent) as Arc<dyn BaseAgent>,
        vec![],
    ));

    // 输入限 50 字符；输出拦截敏感信息
    let config = GuardrailsConfig::new()
        .with_input(Arc::new(MaxLengthGuardrail::new(50)) as Arc<_>)
        .with_output(Arc::new(SensitiveInfoGuardrail::new()) as Arc<_>);

    let mut guarded = GuardedAgent::new(executor, config);

    // 这条输入超长，会在进入 Agent 前被 Block，不消耗任何 token
    let long_input = "x".repeat(100);
    match guarded.invoke(long_input).await {
        Err(GuardrailError::Blocked(reason)) => {
            println!("已拦截: {reason}");
            println!("违规记录数: {}", guarded.violations().len());
        }
        other => println!("其它结果: {other:?}"),
    }
    Ok(())
}

要点：

• 流程是 验输入 → Agent → 验输出，输入被拦则 Agent 不执行（省钱、防注入）。
• SensitiveInfoGuardrail::new() 内置 OpenAI Key / 邮箱 / 信用卡正则 + password/token/secret 等关键词，可用 .with_keywords(vec![...]) 追加。
• 自定义规则：实现 InputGuardrail / OutputGuardrail trait 即可。
• guarded.violations() 取回违规记录，便于审计。

---

6. 多模态 Vision：让模型看图

Message 支持 images 字段，配合 ImageContent 可发送图片给支持 vision 的模型。

use langchainrust::{Message, ImageContent, OpenAIChat, OpenAIConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let llm = OpenAIChat::new(OpenAIConfig::default());

    // 单图（URL）
    let msg = Message::human_with_image(
        "请描述这张图片的内容",
        "https://example.com/photo.jpg",
    );

    // 多图 + base64 也可：
    // let msg = Message::human_with_images(
    //     "对比这两张图",
    //     vec![
    //         ImageContent::from_url("https://example.com/a.png"),
    //         ImageContent::from_base64("iVBORw0KGgo..."),
    //     ],
    // );

    let resp = llm.chat(vec![msg], None).await?;
    println!("{}", resp.content);
    Ok(())
}

要点：

• Message::human_with_image(text, url) 最简；多图用 human_with_images。
• 也可链式：Message::human("看图").with_image(ImageContent::from_url(...))。
• OpenAI 和 Ollama Vision 均已适配序列化。

---

五、更多能力

上面 6 个实战之外，langchainrust 还提供：

• Plan-Execute Agent：先规划完整计划、逐步执行、失败自动重规划，适合复杂多步任务。
• Handoffs：HandoffManager + HandoffTool，让一个 Agent 把任务移交给更擅长的另一个 Agent，实现多 Agent 协作。
• Streaming Tool Calls：StreamingFunctionCallingAgent::invoke_stream，工具调用过程流式返回，前端可实时渲染"正在调用 X 工具"。
• Sessions：SessionManager + 可插拔 SessionStore，封装多轮对话的创建/对话/归档/按用户查询，历史自动维护。
• Token 计数与成本估算：TiktokenCounter 估算 token、TokenTrackingLLM 追踪累计用量、ModelPricing 估算成本（纯本地，不需 API Key）。
• 记忆系统：Buffer / Window / Summary / SummaryBuffer 四种策略，+ MongoDB 持久化。
• LangGraph：图状工作流引擎，支持状态图、Checkpointer 持久化、中断恢复、子图嵌套、并行执行——适合复杂 Agent 编排。
• 扩展工具：HTTPTool（发请求）、FileTool（沙箱 + 扩展名白名单）、SQLTool（只读 + 表白名单，需 sqlite-storage）。
• 向量库：除 InMemory 外，支持 Qdrant / MongoDB / Redis / SQLite / Chroma / PGVector / Pinecone，统一 VectorStore trait。
• 文档加载：Text / JSON / Markdown / PDF / CSV / HTML 六种 Loader，接入 RAG 流水线。
• Output Parsers：Str / List / Json / Structured / Typed 五种解析器，把 LLM 输出转结构化数据。
• Callbacks / LangSmith：执行全生命周期追踪，对接 LangSmith 平台做可观测。

---

六、链接

• crates.io：https://crates.io/crates/langchainrust
• docs.rs：https://docs.rs/langchainrust/0.3.0
• GitHub：https://github.com/atliliw/langchainrust

langchainrust = "0.3.0"

langchainrust 把"搭 LLM 应用"的积木都备齐了：从最底层的 LLM 调用、工具、记忆，到 RAG、LangGraph 工作流，再到生产级的安全护栏、会话管理、成本可观测。如果你在用 Rust 做 AI 应用，值得试一试。欢迎试用与反馈。

---

本文代码基于 langchainrust 实际 API 编写。LLM 调用 / Agent / RAG / MCP / 多模态示例需要 OPENAI_API_KEY 环境变量（MCP 示例还需本地 MCP Server）；Guardrails 拦截示例为纯本地运行，无需任何 Key。