版本：Dev

Jina

Jina AI 为搜索和检索应用提供 Embedding 和重排序模型。AISIX 让应用通过网关的 OpenAI 兼容 Embeddings 路由和统一重排序路由调用这些模型，同时管理 Jina 凭证、调用方访问权限和限流。

Jina 通过同一个 API 根地址提供 Embedding 和重排序服务，因此一个服务提供方密钥可以支持两类模型。本指南先配置一个 Embedding 模型，再为重排序模型复用该服务提供方密钥。

准备工作

开始前，请准备以下内容：

一套 AISIX 环境：
- 对于 AISIX Cloud，需要一个已关联网关的环境和具备写入权限的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
- 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
从 Jina AI API 控制台获取的 Jina API Key。一个密钥可授权使用包括 Embedding 和重排序在内的所有 Jina API 产品。
curl 和 jq。

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

为 Jina 支持的 Embeddings 路由创建服务提供方密钥、模型别名和调用方 API Key。

创建服务提供方密钥

创建用于存储 Jina 凭证和 API 根地址的服务提供方密钥：

# 请替换为实际值
export JINA_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "jina-prod",
    "provider": "jina",
    "api_key": "'"${JINA_API_KEY}"'",
    "api_base": "https://api.jina.ai/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider 为 jina，这是 AISIX 重排序路由能够识别的服务提供方值。Jina 不在 models.dev 中，但 AISIX Cloud 会把它作为直接支持的服务提供方接受，并为 Embeddings 及其他 OpenAI 形态路由派生 openai 适配器。adapter 字段仅在 BYO 服务提供方密钥上被接受。

❷ api_key 存储 Jina API Key，并在上游调用中作为 Bearer Token 发送。其行为遵循服务提供方密钥中的凭证处理方式。

❸ api_base 是带版本的 Jina API 根地址。Embeddings 路由会将 /embeddings 追加到该值，重排序路由则会识别末尾的 /v1，再追加 /rerank，因此两个路由都能从同一个服务提供方密钥组成正确的上游 URL。此字段可选；省略时，AISIX Cloud Admin API 会填入相同的规范值。若密钥指向不同的 Jina 部署，请显式设置该字段。

该命令将返回的服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。

创建模型

此示例使用 jina-embeddings-v5-text-small，这是当前的 1024 维文本 Embedding 模型。Jina 还提供面向文本、图片、音频、视频和 PDF 输入的多模态 v5 模型。由于规范化 AISIX 路由只接受字符串，这些非文本输入结构需要透传路由。

创建调用方将在请求中发送的模型别名：

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "jina-embed-prod",
    "model_name": "jina-embeddings-v5-text-small",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name 是调用方在 model 中发送的别名。

❷ model_name 是准确的 Jina 模型 ID。由于 Jina 不在 models.dev 中，控制台不会为此服务提供方建议模型 ID；请自行输入 Jina 当前模型目录中的 ID。

❸ provider_key_id 将该别名关联到 Jina 服务提供方密钥。

创建调用方 API Key

创建可访问该模型别名的调用方 API Key。明文密钥由服务器生成，并且只在响应中返回一次，因此请立即保存：

AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "jina-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "$AISIX_API_KEY"

allowed_models 值必须引用上一步保存的模型 ID，使该密钥只能访问已创建的别名。写入后，配置会自动投射到已关联的网关。

使用开源 AISIX 网关配置

导出上游凭证，并选择应用将发送给网关的调用方 API Key：

export JINA_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

对于新网关，请使用此完整资源文件。对于现有网关，请将这些条目合并到其当前文件中，并保留其他资源：

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "jina-prod"
    provider: "jina"
    adapter: "openai"
    api_key: ${JINA_API_KEY}
    api_base: "https://api.jina.ai/v1"

models:
  - display_name: "jina-embed-prod"
    provider: "jina"
    model_name: "jina-embeddings-v5-text-small"
    provider_key: "jina-prod"

api_keys:
  - display_name: "jina-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "jina-embed-prod"

