入门指南 / API 协议与全栈接入
Jev API 接入指南:3 大官方及网关端点与规范
Jev(System One)是专为业务决策设计的类型化 AI 模型。本站已实装并深度支持三大生产级接入端点(TypeSafe AI 原生端点、Vercel AI Gateway 与 OpenRouter 网关),帮助工程团队以 0 语法错误将确定性决策嵌入业务系统。
速查导读:Jev 怎么接?3 个端点如何选?
在实际工程落地中,请根据业务场景选择最适端点:1) 低延迟核心链路直连 TypeSafe 官方端点(https://api.typesafe.ai/v1/systemone,延迟最低 <120ms,支持原生 token 概率分布);2) Next.js 全栈与 Serverless 推荐接入 Vercel AI Gateway(https://ai-gateway.vercel.sh/v1/evaluate,自带边缘缓存与 OpenTelemetry 监控);3) 多模型共享账单与容灾备份使用 OpenRouter 网关(https://openrouter.ai/api/alpha/decisions)。生产最佳实践是:绝不在浏览器直调端点,而是在服务端封装自适应适配器,结合 1500ms 超时与双端点 Failover 降级机制。
已实装接入端点目录
已实装并验证的 3 大生产级 Jev 端点
针对不同部署拓扑与计费体系,选择最契合工程架构的入口:
TypeSafe AI 官方端点
TypeSafe 是 Jev 与 System One 模型架构的官方缔造者与核心推理托管商。直接调用该端点无额外代理跳转,能在正向传播阶段直接输出各选项的原生对数概率(Log-probabilities),适合对 SLA 与延迟极度敏感的同步核心风控与工单路由。
https://api.typesafe.ai/v1/systemoneAuthorization: Bearer ts_live_***jev-latest (或 jev-1)Vercel AI Gateway 端点
深度集成 Vercel 全球边缘基础设施与 Edge Middleware。原生支持全局边缘响应缓存(Edge Caching)、智能限流保护、OpenTelemetry 链路追踪与团队协作账单,非常适合在 Next.js App Router / Edge Functions 中开箱即用。
https://ai-gateway.vercel.sh/v1/evaluateAuthorization: Bearer vck_***typesafe-ai/jevOpenRouter 统一决策端点
全球领先的统一 AI 路由平台。开发者只需维护单一 API Key 与统一资金账户,即可调用 Jev 模型。提供透明的用量审计日志,且天然适合作为 TypeSafe 官方端点的异构容灾备选,实现跨服务商的高可用热备。
https://openrouter.ai/api/alpha/decisionsAuthorization: Bearer sk-or-v1-***typesafe/jev-1.133 大接入端点技术特性全维度对比
涵盖鉴权协议、模型标识符、延迟开销、计费账单与适用拓扑:
| 维度指标 | TypeSafe AI (官方直连) | Vercel AI Gateway | OpenRouter 网关 |
|---|---|---|---|
| 端点地址 (Endpoint) | https://api.typesafe.ai/v1/systemone | https://ai-gateway.vercel.sh/v1/evaluate | https://openrouter.ai/api/alpha/decisions |
| 鉴权标头 (Auth Header) | Authorization: Bearer ts_live_*** | Authorization: Bearer vck_*** | Authorization: Bearer sk-or-v1-*** (附带 HTTP-Referer) |
| 生产模型标识 (Model ID) | jev-latest / jev-1 | typesafe-ai/jev | typesafe/jev-1.13 |
| 典型网络延迟 | 最快 (~80-140ms),直连推理机架 | 极快 (~100-160ms),边缘就近路由 | 良好 (~120-190ms),含多模型代理跃点 |
| 专属工程优势 | 直接输出各选项原生 log-probs,新特性零延迟同步 | 内置全局边缘缓存、OTel 遥测与 Vercel 统一配额 | 单 Key 聚合管理、跨厂商故障转移、团队统一充值 |
| 推荐工程场景 | 严苛低延迟同步业务、原生 Jev 深度调优 | Next.js 全栈站点、Serverless Edge 部署 | 多模型混合调度、作为异地多活热备通道 |
4 步标准接入流程:从凭证到高可用决策
遵循确定性决策设计模式,将 Jev 严谨地接入业务系统的标准步骤:
配置服务端环境变量
在对应平台控制台创建 API Key,并安全注入服务端环境变量(如 .env.local 或 Cloudflare Secrets),切忌在前端代码中硬编码任何密钥。
设计业务上下文 State 与 Typed Question
将业务证据梳理为紧凑清晰的 state 字符串,同时声明具有明确互斥 criteria 的 typed question(Choice、Score 或 Noul),避免非结构化 Prompt 注入。
通过服务端请求指定端点
在服务端的 API Route 或后台微服务中发起 HTTP POST 请求,由服务端统一完成请求序列化、鉴权校验与网络超时熔断。
校验置信度与执行 Fallback 降级
验证返回的 confidence 置信度。置信度高于阈值(如 >=0.85)时自动执行业务动作;若置信度偏低或端点不可用,平滑切入安全兜底分支。
交互式接入代码实战(3 大端点与统一容灾适配器)
复制生产可用的代码模板,覆盖 TypeScript、Python、cURL 以及多端点热备:
// server/jev-typesafe.ts
// 官方直连端点:https://api.typesafe.ai/v1/systemone
export async function evaluateWithTypesafe(ticketText: string) {
const apiKey = process.env.TYPESAFE_API_KEY;
if (!apiKey) throw new Error('Missing TYPESAFE_API_KEY');
const response = await fetch('https://api.typesafe.ai/v1/systemone', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${apiKey}`,
},
body: JSON.stringify({
model: 'jev-latest',
state: `Customer Ticket: "${ticketText}"`,
questions: {
intent: {
type: 'choice',
instructions: 'Classify incoming customer support intent',
criteria: {
billing: 'Subscription, invoice, or refund inquiries',
technical: 'System bug, error code, or API issue',
general: 'General inquiry or feature request',
},
},
},
}),
});
if (!response.ok) {
const errorText = await response.text();
throw new Error(`TypeSafe API failed [${response.status}]: ${errorText}`);
}
const result = await response.json();
const decision = result.answers?.intent;
return {
selected: decision?.selected as 'billing' | 'technical' | 'general',
confidence: decision?.confidence as number, // 0.0 ~ 1.0
probabilities: decision?.probabilities as Record<string, number>,
usage: result.usage,
};
}HTTP 请求报文与响应体标准协议规范
标准 JSON 负载结构,完全摒弃模糊 Prompt,确保 0 语法解析错误:
HTTP POST 请求体字段规范 (Request Body)
model模型标识符。TypeSafe 端点推荐 `jev-latest`;Vercel 端点为 `typesafe-ai/jev`;OpenRouter 为 `typesafe/jev-1.13`。
state输入给模型的决策上下文事实(如工单内容、交易流水、待审评论),作为判定依据。
questions命名问题字典。每个问题必须明确声明 `type`(choice / score / noul)、`instructions` 与具体 `criteria` 评判标准。
questions[key].type输出类型。Choice 为互斥命名选项;Score 为连续有序数值;Noul 为紧凑的二元判定。
questions[key].criteria各个候选答案的具体裁定准则。定义清晰互斥的判定描述,确保每个选项可合理解释。
HTTP 响应报文核心结构 (Response Payload)
{
"model": "jev-latest",
"answers": {
"intent": {
"type": "choice",
"selected": "billing",
"confidence": 0.942,
"probabilities": {
"billing": 0.942,
"technical": 0.041,
"general": 0.017
}
}
},
"usage": {
"input_tokens": 128,
"output_tokens": 1
},
"latency_ms": 112
}常见 HTTP 状态码与故障排查
模型顺利完成前向概率推理,返回值严格符合 Schema 定义。
缺少 state 字段、Question criteria 为空或声明了未支持的类型。
检查 Authorization 标头中是否包含有效的 Bearer API Key。
超过提供商的短时并发配额或账户点数耗尽,需排队或提升配额。
触发服务端设定的熔断阈值,应自动切换至备用端点或本地 Fallback。
生产环境架构规范与高可用法则
严守凭证隔离红线
绝不在浏览器端直接引用端点 API Key。所有外部端点调用必须在服务端或 Edge API Route 封装,对外仅暴露清洗后的领域决策结果。
双端点热备与主动熔断
在生产微服务中配置主端点(如 TypeSafe)与备用端点(如 OpenRouter)。设置 1500ms 超时掐断,超时即刻无缝回放请求至备用网关。
显式区分网络失败与业务不确定
端点连接失败属于基础设施故障(触发容灾重试);confidence < 0.85 属于业务模糊(流转至人工复核审核池)。两者日志与告警必须分流。
沉淀决策样本为黄金回归集
持久化每次推理的输入 state、所选端点、置信度与最终选项。当模型升级或调优 criteria 时,可一键批量回归验证业务准确度。
关于 Jev API 接入的常见问题 (FAQ)
在三大端点(TypeSafe、Vercel、OpenRouter)之间,如何做出最佳技术选型?
如果追求极致的执行速度(<140ms)并需要获取所有候选答案的原生概率分布(probabilities),推荐首选 TypeSafe AI 官方端点;如果项目基于 Next.js App Router 或 Cloudflare/Vercel 全栈构建,并且需要边缘节点缓存及统一团队计费,选 Vercel AI Gateway;如果已有 OpenRouter 充值账户,或者需要建立跨供应商的多活高可用架构,OpenRouter 是最理想的备选与通用入口。
不同端点调用同一批输入,输出的 Choice 结果和置信度会不同吗?
不会。三大接入端点底层均调度同一组 Jev 模型权重(如 Jev 1.13 / System One),相同的输入 state 和相同的 criteria 在 forward pass 中会产生确定性的对数概率分布,因此核心判定和 confidence 数值是一致的。各端点的差异仅体现在网络跃点、HTTP 标头规范、边缘缓存策略及使用量审计字段的命名格式上。
为什么 Jev API 能够保证 0% 语法结构错误?
传统的大语言模型通过贪婪采样(Greedy Decoding)逐字生成长文本,再依赖正则表达式或 JSON.parse 提取结果,极易出现括号不闭合或多余的 Markdown 标记。而 Jev 的 System One 架构在神经网络的正向传播(Forward Pass)阶段,直接在开发者预设的候选 Schema 集合上评估 softmax 概率,并直接返回最高概率索引。它在物理上无法输出任何未声明的格式或非法字符。
本站自身是否也提供了现成的 Jev 内部中继 API?
是的。本项目在 `/api/jev/evaluate` 部署了开箱即用的高安全中继服务。该内部接口支持在服务端自动适配 TypeSafe、Vercel 和 OpenRouter,并内置了 Cloudflare Turnstile 人机验证、原子日用量配额、5次/10秒突发限流与 32KB 请求体安全熔断,可直接在项目内部页面安全复用。
当 Jev API 返回置信度较低(如 confidence < 0.85)时,应该如何处理?
置信度是控制业务流转的数字信号而非绝对真理。对于低置信度情况,最佳实践是设计显式的“三态策略”:高置信度(>=0.90)完全无人值守自动执行;中置信度(0.75-0.90)在用户界面提供推荐标签供人工二次确认;低置信度(<0.75)流转至人工待办池或执行安全保守的默认兜底动作。