Ollama

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

准备工作

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

一套 AISIX 环境：
- 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
- 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
在 AISIX 网关可访问的主机上安装 Ollama。
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，且末尾不带斜杠
# 本地 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"

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}"'",
      "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 兼容适配器。

创建模型

使用准确的本地 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}"

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：

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

通过 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": "ollama-gpt-oss-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Ollama."
      }
    ]
  }'

Ollama 应记录 POST /v1/chat/completions，AISIX 应返回 OpenAI 兼容响应。

端点覆盖范围

Ollama 文档列出了 OpenAI 兼容的 Chat Completions、Completions、Responses、Models 和 Embeddings 路由。通过 AISIX 使用时，Chat Completions 是主要路由；桥接后的 Responses 和 Messages 请求使用相同的 Chat 适配器。Embeddings 需要安装 Embedding 模型。

即使 Ollama 实现了名称相似的端点，AISIX 标准化的图像、视频和重排序路由也不接受 byo 服务提供方值。请参阅服务提供方兼容性。

故障排除

现象	检查项
连接被拒绝或超时	从 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 网关配置​

验证服务提供方连接​

端点覆盖范围​

故障排除​

后续步骤​