如果 AISIX 安装在本地，请在加载前校验文件：

aisix validate --resources resources.yaml

校验后，请在网关进程环境中提供所引用的环境变量并启动网关。仅当这些变量已可用于现有网关进程时才重新加载；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的校验和启动命令。挂载此 resources.yaml 文件，并在两个命令中使用 -e 传入该文件引用的每个环境变量。资源加载后，准备下文共用的验证请求：

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接

导出 AISIX 网关 Origin：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

通过 AISIX 代理发送 Embeddings 请求，并将 dimensions 设置为低于模型默认值的数值：

curl -sS -X POST "$AISIX_PROXY/v1/embeddings" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jina-embed-prod",
    "input": "AISIX keeps the provider credential on the gateway side.",
    "dimensions": 128
  }' -o jina-embed-response.json

jq '.data[0].embedding | length' jina-embed-response.json

此命令应输出 128。向量长度与请求的 dimensions 一致，说明可选字段已到达 Jina，并由其将模型默认的 1024 维输出截断为请求的尺寸。

AISIX 会在兼容 OpenAI 的 Embeddings 响应中重建接受的 Dense 结果。响应中的 model 字段会回显面向调用方的别名；AISIX 会保留 Float 或 Base64 向量、索引，以及提示词和总 Token 计数，但不会保留 image_tokens、audio_tokens 或 video_tokens 等 Jina 专属用量字段。如果请求失败，请检查服务提供方密钥的 api_key 和 api_base，以及 model_name 中的 Jina 模型 ID。

发送 Jina 专用 Embedding 字段

已建模的 /v1/embeddings 路由只接受 model、字符串或字符串数组形式的 input、encoding_format 和 dimensions。AISIX 会将调用方的单字符串或数组输入结构保留到上游。Jina 使用 embedding_type 而非 encoding_format 表示输出编码。

task、embedding_type、normalized 和 truncate 等 Jina 专属字段会在请求到达 Jina 前被丢弃。图片、音频、视频或 PDF 文档的对象输入不匹配 AISIX 请求 Schema，会在解码时被拒绝。Jina Sparse Embedding 和 v4 Multi-vector 响应也超出 AISIX 响应 Schema，会导致上游响应解码失败。这些请求或响应结构请使用透传路由。

如需发送这些字段，请改为通过透传路由调用 Jina，该路由会原样转发请求体。本页的 /passthrough/jina 路径假定一条透传路由认领该前缀，target_url 设为 https://api.jina.ai/v1 并挂上 Jina 服务提供方密钥；在调用方 Key 的 allowed_routes 上授予该路由：

curl -sS -X POST "$AISIX_PROXY/passthrough/jina/embeddings" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jina-embeddings-v5-text-small",
    "task": "retrieval.passage",
    "embedding_type": "float",
    "normalized": true,
    "truncate": true,
    "input": [
      "Provider keys store the upstream credential.",
      "Caller API keys authorize model access."
    ]
  }'

路由不会改写正文，因此 model 必须是上游模型 ID，而不是别名。它注入路由上配置的服务提供方密钥，而不是从调用方密钥的模型允许列表借用；存在多个 Jina 密钥时，请给每把密钥各配一条路由。

该路由会把剩余路径追加到其 target_url，组成 https://api.jina.ai/v1/embeddings，并原样中继响应体。透传检测依据正文键，而不是端点，因此该 Embeddings 请求体中的顶层 input 会让 AISIX 应用 Responses 风格的提取和用量规则。只有响应包含受支持的 Token 字段时，AISIX 才会记录用量。不要依赖透传核算处理 Jina 特有的响应形状。路由行为和限制请参阅透传路由，当前模型特定字段请参阅 Embedding API 参考。

添加重排序模型

/v1/rerank 路由接受服务提供方值为 openai、cohere 或 jina 的模型。对于 jina，协议为恒等映射：Jina 重排序 API 使用与网关统一重排序契约相同的请求字段（model、query、documents 和可选参数）及 results 响应格式，因此 AISIX 只会将 model 字段改写为上游模型 ID，并原样转发正文。

