TokenHub文本向量化与重排序完全指南:/v1/embeddings与/v1/rerank多协议支持详解

原创2026-10-14 17:06:091,694 阅读
文章标签:人工智能大模型LLM 网关API网关后端前端认证鉴权插件系统可观测性

TokenHub文本向量化与重排序完全指南:/v1/embeddings与/v1/rerank多协议支持详解

TokenHub 为企业 AI 网关提供了开箱即用的文本向量化与重排序能力:POST /v1/embeddings 负责文本 Embedding,POST /v1/rerank 负责 Rerank 重排序。两个端点复用同一套 API Key 鉴权、路由、限流与请求审计体系,并且内置 OpenAI、Cohere、Jina、Voyage、DashScope、TEI、Gemini 等多协议适配——无论上游是自托管的 vLLM/Xinference,还是商用 Cohere/Voyage 服务,都只需一次配置即可统一接入。

TokenHub 文本向量化与重排序网关架构

为什么需要统一的文本向量化网关 🧭

RAG、语义检索、知识库问答等场景都绕不开两件事:把文本变成向量(Embedding),以及把候选文档重新打分排序(Rerank)。如果没有网关,你会面临这些痛点:

  • 协议碎片化:OpenAI、Cohere、Jina、Voyage 各家的请求字段、路径、返回格式都不一样
  • 用量黑箱:谁调了向量化接口、消耗了多少、花了多少钱,无从追溯
  • 向量空间混乱:不同部署的向量互相比较,检索结果不可靠

TokenHub 的做法是:客户端只对接 /v1/embeddings 和 /v1/rerank 两个标准端点,协议差异全部由网关吸收;同时每个请求都会经过模型权限校验、TPM 预留、安全钩子和审计落盘。

/v1/embeddings:文本向量化端点详解 ✨

一个请求长什么样

最简请求只需 model 加文本(单条或数组均可):

{"model":"public-embedding","input":["第一条文本","第二条文本"],"dimensions":1024,"encoding_format":"float"}

批量输入会逐条返回稠密向量,且严格保留 index 与输入一一对应;上游返回数量、索引或维度不符时,网关会直接报错而不是静默放行。

可选参数速查

参数 取值 说明
dimensions 1–65536 指定输出向量维度
encoding_format float / base64 向量编码格式
input_type query / document 区分查询与文档语义
task 协议相关 与 input_type 二选一,不能同时传
normalized / truncation / late_chunking / user — 按上游协议支持情况透传

关键约束:单次最多 2048 条输入(个别协议上限更低);不支持的参数会被明确拒绝,而不是悄悄丢弃;稀疏向量、量化输出、多模态和异步 Batch 暂不在该端点范围内。

官方文档:docs/embeddings.md(中文版见 docs/zh-CN/embeddings.md)。

TokenHub 模型目录中的对外模型列表

Embedding 多协议支持:一次配置接入 6 种上游 🌐

在 Provider 高级设置中的 Text embedding settings 选择 embedding_protocol,网关会自动完成请求/响应的协议转换。各协议默认路径如下:

协议 Base URL 结尾 默认路径 适用场景
openai /v1 /embeddings OpenAI、SiliconFlow、vLLM/Xinference 兼容端点
cohere /v2 /embed Cohere 原生(要求 input_type 或 task)
jina / voyage /v1 /embeddings 任务与维度字段自动映射为原生名
dashscope /api/v1 /services/embeddings/text-embedding/text-embedding 阿里百炼原生接口,每次 10 条上限
tei 服务根地址 /embed Hugging Face TEI 自托管服务
Gemini 原生 Gemini 基础地址 :embedContent / :batchEmbedContents 独立文本保持独立请求,不合并批次

留空则使用目录默认或 OpenAI 兼容协议;自定义渠道(如自部署模型服务)建议明确选择实际协议。embedding_path 可覆盖默认路径——注意它是相对路径,追加到 Base URL 上,不改变主机与凭据。

TokenHub 供应商渠道列表配置

💡 本地部署示例:OpenAI 兼容端点 http://model-host:8000/v1/embeddings,Base URL 填 http://model-host:8000/v1,协议选 openai,路径留空即可。

向量空间:保证"向量可比"的关键 🔍

TokenHub 对向量兼容性的判断非常严格:默认要求 Provider、上游模型、适配器类型、Base URL、Embedding 协议与路径完全一致,路由才共享同一个向量空间。如果确认多个部署使用了等价模型版本,可在 Provider 中配置 embedding_spaces:

{"my-embedding-model": "space-v1"}

注意两点:

  • 仅维度相同不等于空间相同,必须管理员确认兼容后才能共用空间 ID
  • 空间冲突时请求返回 409 embedding_space_conflict;更换空间意味着业务侧要重建向量索引,TokenHub 本身从不改动外部索引

