ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

基于 Cloudflare Vectorize 的 Rust 向量检索集成:rig-vectorize 使用指南与源码解析

基于 Cloudflare Vectorize 的 Rust 向量检索集成:rig-vectorize 使用指南与源码解析 AI AgentAgent 框架RAG后端【免费下载链接】rig⚙️ Build modular and scalable LLM Applications in Rust项目地址https://gitcode.com/GitHub_Trending/rig2/rig点击查看免费下载在 Rust 中构建模块化、可扩展的 LLM 应用时向量数据库是 RAG检索增强生成链路的关键一环。rig-vectorize是 Rig 框架官方提供的 Cloudflare Vectorize 向量存储集成它把 Cloudflare 全球分布式索引无缝接入 Rig 的VectorStoreIndex/InsertDocuments抽象使开发者可以用同一套 Rust 代码在向量检索、文档插入之间自由切换后端。阅读本文后你将掌握 rig-vectorize 的安装配置、端到端检索示例、元数据过滤器的能力边界、底层 HTTP 客户端的实现原理以及如何运行真实索引上的集成测试。概览rig-vectorize 在整个框架中的位置rig-vectorize 的核心是VectorizeVectorStore它同时实现了 Rig 的VectorStoreIndex与InsertDocuments两个 trait定义于 crates/rig-core/src/vector_store/mod.rsVectorStoreIndex::top_n/top_n_ids执行向量相似度查询InsertDocuments::insert_documents把文档连同其嵌入向量批量写入索引。查询时向量由注入的嵌入模型现场生成写入时文档以 JSON 形式作为元数据随向量一并存储。仓库文档的原始描述见 crates/rig-vectorize/README.md其lib.rs顶部注释给出了最简用法use rig_core::providers::openai; use rig_vectorize::VectorizeVectorStore; let openai openai::OpenAI::from_env()?; let embedding_model openai.embedding(openai::TEXT_EMBEDDING_3_SMALL, None); let vector_store VectorizeVectorStore::new( embedding_model, your-account-id, your-index-name, std::env::var(CLOUDFLARE_API_TOKEN)?, );安装与特性开关在Cargo.toml中声明依赖即可版本号以仓库 workspace 实际为准见 crates/rig-vectorize/Cargo.toml[dependencies] rig-vectorize 0.2.5 rig-core 0.36.0两种安装方式等价按需选择直接依赖rig-vectorize并配合rig-core使用其vector_store、providers、embeddings等模块通过根rigfacade根 crate 在vectorizefeature 下暴露该 crate见根 Cargo.toml 中vectorize [dep:rig-vectorize]适合统一管理所有 Rig 组件。注意 TLS 后端特性rig-vectorize直接持有reqwest::Client而非通过HttpClientExt抽象因此 TLS 后端完全由该 crate 自己的特性决定crates/rig-vectorize/Cargo.toml 中注释明确说明[features] default [rustls] rustls [reqwest/rustls] native-tls [reqwest/native-tls]默认启用rustls若改用native-tls必须在依赖中显式default-features false并开启对应特性。若两个 TLS 特性都未启用reqwest没有 TLS 后端所有指向 Cloudflare API 的 HTTPS 调用都会在握手阶段失败——这是一个容易踩中的运行时坑。端到端示例插入文档并执行相似度搜索仓库提供了完整可运行的示例 crates/rig-vectorize/examples/vectorize_vector_search.rs演示从嵌入、写入到查询的完整链路use rig_core::{ Embed, embeddings::EmbeddingsBuilder, providers::openai::{self, OpenAI}, vector_store::request::VectorSearchRequest, vector_store::{InsertDocuments, VectorStoreIndex}, }; use rig_vectorize::VectorizeVectorStore; #[derive(Embed, serde::Deserialize, serde::Serialize, Debug)] struct Word { id: String, #[embed] definition: String, } #[tokio::main] async fn main() - Result(), anyhow::Error { let openai_client OpenAI::from_env()?; let model openai_client .embedding(openai::TEXT_EMBEDDING_3_SMALL, None) .erase(); let vector_store VectorizeVectorStore::new( model.clone(), std::env::var(CLOUDFLARE_ACCOUNT_ID)?, rig-example, std::env::var(CLOUDFLARE_API_TOKEN)?, ); let documents EmbeddingsBuilder::new(model) .document(Word { id: doc-1.to_string(), definition: Definition of a *flurbo*: A flurbo is a green alien that lives on cold planets.to_string(), })? .document(Word { id: doc-2.to_string(), definition: Definition of a *glarb-glarb*: ....to_string(), })? .document(Word { id: doc-3.to_string(), definition: Definition of a *linglingdong*: ....to_string(), })? .build() .await?; vector_store.insert_documents(documents).await?; // Vectorize 是最终一致性存储新写入的文档可能需数秒后才可查询 tokio::time::sleep(tokio::time::Duration::from_secs(2)).await; let request VectorSearchRequest::builder() .query(What is a linglingdong?) .samples(3) .build(); let results vector_store.top_n::Word(request).await?; for (score, id, word) in results { println!( Score: {score:.4}, ID: {id}); println!( Definition: {}, word.definition); } Ok(()) }运行方式需要OPENAI_API_KEY、CLOUDFLARE_ACCOUNT_ID、CLOUDFLARE_API_TOKEN环境变量cargo run --release --example vectorize_vector_search示例中有几个值得注意的细节#[embed]属性Word结构体通过#[derive(Embed)]声明哪个字段作为嵌入来源这里是definition其余字段id作为元数据随向量存储.erase()把具体嵌入模型擦除为DynModelEmbedding动态类型使VectorizeVectorStore可以接受任意实现了Embed的模型VectorizeVectorStore::new的第一个参数正是impl Intorig_core::DynModelEmbedding写入后需等待因为 Vectorize 是最终一致性存储立即查询可能查不到刚插入的向量。写入链路一个向量一条记录千条一批查看 crates/rig-vectorize/src/lib.rs 的insert_documents实现通过rig_core::vector_store::flatten_embedded把「文档 多个嵌入」展开为「每个嵌入一条向量记录」每条记录用Uuid::new_v4()生成全新的向量 ID文档的 JSON 序列化结果作为metadata保存以BATCH_SIZE 1000分批调用upsertCloudflare API 单次最多接受 5000 条见 crates/rig-vectorize/src/client/mod.rs 注释分批是稳妥的工程选择空向量列表直接短路返回不发请求。查询链路先嵌入、再过滤、后阈值query_matchescrates/rig-vectorize/src/lib.rs的顺序值得注意若请求带过滤器先调用filter.validate()预检——不支持的操作在发起任何 HTTP 请求前就会报错用与写入相同的嵌入模型对查询文本现场嵌入构造 API 查询请求return_values: false不返回向量本身客户端查询后在本地再按req.threshold()过滤掉分数不达标的匹配。top_n与top_n_ids的区别在于元数据回传策略top_n请求ReturnMetadata::All并把每个匹配的 metadata 反序列化为Ttop_n_ids请求ReturnMetadata::None只返回(score, id)省去元数据网络开销。注意top_n中「匹配无元数据」时 metadata 以 JSONnull反序列化对大多数T都会失败这是 API 语义决定的边界情况。底层 HTTP 客户端VectorizeClient 四个端点VectorizeClient 封装了 Vectorize v2 API 的四个端点全部指向https://api.cloudflare.com/client/v4/accounts/{account_id}/vectorize/v2/indexes/{index_name}使用 Bearer Token 认证方法端点说明queryPOST .../query相似度查询top_k上限为 20带元数据或 100不带见 types.rs 注释upsertPOST .../upsert按 ID 插入或覆盖向量单请求上限 5000 条delete_by_idsPOST .../delete_by_ids按 ID 删除单请求上限 1000 个 IDlist_vectorsGET .../list分页列出向量 IDcount与cursor作为查询参数next_cursor用于翻页每个响应都经过统一的unwrap_api/parse_api处理先读取完整响应体并tracing::debug!记录原始文本便于排查问题再反序列化 Cloudflare 的{success, result, errors, messages}信封。信封中successfalse时取第一个错误构造ApiErrorsuccesstrue但result缺失时也会报ApiErrorNo result in successful ... response。这三条分支各有单元测试覆盖见 crates/rig-vectorize/src/client/tests.rs。元数据过滤VectorizeFilter 的能力边界Vectorize 的过滤依赖元数据索引见下文「可选启用过滤测试」rig-vectorize 通过VectorizeFilter提供类型安全的构建器它包装一个 JSON 值并实现SearchFiltertrait。支持的操作如下操作方法生成的 JSON等于eq{key: {$eq: value}}不等于ne{key: {$ne: value}}大于gt{key: {$gt: value}}小于lt{key: {$lt: value}}大于等于gte{key: {$gte: value}}小于等于lte{key: {$lte: value}}属于集合in_values{key: {$in: [...]}}不属于集合nin{key: {$nin: [...]}}组合规则与限制AND合取and把两个过滤器合并进同一个 JSON 对象Vectorize 按合取语义求值多个过滤器链式and会累积键test_multiple_and_filters验证了三层合并后三个键共存OR析取不受支持or会丢弃两侧操作数产出一个{$unsupported_or: ...}哨兵过滤器并在validate()时返回VectorizeError::UnsupportedFilterOperation。也就是说在发起任何网络请求之前带 OR 的查询就会失败。源码注释还提示该预检只能识别顶层析取嵌套在更深层的析取不会被探测到以上行为均有单元测试佐证见 crates/rig-vectorize/src/client/filter/tests.rs。查询时过滤器以req.filter()传入VectorSearchRequestVectorizeFilterRig 的请求构建器VectorSearchRequest::builder().query(..).samples(..).filter(..).threshold(..).build()。错误类型与 trait 桥接VectorizeErrorcrates/rig-vectorize/src/client/error.rs覆盖四类失败HTTP 层错误reqwest::Error、Cloudflare API 业务错误携带code与message、JSON 序列化错误、不支持的过滤操作。通过impl FromVectorizeError for VectorStoreErrorlib.rs 中VectorStoreError::datastore(err)所有错误自动桥接为 Rig 统一的VectorStoreError调用方无需感知具体后端。运行集成测试需真实 Vectorize 索引集成测试需要真实的 Cloudflare Vectorize 索引crates/rig-vectorize/README.md 给出了完整流程。1. 创建索引npx wrangler vectorize create rig-integration-test --dimensions1536 --metriccosine--dimensions必须与嵌入模型输出的维度一致如 OpenAItext-embedding-3-small为 1536 维--metric选择相似度度量这里用余弦。2. 设置环境变量并运行测试export CLOUDFLARE_ACCOUNT_IDyour-account-id export CLOUDFLARE_API_TOKENyour-api-token export VECTORIZE_INDEX_NAMErig-integration-test cargo test --package rig-vectorize --test integration_tests -- --test-threads1测试必须串行执行--test-threads1每个用例开始前会清空索引并行会互相冲突。此外由于 Vectorize 是最终一致性存储测试在插入文档后等待 5 秒再查询等待时长由源码中的EVENTUAL_CONSISTENCY_DELAY常量控制。3. 可选启用过滤测试过滤测试依赖元数据索引未创建时相关用例会被跳过npx wrangler vectorize create-metadata-index rig-integration-test --property-namecategory --typestring npx wrangler vectorize create-metadata-index rig-integration-test --property-nameid --typestring这也从侧面印证了上一节的内容要对category、id等字段执行$eq/$in等过滤必须先为它们建立元数据索引否则过滤查询无法生效。工程实践要点小结嵌入模型必须与写入时一致VectorizeVectorStore的查询向量由同一模型现场生成换模型会导致检索结果失去意义源码文档注释明确此点维度与度量在建索引时锁定创建索引时指定的dimensions必须匹配模型输出之后不易更改记住最终一致性写入后立即查询可能查不到结果示例与测试分别采用 2 秒与 5 秒的等待策略OR 过滤器不可用设计查询条件时优先用$in替代 OR 语义或把析取拆成多次查询TLS 特性必须显式配置默认rustls切换到native-tls需关闭默认特性否则 HTTPS 握手必然失败。至此从安装、示例、过滤器到 HTTP 客户端与测试流程你已经掌握了 rig-vectorize 的完整使用方式与内部实现脉络。下一步可以把VectorizeVectorStore直接挂到 Rig 的 Agent RAG 工具链中用统一抽象替换其他向量后端而无需改动业务代码。赞分享AI AgentAgent 框架RAG后端【免费下载链接】rig⚙️ Build modular and scalable LLM Applications in Rust项目地址https://gitcode.com/GitHub_Trending/rig2/rig点击查看免费下载相关推荐rig-vectorize 版本演进与源码剖析用 Rig 集成 Cloudflare Vectorize 向量检索rig vectorize 版本演进与源码剖析用 Rig 集成 Cloudflare Vectorize 向量检索 本文围绕 crates/rig vectoAI AgentAgent 框架RAG后端Cloudflare Vectorize 实战模式全解析从 Embedding 集成到多租户 RAG 检索Cloudflare Vectorize 实战模式全解析从 Embedding 集成到多租户 RAG 检索 本篇技术指南以 Cloudflare Vector人工智能AI 技能AI 插件使用 rig-lancedb 在 Rust 中构建基于 LanceDB 的向量检索与 RAG 应用使用 rig lancedb 在 Rust 中构建基于 LanceDB 的向量检索与 RAG 应用 本篇技术指南以 rig lancedb https://liAI AgentAgent 框架RAG后端上一篇Element Plus 快速上手指南5 步搭出后台管理界面下一篇ESP-BOX开发平台终极指南从入门到精通AIoT开发创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表