版本：1.8.0

Mistral AI

Mistral AI 开发并托管 Mistral 模型系列。AISIX 使应用能够使用网关签发的调用方密钥调用其 Chat 和兼容 API 接口。

准备工作

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

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

使用 AISIX Enterprise 或 AISIX Cloud 配置

导出控制面连接信息：

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

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

由于 Mistral 提供兼容 OpenAI 的 API，AISIX 通过 openai 适配器连接，并将 Mistral API 根地址用作 api_base。

创建服务提供方密钥

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

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

echo "$PROVIDER_KEY_ID"

❶ provider 为 mistral。AISIX Cloud Admin API 会从目录服务提供方推导适配器；适配器字段仅接受用于 BYO 服务提供方密钥。

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

❸ api_base 已包含 /v1 路径。AISIX 会向其追加 /chat/completions。对于此目录服务提供方，该字段是可选的，因为省略时 AISIX Cloud Admin API 会填入相同的值；但示例显式设置该字段，使上游根地址在资源中保持可见。

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

创建模型

以 -latest 结尾的 Mistral 模型 ID 会跟踪该模型的最新快照。如需固定特定版本，请使用 Mistral 模型列表中带日期的模型 ID。

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

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": "mistral-large-prod",
    "model_name": "mistral-large-latest",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

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

❷ model_name 是 Mistral 模型 ID，例如 mistral-large-latest 或 mistral-small-latest。如果对 mistral-small-latest 使用结构化推理，请先阅读了解结构化响应，再启用该功能。

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

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

echo "$AISIX_API_KEY"

allowed_models 值必须引用上一步保存的模型 ID。

网关会自动获取新资源，无需重启。

使用开源 AISIX 网关配置

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

export MISTRAL_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

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

resources.yaml
_format_version: "1"

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

models:
  - display_name: "mistral-large-prod"
    provider: "mistral"
    model_name: "mistral-large-latest"
    provider_key: "mistral-prod"

api_keys:
  - display_name: "mistral-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "mistral-large-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": "mistral-large-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Mistral."
      }
    ]
  }'

网关返回兼容 OpenAI 的响应，其中会回显面向调用方的别名 mistral-large-prod。如果请求失败，请检查服务提供方密钥的 api_key、api_base，以及 model_name 中的 Mistral 模型 ID。

了解结构化响应

当 message.content 或每个流式 delta.content 为字符串时，标准 Mistral Chat 响应可通过规范化 AISIX 端点正常工作。文本和 OpenAI 风格的图片输入块会转发给 Mistral Large 3 等兼容的多模态模型。

当前 Mistral 推理模型可能返回不同的数据结构。当设置 reasoning_effort: "high" 时，Mistral 会在 content 中返回由 ThinkChunk 和 TextChunk 对象组成的数组。非流式响应到达各规范化端点时的处理如下：

/v1/chat/completions 在 message.content 中按 Mistral 发送的原样返回该数组。AISIX 不会把思考块转换为 reasoning_content。
/v1/messages 把文本作为 text 块返回，把思考块作为 signature: "" 的 thinking 块返回，参见 Anthropic Messages。
/v1/responses 把文本作为 output_text 返回，把思考块作为 reasoning 输出项返回，参见 Responses API。

思考文本还会被内容导出器作为推理内容采集；Mistral 未上报用量时，也会计入估算的补全 Token 数。response.reasoning_field 覆盖设置无法转换内容数组。1.7.0 及更早版本的网关会对这些响应返回上游解码错误。

流式响应的 delta.content 为此类数组时，每个端点都会保持各块的原始顺序。/v1/chat/completions 把 text 块的文本作为 delta.content 返回，把思考块作为 delta.reasoning_content 返回，因此流式答复与非流式答复的结构不同。Chat delta 中没有承载块 signature 的字段，因此不会返回签名。/v1/messages 把思考内容以 thinking 块流式返回，/v1/responses 把它以 reasoning 项流式返回。内容导出器和估算的补全 Token 数对流式思考内容的处理与非流式答复相同。

在 /v1/chat/completions 上，assistant 轮次中回放的 Mistral 思考块会经过输入安全护栏检查，参见推理与思考内容。

对于 mistral-small-latest 等支持推理的模型，如果不需要其推理内容，请在规范化端点上使用 reasoning_effort: "none"。如需按 Mistral 发送的原样获取思考块（包括流式响应），请通过 /passthrough/mistral/chat/completions 调用 Mistral 原生 Chat 协议，并发送上游 Mistral 模型 ID，而非 AISIX 别名。本页的 /passthrough/mistral 路径假定一条透传路由认领该前缀，target_url 设为 Mistral 的 API 根地址；在调用方 Key 的 allowed_routes 上授予路由名称。路由会保留响应体，原生流式响应增量中继。