空间契约的实现细节可以参考 backend/internal/server/embedding_routes.go。

/v1/rerank:重排序端点详解 🎯

请求与响应

POST /v1/rerank 接收一个查询和一串候选文档,返回带相关性得分的结果:

{"model":"public-reranker","query":"如何续期证书?","documents":["续期说明","一篇无关文档"],"top_n":1,"return_documents":true}

响应中的 results 保留原始 index 与 relevance_score,return_documents 为 true 时带回 document.text。几个行为要点:

  • documents 必须包含 1–2048 条非空文本;top_n 介于 1 与文档数之间,不传则返回全部
  • 分数不做跨模型归一化,不同 Reranker 模型的得分不可直接比较
  • 空查询、非法 top_n、无效的 top_n/索引缺失都会显式报错
  • 当前仅支持纯文本,图片、视频与异步任务不在本期范围

官方文档:docs/rerank.md(中文版见 docs/zh-CN/rerank.md)。

TokenHub 模型路由规则配置

Rerank 协议支持对照表

在 Advanced → Text rerank settings 中按实际部署选择协议:

协议 Base URL 结尾 默认端点 说明
jina /v1 /rerank Jina、SiliconFlow 及 vLLM/Xinference 兼容部署
cohere /v2 /rerank Cohere 文本重排,按 search unit 计费
voyage /v1 /rerank top_n 自动映射为 top_k
qwen 区域兼容地址 /reranks 阿里 qwen3-rerank
dashscope /api/v1 /services/rerank/text-rerank/text-rerank 阿里 gte-rerank-v2 原生封装
tei 服务根地址 /rerank Hugging Face TEI,文档映射为 texts

instruction 参数在 Jina 兼容/Qwen/DashScope 场景下可用,truncation 适用于 Voyage 与 TEI——最终以所选模型的实际能力为准,不支持的选项会显式失败。自定义 openai-compatible/local 渠道若无厂商目录,自动采用 Jina 兼容的 /rerank 契约。

重排端点的完整执行链路(鉴权 → 隐私钩子 → 护栏 → 路由 → 缓存 → 计费)实现在 backend/internal/server/gateway_rerank_http.go。

计费与用量治理:每一笔向量调用都可追溯 📊

向量化与重排序请求同样纳入 TokenHub 的成本治理:

  • 两侧定价:发布路由时需同时配置租户侧 Embedding 价格与供应商侧输入价格;确认自托管模型免费时,需显式设置 metadata.retrieval_pricing_confirmed="true",历史空零值不视为确认
  • 用量诚实:上游未报告用量时保持"未报告",绝不拿估算值冒充实测数据
  • 缓存复用:Embedding/Rerank 结果可通过缓存钩子复用,缓存键绑定向量空间与调用方范围,命中后免去重复上游调用
  • 审计留痕:每次请求的载荷、错误、用量证据都保存在请求详情中,方便事后对账

TokenHub 用量分析仪表盘

常见问题快速排查 🛠️

Q:调用返回 501 provider_capability_not_supported? 说明所有候选线路都被运行时筛选排除,且尚未发出任何上游请求。查看 error.details.reasons 中的原因码逐项修复:

原因码 检查项
provider_capability_or_protocol_unsupported 渠道是否支持对应 Embedding/Rerank 协议
tenant_price_not_configured 对外模型是否配置了价格或明确确认免费
upstream_model_inventory_missing 渠道库存是否有匹配的上游模型记录
upstream_model_modality_mismatch 库存模型类型是否为 embedding
upstream_text_input_unsupported 库存是否支持文本输入

Q:返回 409 embedding_space_conflict? 多线路向量空间不一致。移除不兼容线路,或确认兼容后为相同模型配置同一空间 ID。

Q:如何发布前验证上游连通性? 管理员可用 POST /api/admin/playground/rerank(或对应 Embedding 预检)以管理会话直接测试上游模型,查看响应与用量证据,无需等租户侧验收。

总结

TokenHub 的 /v1/embeddings 与 /v1/rerank 把最碎片化的两件事——多协议向量/重排接入和用量治理——收敛成了两个干净的端点。核心要点回顾:

  1. 客户端零适配:标准端点 + API Key,OpenAI SDK 的 client.embeddings.create 直接可用
  2. 协议全覆盖:Embedding 6 种协议 + Gemini 原生,Rerank 6 种协议,本地自托管与商用服务通吃
  3. 空间严格契约:向量可比性由网关强制保证,冲突显式报错
  4. 全程可治理:权限、限流、计费、审计与 RAG 业务链路完全打通

更多细节可查阅 docs/semantic-routing.md 与 docs/architecture.md,了解语义路由与网关整体架构设计。

登录后查看全文
TokenHub