Jina 的重排序服务与 Embeddings 同样位于 https://api.jina.ai/v1 根地址，因此上文创建的服务提供方密钥已经可以访问，无需再创建第二个服务提供方密钥。这与重排序端点位于 OpenAI 兼容接口之外的服务提供方不同；可对照 Cohere 的重排序设置。重排序路由会在服务提供方密钥 Base 后追加 /rerank，且仅在 Base 末尾没有 /v1 时才插入 /v1 路径段，因此规范的 Jina Base 会组成 https://api.jina.ai/v1/rerank，而不会重复版本路径段。

在 AISIX Cloud 中，创建重排序模型别名和仅限该模型的调用方密钥：

RERANK_MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "jina-rerank-prod",
    "model_name": "jina-reranker-v3.5",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

RERANK_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "jina-rerank-caller",
    "allowed_models": ["'"${RERANK_MODEL_ID}"'"]
  }' | jq -r '.plaintext')

对于开源 AISIX 网关，请将 jina-rerank-prod 添加到现有 models 集合。将现有 jina-caller 条目替换为下面更新后的条目，使其允许两个模型别名。保留无关条目和集合：

resources.yaml（重排序模型访问）
models:
  - display_name: "jina-rerank-prod"
    provider: "jina"
    model_name: "jina-reranker-v3.5"
    provider_key: "jina-prod"

api_keys:
  - display_name: "jina-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "jina-embed-prod"
      - "jina-rerank-prod"

按照上文说明校验并重新加载或重启声明式资源文件，然后使用现有调用方密钥发送重排序请求：

export RERANK_API_KEY="$CALLER_API_KEY"

重排序模型 ID 使用独立于 Embedding 代际的命名方式。jina-reranker-v3.5 是当前的多语言、多文档重排模型，可直接替代 jina-reranker-v3。当前目录请参阅 Reranker API 参考。

通过代理发送重排序请求：

curl -sS -X POST "$AISIX_PROXY/v1/rerank" \
  -H "Authorization: Bearer ${RERANK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jina-rerank-prod",
    "query": "How do I rotate a provider credential?",
    "documents": [
      "Provider keys store the upstream credential.",
      "Caller API keys authorize model access.",
      "Rate limits apply per caller key."
    ],
    "top_n": 2
  }'

AISIX 只会将 model 字段改写为 jina-reranker-v3.5，并原样转发正文，因此 Jina 的 top_n、return_documents、max_doc_length 和 return_embeddings 等可选参数会按写入内容到达上游。响应保留 Jina 的重排序格式：results 数组按 relevance_score 排序，每项包含候选项的 index，并在请求时包含文档或文档 Embedding。Jina 的重排序响应会携带模型名称，AISIX 会将该字段改写回请求所使用的别名，因此它显示的是 jina-rerank-prod 而不是 jina-reranker-v3.5。AISIX 会将 usage.total_tokens 读取为重排用量和成本核算的输入 Token。

实验性 Chat Completions

Jina 在同一 API 根地址上为确切模型 ID jina-ai/jina-vlm 提供实验性的兼容 OpenAI /v1/chat/completions 端点。它接受文本和图片输入，但 Jina 将其描述为仅供测试，不保证可用性、扩展性或生产就绪程度。请勿将其作为生产依赖。

如需测试，请在现有服务提供方密钥上创建 model_name: "jina-ai/jina-vlm" 的独立模型别名。直接 /v1/chat/completions 请求会到达 Jina 原生 Chat 路由。/v1/responses 和 /v1/messages 会通过 Chat Completions 使用 AISIX 转换，因此仍受 Responses和 Anthropic Messages中所述桥接限制。

Jina DeepSearch 是位于 https://deepsearch.jina.ai/v1 的另一项 Chat 形态产品。请为它配置独立的服务提供方密钥和模型别名。若使用透传，请另建一条以 DeepSearch 基础地址为目标、注入 DeepSearch 服务提供方密钥的透传路由。

