版本：1.5.0

Cohere

Cohere 提供 Command 模型以及生成、Embedding 和 rerank API。AISIX 将这些能力置于由网关管理的凭证、调用方访问权限、限流和用量核算之后。

Cohere 发布了原生 API，以及用于 OpenAI 形态请求的兼容性 API。本指南使用兼容性 API 处理 Chat Completions 和 Embedding，然后为 rerank 单独配置原生 API。

准备工作

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

一套 AISIX 环境：
- 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
- 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 配置。配置网关以加载声明式资源文件。
从 Cohere 控制台获取的 Cohere API Key。
已安装 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"

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

AISIX 通过 openai 适配器连接 Cohere 兼容性 API。Chat Completions 和 Embedding 无需请求转换。Cohere rerank 使用原生 API，同一个服务提供方密钥即可提供，见添加 Rerank 模型。

创建服务提供方密钥

创建用于存储 Cohere 凭证和 API 根路径的服务提供方密钥：

# 请替换为实际值
export COHERE_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": "cohere-prod",
    "provider": "cohere",
    "api_key": "'"${COHERE_API_KEY}"'",
    "api_base": "https://api.cohere.ai/compatibility/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider 为 cohere。AISIX Cloud Admin API 从目录服务提供方派生适配器；仅在 BYO 服务提供方密钥上接受 adapter 字段。

❷ api_key 存储 Cohere API Key。它遵循服务提供方密钥中的凭证处理行为。

❸ api_base 指向 Cohere 兼容性 API。该路径在 /v1 版本段之前包含 /compatibility，因为 OpenAI 形态路由与 Cohere 原生 API 使用不同的前缀。也可以使用裸主机根地址，例如 https://api.cohere.com，请参阅 AISIX 如何构造 Cohere URL。对于 cohere 目录服务提供方，该字段为可选项；省略时 AISIX Cloud Admin API 会填入相同的值。示例仍显式设置该字段，使配置中始终可以看到每个密钥指向的接口。

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

创建模型

Cohere 模型 ID 由系列名称和发布日期组成：command-a-03-2025 是 command-a 系列 2025 年三月的快照，能力变体会在日期前添加后缀，例如 command-a-reasoning-08-2025 或 command-a-vision-07-2025。日期是 ID 的一部分，因此根据目录 ID 创建的模型别名会固定到一个快照。当前 ID 请查看 Cohere 模型列表。

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

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": "cohere-command-a-prod",
    "model_name": "command-a-03-2025",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

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

❷ model_name 是 Cohere 模型 ID，例如 command-a-03-2025、command-a-plus-05-2026 或 command-a-reasoning-08-2025。

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

创建调用方 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": "cohere-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "$AISIX_API_KEY"

allowed_models 值必须引用上一步保存的模型 ID。写入后，配置会自动投射到已关联的网关。

使用开源 AISIX 网关配置

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

export COHERE_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

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

resources.yaml
_format_version: "1"

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

models:
  - display_name: "cohere-command-a-prod"
    provider: "cohere"
    model_name: "command-a-03-2025"
    provider_key: "cohere-prod"

api_keys:
  - display_name: "cohere-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "cohere-command-a-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 代理发送 Chat Completions 请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere-command-a-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Cohere."
      }
    ]
  }'

网关返回 OpenAI 兼容响应，其中回显面向调用方的别名 cohere-command-a-prod。如果请求失败，请检查服务提供方密钥的 api_key、api_base 和 model_name 中的 Cohere 模型 ID。上游返回 404 通常表示 api_base 带有 AISIX 如何构造 Cohere URL 所列形式之外的路径。

AISIX 如何构造 Cohere URL

无论 api_base 使用裸主机根地址（例如 https://api.cohere.com）还是兼容性基础地址（例如 https://api.cohere.ai/compatibility/v1），Cohere 服务提供方密钥都能把 Chat Completions、Embedding 和 rerank 请求发到正确的端点。AISIX 会去掉 api_base 末尾的 /compatibility/v1、/v1 或 /v2 得到主机根地址，再从该根地址构造各路由的 URL：

路由	上游 URL
`/v1/chat/completions`	`<主机根地址>/compatibility/v1/chat/completions`
`/v1/embeddings`	`<主机根地址>/compatibility/v1/embeddings`
`/v1/rerank`	`<主机根地址>/v2/rerank`

带有其他路径的基础地址（例如私有转发代理）会保留该路径，AISIX 按原样在其后追加 /compatibility/v1 或 /v2/rerank。

控制推理强度

Cohere 支持推理的 Command 模型（例如 command-a-reasoning-08-2025 和 command-a-plus-05-2026）在不同 API 接口上以不同方式提供思考能力。AISIX 路由到兼容性 API，因此调用方通过 OpenAI 形态的 reasoning_effort 字段进行控制：

{
  "reasoning_effort": "none"
}

