Arc 框架解析
1. 实现了 RAG 数据库

RAG 系统的完整组件
- EmbeddingsBuilder - 向量生成器
// 只负责将文档转换为向量 let embeddings = EmbeddingsBuilder::new(embedding_model.clone()) .documents(documents)? .build() .await?;作用:
- 接收原始文档
- 提取文本内容
- 生成向量嵌入
- 返回文档-向量对
- VectorStore - 向量存储
// 实际存储向量和文档的地方 let vector_store = InMemoryVectorStore::from_documents(embeddings);作用:
- 存储文档内容
- 存储向量表示
- 提供检索接口
- VectorStoreIndex - 向量索引
// 提供高效的向量检索能力 let index = vector_store.index(embedding_model);作用:
- 构建向量索引
- 提供相似度搜索
- 优化检索性能
完整的 RAG 流程
// 1. 准备文档
let documents = vec![
WordDefinition { /* ... */ },
WordDefinition { /* ... */ },
];
// 2. 生成向量嵌入
let embeddings = EmbeddingsBuilder::new(embedding_model.clone())
.documents(documents)?
.build()
.await?;
// 3. 创建向量存储
let vector_store = InMemoryVectorStore::from_documents(embeddings);
// 4. 创建检索索引
let index = vector_store.index(embedding_model);
// 5. 创建 RAG agent
let rag_agent = openai_client
.agent("gpt-4")
.preamble("System prompt...")
.dynamic_context(1, index) // 使用索引进行检索
.build();
各组件的职责
- EmbeddingsBuilder
pub struct EmbeddingsBuilder<M: EmbeddingModel, T: Embed> { model: M, documents: Vec<(T, Vec<String>)_, batch_size: Option<usize>, normalized: bool, }- 文档预处理
- 向量生成
- 批处理优化
- VectorStore
pub trait VectorStore { fn add_document(&mut self, doc: Document, embedding: Embedding); fn get_document(&self, id: &str) -> Option<&Document>; // ... }- 文档存储
- 向量存储
- 基本检索
- VectorStoreIndex
pub trait VectorStoreIndex: Send + Sync { async fn top_n<T>(&self, query: &str, n: usize) -> Result<Vec<(f64, String, T)>, VectorStoreError>; }- 向量检索
- 相似度计算
- 结果排序
总结
完整的 RAG 数据库需要:
- EmbeddingsBuilder - 向量生成
- VectorStore - 存储层
- VectorStoreIndex - 检索层
- Agent - 应用层
这些组件共同工作才构成了完整的 RAG 系统。
2. 支持Static Tool 和 Dynamic Tool
在 agent.rs 中,Agent 结构体定义了静态和动态工具:
pub struct Agent<M: CompletionModel> {
model: M,
preamble: String,
static_context: Vec<Document>,
static_tools: Vec<String>, // 静态工具名称列表
temperature: Option<f64>,
max_tokens: Option<u64>,
additional_params: Option<serde_json::Value>,
dynamic_context: Vec<(usize, Box<dyn VectorStoreIndexDyn>)_,
dynamic_tools: Vec<(usize, Box<dyn VectorStoreIndexDyn>)_, // 动态工具索引
tools: ToolSet, // 所有工具的集合
}
工具的处理主要在 completion 方法中:
impl<M: CompletionModel> Agent<M> {
async fn completion(
&self,
prompt: &str,
chat_history: Vec<Message>,
) -> Result<CompletionRequestBuilder<M>, PromptError> {
let mut builder = self.model.completion_request(prompt);
// 1. 添加系统 prompt
builder = builder.preamble(&self.preamble);
// 2. 添加静态工具
// 静态工具直接从 tools 中获取已注册的工具名称
for toolname in &self.static_tools {
if let Some(tool) = self.tools.get(toolname) {
builder = builder.tool(tool.definition(prompt.to_string()).await);
}
}
// 3. 添加动态工具
// 对每个动态工具索引
for (sample_size, index) in &self.dynamic_tools {
// 使用向量检索找到相关工具
let similar = index.top_n_ids(prompt, *sample_size).await?;
// 将找到的工具添加到 builder
for (_, toolname) in similar {
if let Some(tool) = self.tools.get(&toolname) {
builder = builder.tool(tool.definition(prompt.to_string()).await);
}
}
}
// 4. 设置其他参数
if let Some(temperature) = self.temperature {
builder = builder.temperature(temperature);
}
// ...
Ok(builder)
}
}
工具的注册是在 AgentBuilder 中完成的:
impl<M: CompletionModel> AgentBuilder<M> {
// 添加静态工具
pub fn tool(mut self, tool: impl Tool + 'static) -> Self {
let toolname = tool.name();
self.tools.add_tool(tool);
self.static_tools.push(toolname);
self
}
// 添加动态工具
pub fn dynamic_tools(
mut self,
sample: usize,
dynamic_tools: impl VectorStoreIndexDyn + 'static,
toolset: ToolSet,
) -> Self {
self.dynamic_tools.push((sample, Box::new(dynamic_tools)));
self.tools.add_tools(toolset);
self
}
}
主要区别:
- 静态工具
- 通过
tool()方法直接注册 - 工具名称保存在
static_tools列表中 - 每次请求都会包含在 prompt 中
- 不需要向量检索
- 通过
- 动态工具
- 通过
dynamic_tools()方法注册 - 需要提供向量索引和采样数量
- 基于用户输入进行向量检索
- 只有相关的工具会被包含在 prompt 中
- 通过
使用示例:
// 创建 Agent
let agent = openai_client
.agent("gpt-4")
.preamble("You are a helpful assistant")
// 添加静态工具
.tool(BasicTool::new())
// 添加动态工具
.dynamic_tools(2, tool_index, dynamic_toolset)
.build();
// 使用 Agent
let response = agent.prompt("Help me calculate something").await?;
这种设计允许:
- 核心工具始终可用(静态)
- 特定工具按需发现(动态)
- 通过向量检索实现智能工具选择
- 优化 prompt 长度,只包含相关工具
3. 支持 Dynamic Context 和 Static Context
在 Rig 框架中,static_context 和 dynamic_context 的区别类似于静态工具和动态工具的概念。让我们详细分析:
1. 在 Agent 结构体中的定义
pub struct Agent<M: CompletionModel> {
model: M,
preamble: String,
static_context: Vec<Document>, // 静态上下文文档
static_tools: Vec<String>,
// ...
dynamic_context: Vec<(usize, Box<dyn VectorStoreIndexDyn>)_, // 动态上下文索引
dynamic_tools: Vec<(usize, Box<dyn VectorStoreIndexDyn>)_,
tools: ToolSet,
}
2. 在 AgentBuilder 中的添加方法
impl<M: CompletionModel> AgentBuilder<M> {
// 添加静态上下文
pub fn context(mut self, doc: impl Into<String>) -> Self {
self.static_context.push(Document {
id: format!("doc_{}", self.static_context.len()),
text: doc.into(),
additional_props: HashMap::new(),
});
self
}
// 添加动态上下文
pub fn dynamic_context(
mut self,
sample: usize,
dynamic_context: impl VectorStoreIndexDyn + 'static,
) -> Self {
self.dynamic_context.push((sample, Box::new(dynamic_context)));
self
}
}
3. 主要区别
- 静态上下文 (static_context)
- 始终包含在每个请求中
- 直接作为文档存储
- 不需要向量检索
- 适用于基础/通用知识
- 通过
.context()方法添加
let agent = openai_client
.agent("gpt-4")
.context("This is a basic rule that always applies")
.dynamic_context(3, knowledge_base_index) // 每次检索3个最相关文档
.build();
- 动态上下文 (dynamic_context)
- 基于用户输入动态检索
- 存储在向量数据库中
- 需要向量相似度搜索
- 适用于大规模/特定知识库
- 通过
.dynamic_context()方法添加,需要指定采样数量
let agent = openai_client
.agent("gpt-4")
.dynamic_context(3, knowledge_base_index) // 每次检索3个最相关文档
.build();
4. 在请求处理中的使用
impl<M: CompletionModel> Agent<M> {
async fn completion(
&self,
prompt: &str,
chat_history: Vec<Message>,
) -> Result<CompletionRequestBuilder<M>, PromptError> {
let mut builder = self.model.completion_request(prompt);
// 添加静态上下文 - 直接包含所有文档
for doc in &self.static_context {
builder = builder.context(doc);
}
// 添加动态上下文 - 通过向量检索找到相关文档
for (sample_size, index) in &self.dynamic_context {
let similar = index.top_n_ids(prompt, *sample_size).await?;
for (_, doc_id) in similar {
if let Some(doc) = self.get_document(&doc_id) {
builder = builder.context(doc);
}
}
}
// ... 其他处理
Ok(builder)
}
}
5. 使用场景
- 静态上下文适用于:
- 系统规则和约束
- 基本指令和说明
- 始终需要的背景信息
- 数量较少的固定知识
- 动态上下文适用于:
- 大规模知识库
- 特定领域的专业知识
- 需要根据查询动态检索的信息
- 上下文相关的参考资料
6. 完整使用示例
// 创建向量存储和索引
let embeddings = EmbeddingsBuilder::new(embedding_model)
.documents(knowledge_base)?
.build()
.await?;
let vector_store = InMemoryVectorStore::from_documents(embeddings);
let index = vector_store.index(embedding_model);
// 创建 Agent
let agent = openai_client
.agent("gpt-4")
.preamble("You are a helpful assistant")
// 添加静态上下文
.context("Always be polite and professional")
.context("Follow these basic guidelines...")
// 添加动态上下文
.dynamic_context(3, index) // 每次检索3个最相关文档
.build();
这种设计的优点:
- 灵活性:可以同时使用固定和动态的上下文
- 效率:只检索相关的动态上下文
- 可扩展性:支持大规模知识库
- 智能性:基于语义相似度的上下文检索
这种机制让 Agent 能够在保持基本行为准则的同时,根据具体查询提供相关的专业知识。
4. Pipeline
Pipeline 模块的设计采用了操作符组合模式,这种架构设计主要是为了支持灵活的数据处理流程。让我详细解释这个架构:
1. 核心抽象
- 基础操作 Trait (Op)
pub trait Op: Send + Sync { type Input: Send + Sync; type Output: Send + Sync; fn call(&self, input: Self::Input) -> impl Future<Output = Self::Output> + Send; } - 可失败操作 Trait (TryOp)
pub trait TryOp: Send + Sync { type Input: Send + Sync; type Output: Send + Sync; type Error: Send + Sync; fn try_call(&self, input: Self::Input) -> impl Future<Output = Result<Self::Output, Self::Error>> + Send; }
2. 架构组件
- 基本操作符 (op.rs) ```rust // 映射操作 pub struct Map<Op, F> { op: Op, f: F, }
// 链式操作 pub struct Chain<Op1, Op2> { op1: Op1, op2: Op2, }
2. **并行操作 (parallel.rs)**
```rust
pub struct Parallel<Op1, Op2> {
op1: Op1,
op2: Op2,
}
- 条件操作 (conditional.rs)
pub struct Conditional<T, Ops> { ops: Ops, _t: PhantomData<T>, }
3. 设计原因
- 组合性 (Composability)
// 可以灵活组合不同操作 let pipeline = pipeline::new() .map(preprocess) // 预处理 .then(validate) // 验证 .and_then(async_process) // 异步处理 .map_err(handle_error); // 错误处理 - 并行处理
let pipeline = pipeline::new() .chain(parallel!( text_process, // 文本处理 image_process, // 图像处理 metadata_process // 元数据处理 )); - 类型安全
// 编译时类型检查 let pipeline: Pipeline<String, Vec<u8>> = pipeline::new() .map(|s: String| s.into_bytes()) .map(|v: Vec<u8>| process_bytes(v));
4. 实际应用场景
- RAG 流水线
let rag_pipeline = pipeline::new() // 并行执行查询和文档检索 .chain(parallel!( passthrough(), // 保持原始查询 lookup::<_, _, Document>(index, 5) // 检索相关文档 )) // 组合查询和文档 .map(|(query, docs)| format!("Query: {query}\nContext: {docs}")) // 发送到 LLM .prompt(llm_model); - 数据处理流水线
let process_pipeline = pipeline::new() .map(parse_input) // 解析输入 .and_then(validate_data) // 验证数据 .map_ok(transform_data) // 转换数据 .or_else(handle_error); // 错误处理
5. 为什么选择这种架构
- 灵活性
- 支持同步和异步操作
- 可以动态构建处理流程
- 易于添加新的操作类型
- 可维护性
// 每个操作都是独立的,易于测试和维护 #[cfg(test)] mod tests { #[test] fn test_map_operation() { let op = map(|x: i32| x + 1); assert_eq!(op.call(1).await, 2); } } - 性能考虑
- 支持并行处理
- 最小化内存拷贝
- 异步操作优化
- 错误处理
// 完整的错误处理链 let pipeline = pipeline::new() .map(|x| Ok::<_, Error>(x + 1)) .and_then(validate) .or_else(|error| async move { log::error!("Error: {}", e); Err(e) });
在 Agent 中,Pipeline 主要用于构建复杂的 RAG (Retrieval Augmented Generation) 和数据处理流程。让我通过实际场景来说明:
1. RAG 场景
// 基于 rag.rs 示例
let rag_pipeline = pipeline::new()
// 1. 并行执行:保留原始查询 + 检索相关文档
.chain(parallel!(
passthrough(), // 保持原始用户查询
agent_ops::lookup::<_, _, Document>( // 从向量库检索文档
index, // 向量索引
5 // 检索前5个最相关文档
)
))
// 2. 组合查询和上下文
.map(|(query, docs)| {
format!(
"User Query: {}\n\nRelevant Context:\n{}",
query,
docs.iter()
.map(|doc| doc.text.clone())
.collect::<Vec<_>>()
.join("\n")
)
})
// 3. 发送到 LLM 生成回答
.prompt(llm_model);
2. 多模型协作场景
let multi_model_pipeline = pipeline::new()
// 1. 并行处理不同类型的输入
.chain(parallel!(
// 文本处理分支
text_processor
.map(process_text)
.prompt(text_model),
// 图像处理分支
image_processor
.map(process_image)
.prompt(vision_model)
))
// 2. 合并结果
.map(|(text_result, image_result)| {
format!("Text Analysis: {}\nImage Analysis: {}",
text_result, image_result)
})
// 3. 最终总结
.prompt(summary_model);
3. 信息提取场景
// 基于 multi_extract.rs
let extraction_pipeline = pipeline::new()
// 1. 文档预处理
.map(preprocess_document)
// 2. 并行提取不同类型的信息
.chain(parallel!(
extract::<PersonInfo>(person_extractor),
extract::<LocationInfo>(location_extractor),
extract::<DateInfo>(date_extractor)
))
// 3. 合并提取结果
.map(|(persons, locations, dates)| {
DocumentMetadata {
persons,
locations,
dates
}
});
4. 工具调用场景
let tool_pipeline = pipeline::new()
// 1. 分析用户意图
.map(analyze_intent)
// 2. 条件分支处理不同工具
.chain(conditional!(Intent,
Calculate => calculator_tool,
Search => search_tool,
Translate => translation_tool
))
// 3. 格式化结果
.map(format_tool_response);
5. 错误处理和重试场景
let robust_pipeline = pipeline::new()
.map(initial_process)
.and_then(|input| async move {
// 带重试的 API 调用
retry::retry(ExponentialBackoff::default(), || async {
api_call(input).await
}).await
})
.or_else(|error| async move {
// 错误处理和降级策略
fallback_process(error).await
});
6. 动态上下文管理
let context_aware_pipeline = pipeline::new()
// 1. 并行获取各种上下文
.chain(parallel!(
get_user_context,
get_conversation_history,
get_relevant_documents
))
// 2. 合并上下文
.map(|(user, history, docs)| {
Context::new()
.with_user(user)
.with_history(history)
.with_documents(docs)
})
// 3. 使用上下文生成响应
.prompt(context_aware_model);
优势
- 模块化
- 每个处理步骤都是独立的
- 易于测试和维护
- 支持代码重用
- 灵活性
- 可以动态组合不同的处理步骤
- 支持条件分支和并行处理
- 易于添加新功能
- 可靠性
- 内置错误处理
- 支持重试机制
- 可以实现降级策略
- 性能
- 支持并行处理
- 异步操作优化
- 资源利用效率高
这种 Pipeline 架构让 Agent 能够处理复杂的任务流程,同时保持代码的清晰性和可维护性。
5.Extractor
Extractor 是 Rig 框架中用于从非结构化文本中提取结构化数据的组件。让我详细解析:
1. Extractor 的作用
// 1. 定义要提取的结构化数据格式
#[derive(Debug, Deserialize, JsonSchema, Serialize)]
struct Person {
first_name: Option<String>,
last_name: Option<String>,
job: Option<String>,
}
// 2. 创建和使用提取器
let data_extractor = openai_client.extractor::<Person>("gpt-4").build();
let person = data_extractor
.extract("Hello my name is John Doe! I am a software engineer.")
.await?;
主要功能:
- 将非结构化文本转换为结构化数据
- 自动生成 schema 并指导 LLM 提取
- 处理提取结果的序列化/反序列化
2. 实现原理
- Extractor 结构
pub struct Extractor<T, M: CompletionModel> { agent: Agent<M>, _t: PhantomData<T>, } - 构建过程
impl<T: JsonSchema + for<'a> Deserialize<'a> + Serialize + Send + Sync> ExtractorBuilder<T, M> { pub fn build(self) -> Extractor<T, M> { // 1. 获取类型的 JSON Schema let schema = schema_for!(T); // 2. 构建提示模板 let preamble = format!( "Extract structured data according to this JSON schema:\n{}\n\n\ Return only the JSON data without any additional text.", serde_json::to_string_pretty(&schema).unwrap() ); // 3. 创建专门的提取 agent let agent = self.agent_builder .preamble(&preamble) .build(); Extractor { agent, _t: PhantomData, } } } - 提取过程
impl<T: for<'a> Deserialize<'a>, M: CompletionModel> Extractor<T, M> { pub async fn extract(&self, text: &str) -> Result<T, ExtractionError> { // 1. 发送提取请求给 LLM let response = self.agent.prompt(text).await?; // 2. 解析 JSON 响应 let result: T = serde_json::from_str(&response)?; Ok(result) } }
3. 具体应用场景
- 个人信息提取
```rust
#[derive(Deserialize, JsonSchema)]
struct PersonInfo {
name: Option
, age: Option , email: Option , occupation: Option , }
// 从简历文本中提取信息 let info = extractor .extract(“John Doe, 30 years old, john@email.com, Senior Developer”) .await?;
2. **商品信息提取**
```rust
#[derive(Deserialize, JsonSchema)]
struct ProductInfo {
name: String,
price: f64,
description: Option<String>,
specifications: HashMap<String, String>,
}
// 从产品描述中提取信息
let product = extractor
.extract("iPhone 15, $999, Latest smartphone with A16 chip...")
.await?;
- 事件信息提取
```rust
#[derive(Deserialize, JsonSchema)]
struct EventInfo {
title: String,
date: String,
location: Option
, participants: Vec , }
// 从会议记录中提取信息 let event = extractor .extract(“Team meeting on 2024-03-15 at HQ, with Alice, Bob, and Carol”) .await?;
4. **文档元数据提取**
```rust
#[derive(Deserialize, JsonSchema)]
struct DocumentMetadata {
title: String,
authors: Vec<String>,
publication_date: Option<String>,
keywords: Vec<String>,
}
// 从学术论文中提取元数据
let metadata = extractor
.extract("Title: AI in 2024, Authors: Smith, J., Jones, K...")
.await?;
4. 优点
- 类型安全
- 使用 Rust 的类型系统
- 编译时验证
- 自动生成 schema
- 灵活性
- 支持复杂的数据结构
- 可选字段处理
- 嵌套对象支持
- 易用性
- 声明式数据结构
- 自动处理序列化
- 清晰的错误处理
- 可扩展性
- 支持自定义数据类型
- 可以添加验证逻辑
- 集成其他处理步骤
5. 最佳实践
- 字段定义
#[derive(Deserialize, JsonSchema)] struct Data { // 使用 Option 处理可选字段 optional_field: Option<String>, // 添加字段文档 #[schemars(description = "User's age in years")] age: u8, // 使用合适的类型 timestamp: chrono::DateTime<chrono::Utc>, } - 错误处理
match extractor.extract(text).await { Ok(data) => process_data(data), Err(ExtractionError::JsonError(e)) => handle_json_error(e), Err(ExtractionError::LLMError(e)) => handle_llm_error(e), Err(e) => handle_other_error(e), }
Extractor 是一个强大的工具,特别适合需要从非结构化文本中提取结构化信息的场景。