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，且末尾不带斜杠
# 本地 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"

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：

# 本地快速入门使用 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": "snowflake-claude-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Snowflake Cortex."
      }
    ]
  }'

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

端点覆盖范围

Snowflake Cortex 的 OpenAI 兼容聊天路由支持通过 AISIX 访问 /v1/chat/completions。兼容的 Responses 和 Messages 请求可以使用 AISIX 中的聊天桥接功能。

AISIX 标准化的 /v1/embeddings 路由与 Snowflake 的 Vector Embed REST API 不兼容。Snowflake 使用 POST /api/v2/cortex/inference:embed 和 Snowflake 原生请求体。请使用服务提供方透传，并配置一个以 https://<account>.snowflakecomputing.com/api/v2/cortex 为 Root 的独立服务提供方密钥，或改用其他嵌入模型服务提供方。

图像生成、视频生成和重排序不接受 snowflake-cortex 服务提供方值。请参阅服务提供方兼容性。

故障排查

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

后续步骤

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

服务提供方密钥：管理账户专用凭证和密钥轮换。
服务提供方透传：访问 AISIX 未标准化的 Snowflake 原生路由。
模型别名：为别名配置路由、重试行为或成本元数据。
服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。

准备工作​

使用 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

端点覆盖范围​

故障排查​

后续步骤​