文本补全

有些应用会发送单个提示词，并期望收到文本补全响应，而不是聊天消息响应。AISIX AI 网关通过 completions 代理路由支持这种 OpenAI 兼容请求形态。

文本补全主要适用于已有的基于提示词的客户端。对于新的对话式应用，Chat Completions 路由通常能提供更广泛的服务提供方支持和更适合聊天场景的客户端能力。

准备工作

请先准备以下内容：

一个可以处理代理请求的 AISIX 网关。
一个可以访问该模型别名的调用方 API Key。
一个由支持文本补全的服务提供方和模型支撑的模型别名。

导出网关连接和请求值：

# AISIX_PROXY 末尾不含斜杠，也不包含 /v1 等端点路径。
# 本地快速入门使用 http://127.0.0.1:3000。
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="text-prod"

发送文本补全请求

通过网关代理发送请求，并在请求体中使用 AISIX 模型别名：

curl -sS -X POST "${AISIX_PROXY}/v1/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "prompt": "Write one sentence about API gateways.",
    "max_tokens": 40
  }'

AISIX 会解析模型别名、检查调用方 API Key、改写上游模型 ID，并将剩余请求体转发到服务提供方的 completions 端点。

响应会保持 OpenAI 兼容的文本补全格式：

{
  "id": "cmpl-***",
  "object": "text_completion",
  "model": "text-prod",
  "choices": [
    {
      "text": "API gateways help manage, secure, and observe traffic between clients and services.",
      "index": 0,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 7,
    "completion_tokens": 13,
    "total_tokens": 20
  }
}

服务提供方与网关行为

Text Completions 路由是 OpenAI 兼容代理路径。支持 completions 的服务提供方可以通过已配置适配器接收请求。不支持 completions 的服务提供方会返回 501，错误类型为 not_implemented。

该路由不支持流式。设置了 stream: true 的请求会在 AISIX 调用服务提供方之前被拒绝并返回 400，因此服务提供方不会生成响应，也不会因此产生费用：

{
  "error": {
    "message": "request payload is invalid: `stream` is not supported on /v1/completions; use /v1/chat/completions for streaming",
    "type": "invalid_request_error"
  }
}

设置 stream: false 或未包含 stream 字段的请求不受影响，仍按原有方式转发。需要流式输出时，请使用 OpenAI 兼容 API。

输入安全护栏可以在 AISIX 调用服务提供方之前检查字符串提示词。包含字符串的提示词数组也可以被检查。Token ID 提示词会被转发，但其中不包含可供安全护栏扫描的文本。

输出安全护栏会在 AISIX 返回补全文本前扫描它，行为与 Chat Completions 路径相同。如果输出安全护栏阻断响应，AISIX 会返回 422。此时服务提供方已经生成响应并产生费用，因此该请求的 Token 用量仍会被记录。

成功响应会保持 OpenAI 兼容的 completions 响应格式。当上游响应包含 Token 用量时，AISIX 会记录该请求的用量。

文本补全行为

当应用可以发送基于 role 的消息、使用工具、流式返回 assistant 输出，或希望覆盖最广泛的服务提供方后端时，建议使用 Chat Completions。

如果请求返回 501，说明解析出的服务提供方适配器不支持文本补全。请使用由支持 completions 的服务提供方支撑的模型，或将应用迁移到 Chat Completions。

如果输入安全护栏没有阻断提示词，请检查提示词是否包含可检查文本。字符串提示词和字符串数组可以被扫描；Token ID 提示词数组不会向输入安全护栏暴露文本。

下一步

你已经了解何时通过 AISIX 使用文本补全，以及为什么新集成通常更适合默认选择 Chat Completions。主要聊天链路请参见 OpenAI 兼容 API。

准备工作​

发送文本补全请求​

服务提供方与网关行为​

文本补全行为​

下一步​

准备工作

发送文本补全请求

服务提供方与网关行为

文本补全行为

下一步