Cohere 兼容性 API 的该字段接受 none 和 high，分别映射为禁用和启用思考。该接口未记录原生 API 的 Token 预算控制，因此请求无法通过兼容性路由限制推理 Token 数量。当前字段行为请参阅 Cohere 的推理文档。

AISIX 会保留响应中的 reasoning_content，并把 reasoning 标准化到该规范字段。Cohere 服务提供方密钥不带推理字段覆盖项。如果模型在其他 delta 路径下传输推理，请在服务提供方密钥上设置 response.reasoning_field。

添加 Rerank 模型

/v1/rerank 路由接受服务提供方值为 openai、cohere 或 jina 的模型，因此该路由允许 Cohere 支持的别名。Cohere rerank 不属于兼容性 API；AISIX 会把请求发到服务提供方密钥 api_base 主机根地址下的 Cohere 原生 v2 rerank 端点，详见 AISIX 如何构造 Cohere URL。因此，为 Chat Completions 创建的服务提供方密钥同样可以用于 rerank。

在 AISIX Cloud 中，在该服务提供方密钥上创建 rerank 模型别名，以及范围仅限该别名的调用方密钥：

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": "cohere-rerank-prod",
    "model_name": "rerank-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": "cohere-rerank-caller",
    "allowed_models": ["'"${RERANK_MODEL_ID}"'"]
  }' | jq -r '.plaintext')

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

resources.yaml（重排序资源）
models:
  - display_name: "cohere-rerank-prod"
    provider: "cohere"
    model_name: "rerank-v3.5"
    provider_key: "cohere-prod"

api_keys:
  - display_name: "cohere-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "cohere-command-a-prod"
      - "cohere-rerank-prod"

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

export RERANK_API_KEY="$CALLER_API_KEY"

Rerank 模型 ID 使用独立于 Command 系列的命名：rerank-v3.5，以及两个 Rerank 4.0 变体 rerank-v4.0-fast 和 rerank-v4.0-pro。该路由会解析到 Cohere v2 rerank 端点，因此在生产别名指向所选 ID 前，请先在 rerank 模型概述中确认该端点提供此 ID。

通过代理发送 rerank 请求：

curl -sS -X POST "$AISIX_PROXY/v1/rerank" \
  -H "Authorization: Bearer ${RERANK_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cohere-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 字段重写为 rerank-v3.5，并原样转发正文，因此 Cohere 的 top_n 参数会按原样到达上游。响应保留 Cohere rerank 形态：一个按 relevance_score 排序的 results 数组以及一个 meta 对象。Cohere 的 rerank 模型以 meta.billed_units.search_units 上报用量，不含 Token 数。AISIX 不对搜索单元定价，因此每个 rerank 请求都会以零 Token 记录在用量日志中：它会与聊天流量一同出现在请求日志中，但不会为预算总计增加成本。如果 Cohere 响应中包含 meta.billed_units.input_tokens，AISIX 会记录该数值。

Cohere 端点支持

对于由 Cohere 服务提供方密钥支持的模型别名，无论 api_base 使用 AISIX 如何构造 Cohere URL 中的哪种形式，以下路由的行为如下。

路由	Cohere 支持模型的行为
`/v1/chat/completions`	通过兼容性 API 提供支持。
`/v1/embeddings`	通过兼容性 API 上 Cohere 的 OpenAI 形态 Embedding 路由提供支持。在 `model_name` 中使用 `embed-v4.0` 等 Cohere Embedding 模型 ID。
`/v1/responses`	通过聊天适配器桥接。AISIX 会返回 Responses 形态结果，而不是转发到原生 Responses API；没有对应聊天语义的 OpenAI Responses 专用字段会被忽略。请参阅 Responses API。
`/v1/rerank`	通过 Cohere 原生 v2 rerank 端点提供支持，使用同一个服务提供方密钥。请参阅添加 Rerank 模型。
`/v1/images/generations`	不支持。该路由只接受服务提供方值为 `openai` 的模型。
`/v1/videos`	不支持。视频路由的服务提供方允许列表中不包含 Cohere。
`/v1/messages`	通过转换支持 Anthropic 形态的调用方。`/v1/messages/count_tokens` 的 Token 计数要求使用 Anthropic 支持的模型。
`/passthrough/cohere/*`	通过已配置的透传路由可用；在调用方 Key 的 `allowed_routes` 上授予该路由。一条路由绑定一个固定的 `target_url` 和服务提供方密钥，因此要同时访问兼容性基础地址和原生根地址，需要在不同前缀下配两条路由。

后续步骤

你已将 AISIX 接入 Cohere，验证了模型别名，并添加了 rerank 路由。接下来可以阅读：

模型别名：为这些别名配置路由、重试行为或成本元数据。
Rerank：查看 rerank 请求契约及其服务提供方要求。
路由和故障转移：在 Cohere 与另一个服务提供方之间进行故障转移。
服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。

准备工作​

使用 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

AISIX 如何构造 Cohere URL​

控制推理强度​

添加 Rerank 模型​

Cohere 端点支持​

后续步骤​