跳到主要内容
版本：1.7.0

Snowflake Cortex

Snowflake Cortex 将托管基础模型引入 Snowflake 账户，并通过 REST API 公开这些模型。AISIX 为应用提供一个 OpenAI 兼容 API，用于访问你账户中可用的模型。

准备工作​

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

  • 一套 AISIX 环境：
    • 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
    • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
  • Snowflake 账户标识符和编程访问 Token（PAT）。
  • 允许使用 Cortex 的 Snowflake 角色。Snowflake 文档说明了 SNOWFLAKE.CORTEX_USER 数据库角色和 REST API 用户角色要求。
  • 在你的 Snowflake 区域中访问所选模型的权限。
  • curl 和 jq。

导出 Snowflake 连接信息：

export SNOWFLAKE_ACCOUNT="example-account"
export SNOWFLAKE_API_BASE="https://${SNOWFLAKE_ACCOUNT}.snowflakecomputing.com/api/v2/cortex/v1"
export SNOWFLAKE_PAT="YOUR_SNOWFLAKE_PROGRAMMATIC_ACCESS_TOKEN"

使用 Snowflake 连接信息中的账户主机名。SNOWFLAKE_ACCOUNT 中不要包含 https:// 或其他路径。

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

Snowflake 是提供 OpenAI 兼容 Cortex 端点的社区目录服务提供方。AISIX 通过 openai 适配器连接，使用 Bearer Token 对上游请求进行身份认证，并将账户专用主机名用作 api_base。

创建服务提供方密钥​

PROVIDER_KEY_ID=$(
  curl -sS -X POST "$AISIX_CP/provider_keys" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "snowflake-cortex-prod",
      "provider": "snowflake-cortex",
      "api_key": "'"${SNOWFLAKE_PAT}"'",
      "api_base": "'"${SNOWFLAKE_API_BASE}"'",
      "allowed_environments": ["'"${ENV_ID}"'"]
    }' | jq -er '.provider_key.id'
)

echo "$PROVIDER_KEY_ID"

snowflake-cortex 是准确的目录 ID。snowflake 不是它的别名。AISIX 会推导出 openai 适配器，因此请省略 adapter 字段。

实际使用时必须提供账户专用的 api_base，因为 AISIX 无法推断哪个 Snowflake 账户应接收请求。AISIX 会在此 Root 后追加 /chat/completions。

AISIX_TOKEN 是 AISIX 管理 Token。SNOWFLAKE_PAT 是存储在服务提供方密钥中的上游凭证。尽管二者都可能被称为 PAT，但它们是互不相关的 Token 类型。

创建模型​

为账户中可用的 Cortex 模型创建别名：

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": "snowflake-claude-prod",
      "model_name": "claude-sonnet-4-5",
      "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
    }' | jq -er '.model.id'
)

echo "$MODEL_ID"

Snowflake 支持的模型列表因区域和版本而异。只能将 claude-sonnet-4-5 替换为你账户可用的 ID，并从当前的 Cortex 模型可用性参考中复制其准确拼写。

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

echo "$AISIX_API_KEY"

使用开源 AISIX 网关配置​

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

export SNOWFLAKE_PAT="YOUR_SNOWFLAKE_PROGRAMMATIC_ACCESS_TOKEN"
export SNOWFLAKE_ACCOUNT="YOUR_SNOWFLAKE_ACCOUNT"
export SNOWFLAKE_API_BASE="https://${SNOWFLAKE_ACCOUNT}.snowflakecomputing.com/api/v2/cortex/v1"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

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

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "snowflake-cortex-prod"
    provider: "snowflake-cortex"
    adapter: "openai"
    api_key: ${SNOWFLAKE_PAT}
    api_base: "${SNOWFLAKE_API_BASE}"

models:
  - display_name: "snowflake-claude-prod"
    provider: "snowflake-cortex"
    model_name: "claude-sonnet-4-5"
    provider_key: "snowflake-cortex-prod"

api_keys:
  - display_name: "snowflake-cortex-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "snowflake-claude-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": "snowflake-claude-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Snowflake Cortex."
      }
    ]
  }'

AISIX 会转发 Snowflake 模型 ID，并使用 Authorization: Bearer <SNOWFLAKE_PAT> 进行身份认证。

端点覆盖范围​

Snowflake 同时提供 OpenAI 兼容的 Chat Completions 和仅支持 Claude 的 Anthropic Messages API。snowflake-cortex 目录条目使用 openai 适配器，因此标准化路由行为不同于 Snowflake 原生界面：

路由使用 Snowflake Cortex 别名时的行为
/v1/chat/completions通过 Snowflake OpenAI 兼容 Chat 路由提供支持，包括缓冲和流式传输。
/v1/responses通过 AISIX Responses 桥接提供支持。Snowflake 不提供原生 Responses 端点；没有对应 Chat Completions 语义的字段会被忽略。
/v1/messages通过转换到 Chat Completions 提供支持，而不是使用 Snowflake 原生 Messages 路由。需要 Snowflake 原生 Anthropic 契约或 Beta 功能的 Claude 别名，应通过 /passthrough/snowflake-cortex/messages 调用，并发送准确的上游模型 ID 和必需的 anthropic-version: 2023-06-01 请求头。
/v1/messages/count_tokens不支持。Token 计数仅限适配器配置为 Anthropic 的模型。
/v1/embeddings与 Snowflake 的 Vector Embed REST API 不兼容。Snowflake 使用 POST /api/v2/cortex/inference:embed 和原生请求体。请通过一条独立的透传路由访问：其 target_url 设为 https://<account>.snowflakecomputing.com/api/v2/cortex——路由只中继到一个固定基础地址，因此给这条路由独立的路径前缀——然后在该前缀下调用原生 inference:embed 路径；也可以改用其他 Embedding 服务提供方。
/v1/images/generations、/v1/videos、/v1/rerank不支持。这些路由不接受 snowflake-cortex 服务提供方值。
/passthrough/snowflake-cortex/*rest通过已配置的透传路由可用于 Snowflake 原生路由，网关标准化有限。当原生 API 需要不同 Base URL 时，请在独立前缀下另建一条路由。

本页的 /passthrough/snowflake-cortex 路径假定一条透传路由认领该前缀，target_url 设为本指南的 api_base；在调用方 Key 的 allowed_routes 上授予路由名称。

完整端点和服务提供方矩阵请参阅服务提供方兼容性。

故障排查​

现象检查项
DNS 错误或上游返回 404确认 SNOWFLAKE_ACCOUNT 生成的主机名与 Snowflake 连接信息中显示的主机名相同。
上游返回 401轮换 Snowflake PAT 并更新服务提供方密钥。
上游返回 403确认该 Token 对应的用户和角色具有 Cortex 权限及模型访问权限。
模型不可用选择 Snowflake 账户所在区域支持的模型。
创建服务提供方密钥时返回 400使用 provider: "snowflake-cortex" 并省略 adapter。

后续步骤​

现在，你已将 AISIX 连接到 Snowflake Cortex，并验证了模型别名。请继续阅读以下指南：