AI AgentAgent 框架RAG后端【免费下载链接】rig⚙️ Build modular and scalable LLM Applications in Rust项目地址https://gitcode.com/GitHub_Trending/rig2/rig点击查看免费下载本指南围绕 rig-typesafeai 这一实验性子 crate讲解如何在 Rig 生态中接入 TypeSafe 的 Jev 模型做结构化评估classification / scoring / yes-no 判断。读完本文你将掌握Querytrait 的一结构两用设计、Choice/Score/DynamicScore/Noul四种问题构建器的完整用法、Jev::from_env()客户端配置以及如何通过仓库内的示例与 fixtures 验证评估结果——全程类型安全、零手写 JSON 映射。1. 背景与定位Jev 评估在 Rig 中的角色rig-typesafeai 是 Rig 仓库中的实验性子 crate见 crates/rig-typesafeai/README.md它把 TypeSafe 的 Jev 模型接入 Rig 的共享基础设施Operation、Wire、Model与统一的 driverHTTP 传输层。与一般的 Agent 对话补全不同Jev 面向的是对同一份状态(state)批量提出多个独立问题的场景——例如工单路由、紧急度打分、是否触发人工复核一次调用返回全部结构化答案。值得注意的设计取舍这个 crate没有 Jev 的 derive 宏也没有 schema 生成 trait。类型安全完全依靠你手写的泛型Query实现配合 Serde 完成编码与解码。从 根 Cargo.toml 可以看到启用方式有两种# 方式一在根 rig crate 上开启 typesafeai feature rig { version 0.43, features [typesafeai] }# 方式二直接依赖本 crate并显式搭配一个 Rig HTTP 传输如 rig-reqwest rig-typesafeai 0.43 rig-reqwest 0.43crate 自身提供了reqwestfeature默认开启随rustlsTLS 栈用于内置的共享 HTTP 客户端也可以完全不带该 feature用JevConfig::connect或Jev::with_http自行注入传输层见 crates/rig-typesafeai/Cargo.toml 与 crates/rig-typesafeai/src/wire.rs。2. 核心模式一份结构同时表达问题与答案Jev 评估最关键的概念是Querytrait你在一个泛型命名结构体上实现Query其关联类型Response用问题字段对应的答案类型替换问题类型但保留字段名与布局Output则进一步替换为最终的应用答案类型。这样问题与答案共用一份结构声明Serde 的字段名含rename属性自动充当线上的问题 ID。以 README 中的完整示例为基础crates/rig-typesafeai/src/questions.rs 中有同样的 doctestuse rig_core::error::ProviderError; use rig_typesafeai::{Noul, NoulAnswer, Query}; use serde::{Serialize, Deserialize}; // 字段只声明一次同时用于问题与答案。 #[derive(Serialize, Deserialize)] struct AssessmentR, V { ready: R, needs_review: V, } implR: Query, V: Query Query for AssessmentR, V { type Response AssessmentR::Response, V::Response; type Output AssessmentR::Output, V::Output; fn decode(self, response: Self::Response) - ResultSelf::Output, ProviderError { Ok(Assessment { ready: self.ready.decode(response.ready)?, needs_review: self.needs_review.decode(response.needs_review)?, }) } } let query Assessment { ready: Noul::new(Is this ready to ship?)?, needs_review: Noul::new(Does this need human review?)?, };拿到一个 Jev 模型Jev::from_env()?.evaluation()后直接评估let answers: AssessmentNoulAnswer, NoulAnswer jev.evaluate(state, query).await?.answers;整个流程的类型安全链条可以从 crates/rig-typesafeai/src/lib.rs 的实现中看清serde_json::value::to_raw_value(questions)把问题结构原样序列化为 JSON保持原始字节以便校验重复键validation::request_ids用自定义 Deserializer 提取所有问题 ID 并校验其非空、唯一组装Request { state, questions }发给 Jev响应到达后先比对request_ids与response_ids不一致直接返回ProviderError::Response再serde_json::from_str反序列化为Response结构交给Query::decode逐字段校验并转换为应用答案。所以.await?只处理一次构造无关的传输/响应错误结果里全是普通类型化字段不需要手工构造 map 或按 ID 查找。2.1 用#[serde(flatten)]组合命名分组README 明确提示可以用#[serde(flatten)]把多个命名分组组合进一个评估请求。这在 crates/rig-typesafeai/src/questions.rs 的JoinedQuery中也有体现——两个对象形查询通过 flatten 序列化进同一个扁平请求解码时按各自字段名从响应中切分。3. 四种问题构建器Question Builders所有构建器都返回Result_, ProviderError在构造期就做校验而不是把错误留到运行时。构建器返回的答案类型用途约束Choice::new(instructions, [(variant, description), ...])ChoiceAnswerT从固定备选里选一个附带完整分布2–255 个备选编译期检查T: Serialize DeserializeOwned Ord且 Serde 表示必须是字符串Score::new(instructions, [(level, description), ...])ScoreAnswerL有序评分rubric返回概率加权期望值与按 level 键控的分布2–10 级编译期检查L: Ord Clone需满足 WASM 兼容的传输 boundDynamicScore::new(instructions, descriptions)DynamicScoreAnswer评分等级在运行时才确定2–10 级Noul::new(instructions)NoulAnswer返回为是的概率无数量约束下面逐一展开。3.1 Choice带完整分布的单选题use rig_typesafeai::Choice; let q Choice::new( Which support team should investigate this ticket?, [ (Route::Billing, Charges, invoices, refunds, and subscriptions), (Route::Technical, Product errors and broken functionality), (Route::Account, Login, permissions, and account access), ], )?;答案ChoiceAnswerT有三个字段crates/rig-typesafeai/src/questions.rschoice: T—— 选中的应用值probabilities: BTreeMapT, f64—— 覆盖所有备选的全分布confidence: f64—— 供应商报告的集中度不是正确概率。Choice要求备选值的 Serde 表示必须是字符串标签且标签能往返还原为原值try_from_iter内部做了to_value→ 校验字符串 →from_value→ 与原值比较见 questions.rs。空标签或重复标签、数量不在 2–255 区间都会在构造期被拒绝。数量检查分两条路径new用const { assert!(...) }做编译期检查try_from_iter对运行时集合做等价校验。3.2 Score有序评分数组顺序即线上位置use rig_typesafeai::Score; let urgency Score::Urgency::new( How urgent is the current request based on the evidence in the conversation?, [ (Urgency::Routine, Routine conversation or question; no disruption), (Urgency::Workaround, Inconvenience with a workaround), (Urgency::Significant, Significant disruption or unexpected charge), (Urgency::Critical, Critical ongoing loss or complete outage), ], )?;ScoreAnswerL的score: f64是基于零下标数组位置的概率加权均值。README 特别强调数组顺序决定数值位置与枚举的 discriminant 和Ord实现无关。也就是说Urgency枚举即使 discriminant 是 0/1/2/3线上位置也只看传给new的数组顺序。解码时questions.rsDynamicScoreAnswer里按usize键控的概率会被逐个映射回L类型的 level未知下标会得到 unknown score level 的响应错误。3.3 DynamicScore运行时定义的评分等级当评分标准rubric 身份由运行时决定、编译期无法枚举时用DynamicScoreuse rig_typesafeai::DynamicScore; let ds DynamicScore::new( Rate severity, [No impact, Minor, Major, Critical], )?;返回的DynamicScoreAnswerquestions.rs包含score: f64—— 概率加权后的零基下标期望probabilities: BTreeMapusize, f64—— 按下标键控的分布legend: BTreeMapusize, Value—— 下标到原始描述的映射confidence: f64。3.4 Noul二分判断返回为是的概率use rig_typesafeai::Noul; let clarification Noul::new( A focused clarifying question is needed before useful support advice can be given., )?; // 也可以为两个结局提供结构化描述 let q Noul::new(Is this ready to ship?)? .criteria(Yes, verified by tests and code review, No, blockers remain)?;NoulAnswer只有一个字段noul: f64是/是的概率。.criteria(yes, no)?接受字符串、对象、数组或 null 的结构化描述内部以true/false为键写入 criteria见 questions.rs。3.5 描述与状态的取值范围所有构建器都接受可序列化的描述包括结构体、JSON 对象、数组、字符串和 null状态state接受字符串、对象或数组。源码content函数questions.rs会拒绝其他类型如裸数字/布尔并在状态为 null 时明确报错state函数questions.rs。4. 组合、命名与运行时查询4.1 给独立问题一个 ID命名结构体的字段名自动成为问题 ID对独立非结构体字段的问题用.named(ready)?赋予运行时 ID。NamedQuery在序列化时把自己包成{ ready: {...} }单键对象解码时要求响应恰好一个键且 ID 匹配questions.rs。4.2 拼接与投影.join(other)把两个对象形查询展平进同一个请求重复 ID 在发送前被拒绝返回(A::Output, B::Output)元组.map(...)对校验后的答案做类型投影#[serde(transparent)]#[serde(skip)]的闭包字段不影响线上格式问题本身可按引用复用impl Query for Q让query也能参与评估键控问题集合BTreeMapString, Q本身也实现了Query解码时逐项比对键集合。这些实现都位于 crates/rig-typesafeai/src/questions.rs。4.3 完全运行时定义的查询集DynamicQuery当问题集在编译期完全未知时用DynamicQuery::new(definitions)?其中 definitions 是BTreeMapString, Question。它的输出类型是显式的BTreeMapString, types::Answer见 crates/rig-typesafeai/src/dynamic.rs。构造期校验每个定义的 ID 与 question 内容评估期逐项校验供应商返回的答案。注意这里的Answer是线上协议枚举Choice/Score/Noul三变体不是类型化应用答案。4.4 评估边界的 ID 校验无论哪种组合方式空 ID、重复 ID、响应缺失或出现意外 ID都会在评估边界被拒绝请求侧validation::request_ids用自定义 Visitor 扫描原始 JSON 的键校验非空唯一并要求至少一个问题crates/rig-typesafeai/src/validation.rs响应侧response_ids用同样的扫描比对 ID 集合不一致即报 response question IDs differ from requestlib.rs。5. 客户端配置JEV_TOKEN、模型与传输5.1 JevConfig 与 JevJevConfig是 Jev 的POST https://api.typesafe.ai/v1/systemone端点配置同时就是线上协议Wire见 crates/rig-typesafeai/src/wire.rsJevConfig::new(token)—— 默认模型jev-latest、默认端点https://api.typesafe.ai/v1/systemoneJevConfig::from_env()—— 读取JEV_TOKEN不加载 secrets 文件且拒绝空白凭据JevConfig::model(...)—— 选择其他供应商模型标识符JevConfig::with_endpoint(...)—— 覆盖完整端点 URLJevConfig::connect(http)—— 绑定任意HttpClientExt传输client()—— 使用进程内共享的 reqwest 客户端需reqwestfeature。Jev::from_env()是JevConfig::from_env()?.client()的便捷组合Jev::with_http则让你在 Rig 传输上配置超时与重试中间件后注入。.evaluation()返回ModelJevConfig——同一个模型通过共享 driver 发送因此Evaluate直接实现在ModelJevConfig, T上lib.rs。编码细节wire.rs值得注意请求体是{ model: ..., #[serde(flatten)] request }Authorization: Bearer token被标记为敏感打印/序列化配置时会脱敏并携带x-typesafe-request-id请求头与路由信息用于诊断。5.2 评估结果的元数据evaluate返回EvaluationResultAlib.rs除answers外还附带model—— 供应商返回的模型标识usage: Optiontypes::Usage—— 供应商报告时的 token 统计Jev 未报告的计数保持 unknownprovider_request_id—— 传输层请求 ID用于诊断。6. 直接跑起来交互控制台与混合分流示例仓库提供两个可直接运行的示例均已注册在 workspace 的 examples 中6.1 交互控制台 typesafeai_chat先导出JEV_TOKEN从仓库根目录运行cargo run -p typesafeai_chat默认模式只用 Jev 做决策打印每个问题的选择、集中度与完整分布并给出确定性的下一步动作。加-- --agent切换为gpt-5.6-sol回复模式需要OPENAI_API_KEYJev 的判定结果会注入 Agent 的 preamble 作为建议性路由策略。两种模式都支持/reset清空历史、/quit退出以及对话历史维护历史超过 8 轮自动弹出最旧条目见 examples/typesafeai_chat/src/main.rs。该示例展示了三个要点typesafeai_chat/src/main.rs一个泛型结构AssessmentR, U, C通过类型参数默认值同时充当答案结构ChoiceAnswerRoute/ScoreAnswerUrgency/NoulAnswer与问题结构ChoiceRoute/ScoreUrgency/NoulRoute枚举用#[serde(rename_all snake_case)]其 Serde 字符串形式即线上标签如billing、technical阈值策略放在应用代码里例如clarification 0.7 || route.confidence 0.6时优先追问next_action函数而confidence只做集中度参考。6.2 混合分流 typesafeai_triagecargo run -p typesafeai_triage对一张合成工单同时发起ChoiceScoreNoul三个问题examples/typesafeai_triage/src/main.rs一次调用得到路由、紧急度、是否重复扣费三个判定打印各自的分布与集中度。README 指出它的查询与答案形式是同一类型的两个具体实例化全程无类型擦除。7. 离线验证fixtures 重放与校验不变量不需要真实 API 也能验证 crate 行为。在仓库根目录运行cargo test -p rig-typesafeai测试会离线重放三个合成/实况录制的 fixturestriage.json、structured.json、rounded.json位于 crates/rig-typesafeai/fixtures检查本地校验不变量分布归一、概率范围、分数与均值一致性等运行 compile-fail doctests例如10个 score level、单个 choice 备选会在编译期被拒。以 triage.json 为例其请求体正是第 4.4 节描述的线上格式——questions是一个按 ID 键控的对象每个 question 有type标签choice/score/noulscore的 criteria 是数组下标即位置响应里带legend与按零基下标键控的probabilities。几点注意事项fixtures 中不含任何认证头录制的模型是jev-1.13.0重放只检查请求 JSON 形状 解码后的答案不承诺未来模型的精度或校准无效响应如错误答案种类、越界概率由单独的变异测试覆盖。校验实现位于 crates/rig-typesafeai/src/validation.rs 与 crates/rig-typesafeai/src/questions.rs概率与 confidence 必须在[0, 1]且有限分布需归一针对实况响应中概率独立四舍五入到百分位的现象容差按集合大小放宽到min(n * 0.005, 0.02)并拒绝实质未归一的大分布score必须在 rubric 下标范围内且与概率加权均值之差不超过由四舍五入误差推导出的上界。8. 设计边界与实战要点总结结合 README 的说明与源码实现使用时有几点需要牢记问题共享状态但不能消费彼此的答案——所有问题在同一个请求里独立评估同一份state不存在链式引用。需要先判定再行动的场景请在应用层分多次调用。confidence 度量的是集中度不是正确性——把分布完整保留下来probabilities/noul阈值策略一律放应用代码。校验保留供应商的原始值——包括有界的百分位四舍五入误差校验不会静默重新归一化概率发现分布严重不归一或 ID 不匹配时直接报错。构造期即校验——备选数量、标签唯一性、往返还原、内容类型都在new/try_from_iter阶段拒绝错误早暴露。线上 ID 的来源——命名结构体的 Serde 字段名含rename独立问题用.named(id)运行时集合用BTreeMapString, Q或DynamicQuery。如需查阅协议细节可参考 crate 文档中列出的 API、Choice、Score、Noul 协议来源但注意它们属于外部站点仓库内的权威参考是 crates/rig-typesafeai/src/types.rsRequest/Response/Question/Answer四个线上类型与三个 fixtures。9. 相关资源crate 说明与全部 API 用法crates/rig-typesafeai/README.md核心实现src/lib.rs、src/questions.rs、src/wire.rs、src/validation.rs完整示例examples/typesafeai_triage/src/main.rs、examples/typesafeai_chat/src/main.rs离线 fixturescrates/rig-typesafeai/fixtures/triage.json、structured.json、rounded.json根 crate 的 feature 开关Cargo.toml赞分享AI AgentAgent 框架RAG后端【免费下载链接】rig⚙️ Build modular and scalable LLM Applications in Rust项目地址https://gitcode.com/GitHub_Trending/rig2/rig点击查看免费下载相关推荐tsParticles Rounded Polygon 形状插件安装配置与圆角多边形粒子实战指南tsParticles Rounded Polygon 形状插件安装配置与圆角多边形粒子实战指南 导读 tsparticles/shape roundedAI AgentAgent 框架RAG后端CLM 实战用 Chrome 恐龙游戏 T-Rex 实时对打 TypeSafe Jev评测 System One 决策延迟与安全性CLM 实战用 Chrome 恐龙游戏 T Rex 实时对打 TypeSafe Jev评测 System One 决策延迟与安全性 本指南以 exampleSuperstruct 运行时数据校验指南定义结构、自定义类型与 TypeScript 类型安全Superstruct 运行时数据校验指南定义结构、自定义类型与 TypeScript 类型安全 Superstruct 是一款简单、可组合的 JavaS开发工具上一篇CANN pto-isa 指令详解TAXPY 原位缩放累加a·x y的语义、接口与多平台实现下一篇领域无关对比表示下的标签比例学习SelfCLR-LLP 在 Criteo 与 MovieLens-1M 上的完整实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考