企业官网建设流程全解析

• AI Agent
• Agent 框架
• RAG
• 后端

导读

本文以 rig 官方 README 为骨架，系统讲解这个 Rust LLM 应用框架的核心理念、架构分层、快速上手路径与完整集成矩阵。读完你将掌握：如何在几行代码内通过统一接口接入 20+ 模型提供商与 10+ 向量数据库、如何理解rig-core（可移植契约层）与rig-agent（经典 Agent 运行时）的职责边界、如何用cassette特性实现免 API Key 的请求录制与回放，以及如何借助仓库源码与测试体系验证每个结论。

Rig 是什么

Rig 是一个用于构建**可扩展（scalable）、模块化（modular）、符合人体工程学（ergonomic）**的 LLM 应用的 Rust 库。它解决的核心痛点是：LLM 生态中模型提供商、向量数据库、工具协议碎片化严重，应用层代码往往被某个厂商的 SDK 绑定。Rig 通过一层"单一统一接口"（one singular unified interface）把这种复杂性收口，让开发者用最少的样板代码（minimal boilerplate）把 LLM 能力集成进应用。

仓库根目录的 Cargo.toml 中，这个库的自我描述是 "An opinionated library for building LLM powered applications"——它有明确的设计主张，而不是一个什么都收的中立适配层。

核心特性一览

根据 README.md 与仓库源码，Rig 的特性可以归纳为以下几组：

• Agentic 工作流：支持多轮（multi-turn）流式对话与提示词编排，内置经典 Agent 运行时（默认启用），并提供可序列化的AgentRun状态机（见下文"运行时选择"）。
• 统一模型接口：20+ 模型提供商全部收敛到同一套Model契约之下；10+ 向量存储集成共享同一套VectorStoreIndex契约。
• 全能力覆盖：不仅支持 completion 与 embedding 工作流，还覆盖转录（transcription）、音频生成（audio generation）与图像生成（image generation）三类多模态能力。
• 可观测性：完整兼容 GenAI Semantic Convention。
• 浏览器 WASM 支持：可移植核心（portable core）与经典运行时支持wasm32-unknown-unknown，无需任何 wasm feature flag（详见 crates/rig-agent/README.md）；WASI 不支持，rig-rmcp/MCP 仅限原生平台。

需要提醒的是，README 顶部有一则显著的WARNING：项目处于快速迭代期，未来更新将包含破坏性变更（breaking changes），Rig 会随演进标注变更并给出迁移路径。计划用于生产环境时应关注 CHANGELOG.md 与 MIGRATING.md。

运行时选择：rig-core 与 rig-agent 的职责分层

Rig 的架构精髓在于把"与具体提供商相关的可移植契约"和"Agent 编排逻辑"彻底分离，这是理解整个框架的钥匙。

rig-core：提供者无关的契约层

crates/rig-core/src/lib.rs 的模块头注释定义得很清楚：rig-core包含**提供者中立（provider-neutral）**的消息模型、completion 模型、可移植与上下文相关的工具契约、memory 与向量存储契约，以及内置的提供商映射。具体来说：

• Model/DynModel：一个Model把"端点线（wire）"绑定到"传输层（transport）"；DynModel是擦除到操作层面的模型，便于消费者持有。
• providers模块：从源码 crates/rig-core/src/providers/mod.rs 可以看到内置客户端的完整清单——anthropic、azure、chatgpt、cohere、copilot、deepseek、gemini、groq、huggingface、llamacpp、mistral、ollama、openai、openrouter、perplexity、together、venice、voyageai、xai 等。每个客户端（如openai::OpenAI）持有配置与传输，负责构建它服务的模型。
• driver、operation、serve、effect、tool、memory、vector_store等模块提供底层运行契约。

rig-agent：经典 Agent 运行时

rig-agent包含经典 builder、prompt/streaming trait、类型化 hooks、实时工具注册表（live tool registry）、抽取（extraction）以及可序列化的AgentRun状态机。该运行时默认启用。从源码结构（crates/rig-agent/src/agent）可以看到 builder、drive、engine、hook、runner、streaming、telemetry 等完整实现模块。

根 facade：rig的再导出

