跳到主要内容

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，且末尾不包含斜杠
# 本地 On-Premises 快速入门使用 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，即 Jina AI 搜索基础 API 的服务提供方 ID。AISIX Cloud Admin API 会从该服务提供方派生 openai 适配器；adapter 字段仅在 BYO 服务提供方密钥上被接受。

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

❸ api_base 是带版本的 Jina API 根地址。对于此服务提供方，版本路径段应包含在 Base 中：Embeddings 路由会将 /embeddings 原样追加到该值，重排序路由则在识别末尾 /v1 后追加 /rerank，不会插入第二个版本路径段。两个路由都能通过这一个值组成正确的上游 URL。此服务提供方的该字段可选；省略时，AISIX Cloud Admin API 会填入相同的规范值。示例显式设置该值，以便在配置中直观看到每个密钥所指向的上游根地址。

Jina 不在 models.dev 目录中，但它并非社区目录条目。网关为该服务提供方实现了 Embeddings 和重排序协议，因此控制台不会把 jina 服务提供方密钥标记为协议格式未经验证的社区条目。目录缺失影响的是定价；请参阅提供成本元数据。

创建模型​

Jina 按代际为其 Embedding 模型命名：jina-embeddings-v4 是当前支持多模态和多语言的版本。它默认返回 2048 维向量，并可通过标准 dimensions 字段截断为较小尺寸。创建模型别名前，请在 Embedding API 参考中查看当前目录。

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

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-v4",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

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

❷ model_name 是 Jina 模型 ID，例如 jina-embeddings-v4。由于 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-v4"
    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：

# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

通过 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，并由其将模型默认的 2048 维输出截断为请求的尺寸。响应会保留上游响应格式，因此 model 包含上游模型 ID，而不是面向调用方的别名；usage 会报告上游 Token 数，供 AISIX 用量核算。如果请求失败，请检查服务提供方密钥的 api_key 和 api_base，以及 model_name 中的 Jina 模型 ID。

发送 Jina 专用 Embedding 字段​

已建模的 /v1/embeddings 路由会转发 OpenAI 请求格式：model、单个字符串或字符串数组形式的 input（调用方发送的协议格式会保留到上游）、encoding_format 和 dimensions。Jina 的 Embeddings API 还接受该格式之外的字段：task 选择针对任务优化的 Embedding，例如索引文档使用的 retrieval.passage 或查询使用的 retrieval.query；late_chunking 会在一个共享上下文中嵌入输入，然后为每项输入返回向量。这些字段不属于已建模的请求格式，网关会在请求到达 Jina 前将其丢弃。

如需发送这些字段，请改为通过原始透传路由调用 Jina，该路由会原样转发请求体：

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

此处与已建模路由存在两点差异。透传路由不会改写正文，因此 model 必须是上游模型 ID，而不是别名。它还会从调用方 API Key 可访问的第一个 Jina 模型中解析上游凭证和 Base URL，因此该密钥必须已经获准使用一个 Jina 支持的别名。此路由会把剩余路径追加到服务提供方密钥的 api_base，组成 https://api.jina.ai/v1/embeddings。路由行为和限制请参阅服务提供方透传，task 和 late_chunking 的可接受值请参阅 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 兼容接口之外的服务提供方那样，在不同 API 根地址上创建第二个服务提供方密钥（可对比 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",
    "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 网关，请将重排序模型添加到现有 models 集合，并允许现有调用方密钥使用两个别名：

resources.yaml
models:
  - display_name: "jina-embed-prod"
    provider: "jina"
    model_name: "jina-embeddings-v4"
    provider_key: "jina-prod"
  - display_name: "jina-rerank-prod"
    provider: "jina"
    model_name: "jina-reranker-v3"
    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 是当前多语言版本，jina-reranker-v2-base-multilingual 是其上一代。当前目录请参阅 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，并原样转发正文，因此 Jina 的 top_n 和 return_documents 等可选参数会按写入内容到达上游。响应保留 Jina 的重排序格式：results 数组按 relevance_score 排序，每个条目包含候选项的 index，并在请求返回文档文本时包含文档本身。AISIX 会从响应中读取 usage.total_tokens 进行用量核算，因此重排序流量会出现在网关日志中；在 AISIX Cloud 中，它还会与 Embeddings 流量一起计入预算总额。

不提供 Chat Completions​

https://api.jina.ai/v1 根地址提供 Embeddings 和重排序服务，但不提供 Chat 模型。网关不会按服务提供方限制 Chat 形态的路由，因此针对 Jina 支持的别名发送 /v1/chat/completions 请求时，会通过模型解析和调用方密钥检查，到达 https://api.jina.ai/v1/chat/completions，然后返回上游错误，而不是由网关侧拒绝。桥接的 /v1/responses 路由和转换后的 /v1/messages 路由会解析到同一上游 Chat 接口，并以相同方式失败。请将 Jina 支持的别名限制为 Embedding 和重排序模型 ID。

Jina 的 Chat 形态 DeepSearch API 位于单独的主机 https://deepsearch.jina.ai/v1，不属于本页配置的 API 根地址。

提供成本元数据​

Jina 没有在 AISIX Cloud 定价流水线读取的 models.dev 目录中定价，因此会产生以下两项影响：

  • 在 jina 服务提供方密钥上创建模型时，控制台不会建议模型 ID，因此请自行输入上游模型 ID。
  • 这些别名不存在目录价格，因此预算检查、用量报告和 least_cost 路由所使用的成本只能来自你提供的定价，处理方式与自带端点相同。

在 AISIX Cloud 部署中，请通过模型定价设置每 Token 费率。对于开源 AISIX 网关，请按照模型别名中的说明，使用 resources.yaml 模型上的 cost 字段记录费率。请从 Jina 发布的 Token 定价中获取费率，并转换为每 1,000 个 Token 的美元价格。在 AISIX Cloud 中，设置费率前，这些别名不会为预算总额贡献任何成本。

端点覆盖范围​

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

路由使用 jina 模型别名时的行为
/v1/embeddings支持。openai 适配器会将 /embeddings 追加到 api_base。已建模的格式会转发 model、input、encoding_format 和 dimensions；有关 task 和 late_chunking，请参阅发送 Jina 专用 Embedding 字段。
/v1/rerank原生支持。jina 是该路由接受的三个服务提供方值之一。请参阅添加重排序模型。
/v1/chat/completionsJina 不提供该路由。网关会转发请求，由于此 API 根地址没有 Chat 模型，请求会在上游失败。请参阅不提供 Chat Completions。
/v1/responsesJina 不提供该路由。Responses 桥接会解析到相同的上游 Chat 接口，并在上游失败。
/v1/messagesJina 不提供该路由。Anthropic 到 OpenAI 的转换会解析到相同的上游 Chat 接口，并在上游失败。
/v1/images/generations不支持。该路由只接受配置的服务提供方为 openai 的模型。
/v1/videos不支持。Jina 不在视频路由的服务提供方列表中，因此路由会在联系上游前返回未实现错误。
/passthrough/jina/*rest支持。请求会原样转发到 api_base 加剩余路径。可用于 Jina 专用请求字段，以及网关尚未建模的 Jina API。

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

后续步骤​

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

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