版本：1.2.0

Ollama

Ollama 在本地或私有基础设施中运行语言模型，并提供 OpenAI 和 Anthropic 兼容 API。Ollama 继续在你的环境中提供推理服务，AISIX 则为其添加调用方密钥、稳定的模型别名、流量控制和用量报告。

准备工作

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

一套 AISIX 环境：
- 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
- 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
在 AISIX 网关可访问的主机上安装 Ollama 0.13.3 或更高版本。该版本开始提供本指南使用的原生 Responses 端点。
curl 和 jq。

准备 Ollama

拉取本指南使用的模型：

ollama pull gpt-oss:20b

Ollama 默认绑定到 127.0.0.1:11434。如果 AISIX 运行在另一个容器或主机上，请按照 Ollama 服务器配置设置可访问的绑定地址。例如，可让前台服务器监听所有网络接口：

OLLAMA_HOST="0.0.0.0:11434" ollama serve

警告

本地 Ollama API 不需要身份验证。绑定到 0.0.0.0 后，其他网络节点也能访问它。请使用防火墙、容器网络或 Kubernetes 策略限制监听网络，不要将该端口直接暴露到公网。

导出一个可从 AISIX 网关访问的 API 根地址：

# Docker Desktop 中的网关访问主机上的 Ollama
export OLLAMA_API_BASE="http://host.docker.internal:11434/v1"

根据部署拓扑选择地址：

AISIX 网关与 Ollama 的部署拓扑	API 根地址示例
两个进程位于同一主机	`http://127.0.0.1:11434/v1`
AISIX 位于 Docker Desktop 中，Ollama 位于主机上	`http://host.docker.internal:11434/v1`
两个容器位于同一 Docker 网络	`http://ollama:11434/v1`
Kubernetes	`http://ollama.<namespace>.svc.cluster.local:11434/v1`

在 Linux 上，host.docker.internal 可能需要显式配置 host-gateway 映射。从笔记本电脑成功发送请求，并不能证明 AISIX 网关容器能够访问同一地址。

使用 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"

Ollama 是私有端点，而不是 AISIX 目录服务提供方。请使用 byo 服务提供方值进行配置，并显式选择 openai 适配器。

创建服务提供方密钥

PROVIDER_KEY_ID=$(
  curl -sS -X POST "$AISIX_CP/provider_keys" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "ollama-local",
      "provider": "byo",
      "adapter": "openai",
      "api_key": "ollama",
      "api_base": "'"${OLLAMA_API_BASE}"'",
      "apis": {
        "responses": {}
      },
      "allowed_environments": ["'"${ENV_ID}"'"]
    }' | jq -er '.provider_key.id'
)

echo "$PROVIDER_KEY_ID"

AISIX 的服务提供方密钥 schema 要求 api_key 非空。Ollama 的 OpenAI 客户端示例使用 ollama，因为客户端要求提供一个值，但本地 Ollama 服务器会忽略该值。AISIX 会将此占位值作为 Bearer Token 发送；它不是安全控制措施。

BYO 密钥要求提供 provider: "byo"、非空的 api_key 和 api_base。本指南显式设置 adapter: "openai"；省略时，AISIX 会默认让 BYO 密钥使用 OpenAI 兼容适配器。apis.responses 声明会把 Responses 请求发送至 Ollama 原生端点，而不是通过 Chat Completions 转换。

创建模型

使用准确的本地 Ollama 模型标签：

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": "ollama-gpt-oss-prod",
      "model_name": "gpt-oss:20b",
      "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
    }' | jq -er '.model.id'
)

echo "$MODEL_ID"

运行 ollama ls 查看已安装的模型标签。标签（包括 :20b 等后缀）会原样发送到上游。

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

echo "$AISIX_API_KEY"

使用开源 AISIX 网关配置

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

export OLLAMA_API_BASE="http://host.docker.internal:11434/v1"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

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

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "ollama-local"
    provider: "ollama"
    adapter: "openai"
    api_key: "ollama"
    api_base: "${OLLAMA_API_BASE}"
    apis:
      responses: {}

models:
  - display_name: "ollama-gpt-oss-prod"
    provider: "ollama"
    model_name: "gpt-oss:20b"
    provider_key: "ollama-local"

api_keys:
  - display_name: "ollama-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "ollama-gpt-oss-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 代理发送 Responses 请求：

curl -sS -X POST "$AISIX_PROXY/v1/responses" \
  -H "Authorization: Bearer $AISIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ollama-gpt-oss-prod",
    "input": "Say hello from Ollama."
  }'

Ollama 应记录 POST /v1/responses。AISIX 会在上游请求中把别名替换为已安装的 Ollama 模型标签，并在响应中恢复该别名。

Ollama 从 0.13.3 版开始提供原生 /v1/responses。该端点支持流式传输、函数工具和推理摘要，但不支持通过 previous_response_id 或 conversation 保存状态。本指南中的声明会在规范化 AISIX 路由上保留这些受支持的原生语义，同时保留别名重写和模型访问控制。

通过透传使用原生 Messages