根包 src/lib.rs 是整仓库的 facade（门面），把rig_core再导出为rig::...路径，并在默认agent特性下把rig_agent的运行时再导出为rig::agent。因此大多数代码只需要依赖rig一个 crate。README 明确指出：

• 需要按特性（feature-gated）访问伴生 crate 时，使用根rigfacade；
• 只需要核心提供商抽象时，可以直接使用rig-core。

两个 Agent 运行时（经典运行时与 ECS 运行时）共享同一个 adapter 来执行Model。ECS 检查点（checkpoint）保留的是执行状态与 handler 描述符，不是提供商的启动配方；恢复时会对照原始保存的契约显式校验完整 handler 集合，或接受有意的替换。效果回放（effect replay）使用已记录的 handler，不需要现场构造提供商——详细契约见 crates/rig-ecs/CONTRACT.md。

快速开始

README 给出的依赖添加方式有两种，按需选择：

cargo add rig # or: cargo add rig-core

其中cargo add rig会启用默认特性。查看 Cargo.toml 的[features]段可以确认默认集是["rig-core/default", "reqwest", "agent", "derive", "rustls"]——即内置 reqwest 传输、经典 Agent 运行时、rig_tool派生宏与 rustls TLS 栈。

仓库还提供了丰富的可运行示例，见 examples 目录（每个示例是一个独立 Cargo 包）以及各 crate 自己的examples目录；提供商测试覆盖与 cassette 命令说明见 tests/README.md。

最小可用示例

README 给出了一个基于 OpenAI 的完整示例，这是理解 Rig 用法的最佳起点：

use rig::prelude::*; use rig::providers::openai::{self, OpenAI}; #[tokio::main] async fn main() -> Result<(), anyhow::Error> { // The client reads `OPENAI_API_KEY` and builds the models it serves. let model = OpenAI::from_env()?.completion(openai::GPT_5_2); let comedian_agent = AgentBuilder::new(model) .preamble("You are a comedian here to entertain the user using humour and jokes.") .build(); // Prompt the agent and print the response let response = comedian_agent.prompt("Entertain me!").await?; println!("{}", response.output); Ok(()) }

逐行解读这条调用链：

1. OpenAI::from_env()?：读取OPENAI_API_KEY环境变量构造客户端。根据 src/lib.rs 中reqwest特性的注释，未显式指定传输的提供商客户端（OpenAI::from_env()）会通过内置的共享 reqwest 客户端发送请求；with_http则可为其他HttpClientExt挂载自定义客户端。
2. .completion(openai::GPT_5_2)：从客户端构建一个 completion 模型，模型标识符是rig-core内置提供商映射的一部分。
3. AgentBuilder::new(model)：把模型注册为标签default（builder 源码见 crates/rig-agent/src/agent/builder.rs 中的AgentBuilder::new，它内部调用named_model("default", model)）。
4. .preamble(...)：设置系统提示词（system prompt）。
5. .build()：在构建期完成所有 handler 注册——默认模型、工具、memory、检索索引等都会在 agent 的 owner 标签下被铸造出稳定的 key（形如<owner>/model:<label>、<owner>/memory、<owner>/retrieve:context#<n>）。
6. .prompt(...)：阻塞式提示，返回TypedPromptResponse，其output字段携带模型回复文本。

README 特别提醒：使用#[tokio::main]需要启用 tokio 的macros和rt-multi-thread特性，或直接启用full：

cargo add tokio --features macros,rt-multi-thread

对应仓库中 examples/agent/src/main.rs 是一个去掉注释的最小可运行版本（examples目录每个包独立可跑，cargo run -p agent即可体验完整的 provider/client/agent/prompt 流程）。

AgentBuilder 的完整配置面

结合 builder 源码，AgentBuilder还提供以下高频配置项，足以覆盖大多数应用场景：

注意AgentBuilder使用 typestate 模式：NoToolConfig/WithBuilderTools/WithToolServerHandle三种状态在编译期约束"builder 自带工具"与"共享工具服务器"二选一，避免运行期歧义。

Recording and replay：免 API Key 的录制回放

这是 README 中一个非常实用的进阶能力。启用cassette特性后，rig::cassette::effect_log提供日志、录制器、回放 handler 与检查点（checkpoint）四种设施。核心用法：