Mistral 还支持大于 1 的 n。/v1/chat/completions 会返回全部选项，/v1/messages 和 /v1/responses 只承载一个答复，返回第一个选项。参见完整返回上游答复。

端点覆盖

本指南中的模型别名对应 Chat 模型。请为嵌入、转录、语音或其他能力创建使用相应 Mistral 模型 ID 的独立别名。

路由	使用 Mistral 别名时的行为
`/v1/chat/completions`	支持，包括 `stream: true`、函数工具，以及所选模型支持的文本或图片输入。非流式的结构化推理响应按 Mistral 发送的原样返回；流式响应把思考内容作为 `delta.reasoning_content` 返回。
`/v1/responses`	通过 Responses 桥接支持。该桥接会转换为 Chat Completions，而非调用原生 Mistral Responses API。没有 Chat 等价项的字段会被忽略。结构化推理响应无论是否流式，都会把思考内容作为 `reasoning` 项返回。
`/v1/messages`	通过转换为 Chat Completions，为采用 Anthropic 协议的调用方提供支持。结构化推理响应无论是否流式，都会把思考内容作为 `thinking` 块返回。该别名以 OpenAI 为后端，因此 `/v1/messages/count_tokens` 会返回 400 错误。
`/v1/embeddings`	使用 `mistral-embed` 等独立别名时支持。AISIX 会转发 `dimensions`，但 Mistral 将缩减维度字段命名为 `output_dimension`；如需使用，请配置请求参数重命名。
`/v1/audio/transcriptions`	使用 `voxtral-mini-latest` 等转录别名时支持。AISIX 会中继 Mistral 响应，包括服务提供方特定字段，但会缓冲流式响应，而非逐步中继事件。
`/v1/audio/translations`	不支持，因为 Mistral 未发布此路由。
`/v1/audio/speech`	路径可到达 Mistral TTS，但协议不兼容 OpenAI。请发送 `voice_id` 等原生字段，并预期获得 Base64 JSON 或经过缓冲的 Mistral SSE 负载，而非原始音频字节。AISIX 不会转换该协议。
`/v1/files`	支持上传、列出、检索、删除和内容下载。Mistral 的 `/v1/files/{id}/url` 签名 URL 路由可通过透传路由访问，但需要原始 Mistral 文件 ID。透传路由不会解码规范化上传所返回的 AISIX 路由 ID。
`/v1/batches`	不支持。AISIX 转发 OpenAI `/v1/batches` 路径，而 Mistral 使用 `/v1/batch/jobs`。
`/v1/fine_tuning/jobs`	不支持。AISIX 转发 OpenAI 作业接口并要求 `training_file`；Mistral 当前公开 API 未发布兼容的微调作业路由。
`/v1/completions`	不支持。Mistral 代码补全使用原生 `/v1/fim/completions` 协议。
`/v1/images/generations`	会返回 400 错误，因为该路由只接受 `openai` 服务提供方模型。Mistral 图片生成是内置工具，而非此 OpenAI 图片路由。
`/v1/rerank`	会返回 400 错误，因为该路由不接受 `mistral` 服务提供方。Mistral 提供分类 API，而非此重排协议。
`/passthrough/mistral/*`	通过已配置的透传路由可用于原生 Mistral 路由及原始请求和响应体。服务提供方 SSE 响应增量中继。

透传路由适用于 Mistral 原生 OCR、内容审核、分类、FIM、批处理、Agents、Conversations 和结构化推理。例如，使用以 https://api.mistral.ai/v1 为目标的路由时，/passthrough/mistral/ocr 和 /passthrough/mistral/v1/ocr 都会解析为 https://api.mistral.ai/v1/ocr，因为 AISIX 会移除一个重复的版本路径段。

AISIX 不会重写透传请求体中的 model 值。路由提供上游基础 URL，inject 模式下还提供服务提供方密钥凭证；一条路由绑定一个目标和凭证，因此不同的 Mistral 账号或基础地址请配置独立路由。哪些请求形态会记录 Token 用量，参见信封识别与用量。

后续步骤

现在，你已将 AISIX 连接到 Mistral，并验证了模型别名。接下来可阅读以下指南：

模型别名：为此别名配置路由、重试行为或成本元数据。
路由和故障转移：在 Mistral 和第二个服务提供方之间配置故障转移。
服务提供方特定覆盖项：当上游 API 与其适配器不同时，调整请求和响应形态。
服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。

准备工作​

使用 AISIX Enterprise 或 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

了解结构化响应​

端点覆盖​

后续步骤​