Ollama 还提供原生 Anthropic 形态的 Messages 路由，但没有 /v1/messages/count_tokens。需要原生 Messages 格式时，请使用透传路由。不要为此工作流声明 apis.messages，也不要创建使用 anthropic 适配器的单独别名；这两种方式都表示包括 Count Tokens 在内的完整 Messages 协议面。参见声明 API 协议面。

透传不会重写 AISIX 别名，因此请发送已安装的 Ollama 模型标签。Ollama 的其他 Messages 限制仍然适用：它不支持强制 tool_choice、提示词缓存、引用和 Messages 批处理；扩展思考预算虽会被接受，但不会强制执行。

端点覆盖范围

Ollama 文档列出了 OpenAI 兼容的 Chat Completions、Completions、Responses、Models 和 Embeddings 路由，还提供 Anthropic 兼容的 Messages 路由。本指南的服务提供方密钥仅声明原生 Responses；其他路由继续遵循 openai 适配器或下表中的路由特定行为。

路由	使用本指南 Ollama 别名时的行为
`/v1/chat/completions`	支持；当已安装模型支持时，可使用流式传输、工具、结构化输出、视觉和推理控制项。
`/v1/completions`	通过 OpenAI 适配器提供支持。Ollama 的 `prompt` 只接受字符串。
`/v1/embeddings`	当别名指向已安装的 Embedding 模型时受支持。Ollama 和 AISIX 均接受字符串或字符串数组。
`/v1/responses`	由于本指南声明了 `apis.responses`，请求会发送至 Ollama 原生 Responses API。如果没有此声明，AISIX 会使用 Responses 桥接。
`/v1/messages`	因为此服务提供方密钥使用 `adapter: openai`，所以通过 Chat 转换。Ollama 原生 Messages 格式请按上文使用透传。
`/v1/messages/count_tokens`	`openai` 适配器会拒绝该路由。即使使用单独的 Anthropic 适配器，Ollama 当前也未实现此端点。
`/v1/models`	返回调用方可访问的 AISIX 模型别名，而不是 Ollama 中安装的模型。请使用 `ollama ls` 或透传路由查询 Ollama 模型清单。
`/v1/images/generations`、`/v1/rerank`	返回 `400`，因为标准化路由不接受本指南的服务提供方标签（AISIX Cloud 中为 `byo`，资源文件中为 `ollama`）。
`/v1/videos`	返回 `501 not_implemented`，因为这两个服务提供方标签均不在视频路由允许列表中。
`/v1/audio/*`、`/v1/files`、`/v1/batches`、`/v1/fine_tuning/jobs`	AISIX 可以转发这些 OpenAI 形态的路由，但 Ollama 未发布对应 API，上游会拒绝请求。
`/passthrough/byo/*`	通过已配置的透传路由可用于 Ollama 原生路由。约定前缀在 AISIX Cloud 中为 `/passthrough/byo`，开源资源文件中为与本页服务提供方标签一致的 `/passthrough/ollama`。

Ollama 的 OpenAI 兼容 Chat 路由当前不支持 tool_choice、logit_bias、user 或 n。AISIX 可以转发这些字段，但转发不会增加上游能力。使用视觉模型时，请在 image_url 内容部分发送 Base64 图像；Ollama 不支持在此路由上使用远程图像 URL。

上述 /passthrough 路径假定一条透传路由认领所选前缀，target_url 设为 Ollama 根地址；在调用方 Key 的 allowed_routes 上授予路由名称。透传不会重写请求体中的 AISIX 别名，路由总是以其固定目标和绑定的服务提供方密钥中继，与请求的模型无关。它会增量中继包括 SSE 在内的上游响应。AISIX 会检测 Chat、Completions 和 Responses 信封，并记录受支持的用量字段。没有可识别载体字段的请求保持不透明：缓冲响应记录零 Token，而不透明 SSE 仍可记录顶层受支持的 usage 字段。当需要别名重写、Token 核算或 AISIX 成本估算时，请优先使用标准化路由。Ollama 是没有目录定价的 BYO 端点；需要成本估算时，请在 AISIX Cloud 中配置模型定价，或在开源模型资源中配置 cost 元数据。

故障排除

现象	检查项
连接被拒绝或超时	从 AISIX 网关容器内测试 `OLLAMA_API_BASE`，不要只在主机上测试。
Ollama 仅监听 `127.0.0.1`	通过受支持的服务配置设置 `OLLAMA_HOST`，然后重启 Ollama。
找不到模型	运行 `ollama pull gpt-oss:20b`，并使用 `ollama ls` 验证标签。
创建服务提供方密钥时返回 `400`	请包含 `provider: "byo"`、`adapter: "openai"`、非空的 `api_key` 和 `api_base`。

后续步骤

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

自带端点：查看适用于私有 OpenAI 兼容服务器的可复用配置。
模型别名：为别名配置路由、重试行为或成本元数据。
路由与故障转移：在 Ollama 和提供同一模型的其他服务提供方之间进行故障转移。
服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。

准备工作​

准备 Ollama​

使用 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

通过透传使用原生 Messages​

端点覆盖范围​

故障排除​

后续步骤​