1. 持有一个EffectLogRecorder句柄；
2. 通过AgentBuilder::record_to挂接它的 clone（见 builder 源码中record_to的签名——它要求Recorder + Send + Sync，因为回复观察者会跨总线的线程安全通道）；
3. 导入rig::cassette::agent::AgentReplayExt来给日志盖章或检查回放兼容性。

对于不需要传输层（transport-free）的消费者，README 建议直接依赖rig-cassette并关闭默认特性。其可选agent与ecs适配器彼此独立、也与原生http引擎相互独立，两个运行时都不依赖具体日志 crate。完整的依赖保证、ECS 回放安装与迁移路径见 crates/rig-cassette/README.md。

从 Cargo.toml 可以确认：cassette特性是["dep:rig-cassette"]，属于 opt-in；rig-cassette在 workspace 依赖中默认关闭特性（default-features = false），需要按需开启agent/ecs/http。

这一能力与仓库庞大的测试体系深度绑定：tests/README.md 描述了 cassette 优先（cassette-first）的测试方针——录制好的真实提供商流量是默认证据，通过RIG_PROVIDER_TEST_MODE=replay可以在零 API Key、零成本下回放 anthropic、bedrock、openai、gemini 等 18+ 个提供商的 cassette 测试套件；cargo xtask cassette record系列命令则管理录制、扫描敏感信息、审计 golden 与清理尝试账本。

支持的集成：一张特性矩阵

Rig 把每一个伴生 crate 都收敛为根 facade 的一个特性开关，示例配置：

rig = { version = "0.36.0", features = ["lancedb", "fastembed"] }

（当前仓库 workspace 版本为0.42.0，见 Cargo.toml 的[workspace.package]；以下表格为 README 原文继承。）

两点补充说明（README 原文要点）：

• rig::memory不需要memory特性即可使用，它包含核心会话记忆 trait 与从rig-core再导出的内存后端；开启features = ["memory"]才会把rig-memory伴生 crate 提供的可复用历史塑形（history-shaping）策略类型加入到同一模块。
• 另有一个关联 craterig-onchain-kit（Rig Onchain Kit），目标是让 Solana/EVM 与 Rig 的交互更易实现，属于额外功能扩展。

这些伴生模块在 facade 中的映射方式可以对照 src/lib.rs 里的companion_modules!宏——每个模块由对应特性门控，例如bedrock = rig_bedrock ["bedrock"]、fastembed由fastembed/fastembed-hf-hub/fastembed-ort-download-binaries三个特性中的任意一个启用。

生态与生产实践参考

README 还列举了一批实际使用 Rig 的公司与开源项目，涵盖医疗可视化工具（St Jude 的 proteinpaint）、终端编码 Agent（VT Code）、GPU 加速终端模拟器（Con）、去中心化 AI 网络（Dria）、事件驱动框架（Nethermind NINE）、Neon 的 app.build、AI 投资组合管理框架（Listen）、智能搜索（Cairnify）、视觉 AI 工作区（Ryzome）、安全个人 AI 助手（Ironclaw）、事件管理平台（ilert）等。这些是项目官方声明的使用者，可作为生态成熟度的参考，但本文不据此做任何"最强/最佳"之类的定性结论。

若你的团队也在生产中使用 Rig，可以在仓库提出 issue 把自己的名字加入该列表；更多项目、库、工具与文章收录在官方维护的 awesome-rig 清单中。

总结

Rig 的工程设计思路可以概括为三层：rig-core 定契约、rig-agent 定编排、根 facade 收口特性。上手路径是cargo add rig→AgentBuilder::new(model)→.build()→.prompt()；进阶路径是借助cassette特性把提供商交互固化为可回放的效果日志，再配合rig-ecs的检查点恢复实现可持久化的 Agent 执行。仓库根目录的 examples 目录（40+ 个可运行示例，覆盖多 Agent、RAG、工具调用、流式、OTel 观测、本地 Candle 推理、WASM 等场景）与 tests/README.md 描述的测试矩阵，是深入验证这些能力的首选入口。

• AI Agent
• Agent 框架
• RAG
• 后端