提供成本元数据

Jina 未在 models.dev 目录中定价。这些别名不存在自动目录价格，因此 least_cost 路由和成本估算只会使用你提供的定价。在 AISIX Cloud 中通过模型定价设置费率；在开源 AISIX 网关中使用模型的 cost 字段，详见成本元数据。请把 Jina 发布的费率换算为每 1,000 Token 的美元价格。

规范化 Embeddings 路由会记录 Jina 的 usage.prompt_tokens。如果 Jina 模型只返回 usage.total_tokens，AISIX 会使用总数执行每分钟 Token 限制，但在用量事件中记录零输入 Token。Rerank 会将 Jina 的 usage.total_tokens 映射到输入 Token。顶层带 query 和 documents 数组的透传 rerank 请求体按与 Rerank 路由相同的方式读取，因此 Jina 的 usage.total_tokens 会记为输入 Token。其他透传请求体（例如 Embeddings）会记录存在的 prompt_tokens 或 input_tokens 以及 completion_tokens 或 output_tokens，但不会把仅含 total_tokens 的响应映射为输入用量。参见信封识别与用量。

端点覆盖范围

Jina 服务提供方密钥会为 OpenAI 形态的路由解析 openai 适配器，重排序路由则直接按 jina 服务提供方值分发：

路由	使用 `jina` 模型别名时的行为
`/v1/embeddings`	默认支持字符串输入和单个 Dense Float 输出。已建模的格式会转发 `model`、字符串或字符串数组形式的 `input`、`encoding_format` 和 `dimensions`，但 Jina 使用 `embedding_type` 选择 Base64、Binary 或 Unsigned Binary 输出。有关这些编码、原生字段、多模态输入及其他输出格式，请使用发送 Jina 专用 Embedding 字段中所示的透传路由。
`/v1/rerank`	使用 Jina 重排序模型别名时支持。`jina` 是该路由接受的三个服务提供方值之一。请参阅添加重排序模型。
`/v1/chat/completions`	仅 Jina 在此 Root 上用于测试的 `jina-ai/jina-vlm` 模型支持。请参阅实验性 Chat Completions。Embedding 和重排序别名会在 Chat 路由上失败。
`/v1/responses` 和 `/v1/messages`	仅对实验性 VLM 别名通过 Chat 转换支持。它们并非 Jina 原生路由，并保留各自桥接限制。`/v1/messages/count_tokens` 仍仅支持 Anthropic。
`/v1/completions`、`/v1/audio/*`、`/v1/files`、`/v1/batches` 和 `/v1/fine_tuning/jobs`	与此 Root 上的 Jina API 不兼容。Jina 的音频和视频支持是指多模态 v5 Embedding 输入，而不是规范化 AISIX 音频或视频生成端点。Jina 原生批量 Embedding 使用不同的路径和契约。
`/v1/images/generations` 和 `/v1/videos`	不支持 `jina` 服务提供方值。
`/passthrough/jina/*rest`	通过已配置的透传路由可用，相对于路由目标解析。可用于原生 Embedding 字段、多模态输入、分类器、训练，以及 `/batch/embeddings` 等原生批处理路径。路由要求准确的上游模型 ID，并保留响应正文。只有检测到的请求信封和响应字段采用受支持的 Token 形状时，才会记录用量。

完整端点和服务提供方矩阵请参阅服务提供方兼容性。

后续步骤

你已将 AISIX 连接到 Jina，验证了 Embedding 别名，并添加了重排序路由。接下来可阅读以下指南：

模型别名：为这些别名配置路由、重试行为或成本元数据。
重排序：查看重排序请求契约及其服务提供方要求。
Embeddings：查看已建模的 Embeddings 请求格式和服务提供方行为。
服务提供方兼容性：查看支持的代理端点和服务提供方特有限制。

准备工作​

使用 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

发送 Jina 专用 Embedding 字段​

添加重排序模型​

实验性 Chat Completions​

提供成本元数据​

端点覆盖范围​

后续步骤​