Meta Llama API

Meta Llama API 通过 API Key 认证提供对 Llama 模型的直接托管访问。AISIX 为应用提供稳定的调用方 API，同时保存上游凭证、控制模型访问并记录用量。

前提条件

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

一套 AISIX 环境：
- 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
- 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
Meta Llama API Key，以及计划使用的模型的访问权限。
curl 和 jq。

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

创建模型服务提供方密钥、模型别名和调用方 API Key。

Llama API 是一个提供兼容 OpenAI 端点的社区目录模型服务提供方。AISIX 通过 openai 适配器连接，并使用 Bearer Token 对上游请求进行认证。

创建模型服务提供方密钥

导出上游凭证：

export LLAMA_API_KEY="YOUR_LLAMA_API_KEY"

创建模型服务提供方密钥：

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

echo "$PROVIDER_KEY_ID"

provider 必须是目录 ID llama。不要添加 adapter：AISIX 会为目录模型服务提供方推导出 openai 适配器，并且仅接受 BYO 模型服务提供方密钥显式设置适配器。

API 基础 URL 包含 /compat/v1/。AISIX 会规范化末尾斜杠并追加 /chat/completions，从而生成上游路由 https://api.llama.com/compat/v1/chat/completions。

创建模型

为上游模型创建面向调用方的别名：

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": "llama-api-prod",
      "model_name": "Llama-3.3-70B-Instruct",
      "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
    }' | jq -er '.model.id'
)

echo "$MODEL_ID"

display_name 是应用向 AISIX 发送的稳定别名。model_name 是发送给 Meta 的确切 ID。替换为其他模型前，请查阅 Meta Llama 模型文档，因为可用性可能取决于账户和 API 版本。

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

echo "$AISIX_API_KEY"

明文调用方密钥仅在资源创建时返回。请安全存储。

使用开源 AISIX 网关配置

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

export LLAMA_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

为此模型服务提供方创建完整的声明式资源文件：

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: "llama-api-prod"
    provider: "llama"
    adapter: "openai"
    api_key: ${LLAMA_API_KEY}
    api_base: "https://api.llama.com/compat/v1/"

models:
  - display_name: "llama-api-prod"
    provider: "llama"
    model_name: "Llama-3.3-70B-Instruct"
    provider_key: "llama-api-prod"

api_keys:
  - display_name: "llama-api-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "llama-api-prod"

如果 AISIX 安装在本地，请在加载前验证该文件：

aisix validate --resources resources.yaml

验证后，在网关进程环境中设置所引用的环境变量并启动网关。仅当这些变量已在进程中可用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两个命令中使用 -e 传入它引用的每个环境变量。资源加载后，为下方的通用验证请求做好准备：

export AISIX_API_KEY="$CALLER_API_KEY"

验证模型服务提供方连接

导出 AISIX 网关源地址：

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

通过 AISIX 发送聊天请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer $AISIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-api-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from the Meta Llama API."
      }
    ]
  }'

AISIX 将 llama-api-prod 解析为 Llama-3.3-70B-Instruct，向 Llama API 发送经过 Bearer Token 认证的请求，并返回兼容 OpenAI 的响应。

端点覆盖范围

规范化的 /v1/chat/completions 路由是此模型服务提供方的主要路径。AISIX 还可以通过同一个聊天适配器桥接兼容的 /v1/responses 和 /v1/messages 请求。嵌入需要 Meta 在此 API 基础 URL 上公开相应的模型和端点。

图像生成、视频生成和重排序使用特定于路由的模型服务提供方允许列表，不接受 llama 模型服务提供方值。请参阅模型服务提供方兼容性。

故障排除

现象	检查项
上游返回 `401` 或 `403`	确认 `LLAMA_API_KEY` 有效，并且账户可以使用所选模型。
上游返回 `404`	确认 API 基础 URL 包含 `/compat/v1`，并从 Meta 复制当前模型 ID。
创建模型服务提供方密钥时返回 `400`	使用 `provider: "llama"`，且不设置 `adapter` 字段。
AISIX 返回模型访问被拒绝	确认调用方密钥的 `allowed_models` 包含模型资源 ID。

后续步骤

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

模型别名：为别名配置路由、重试行为或成本元数据。
模型服务提供方密钥：轮换上游凭证或配置模型服务提供方特定的覆盖设置。
模型服务提供方兼容性：查看支持的代理端点和模型服务提供方特定的限制。

前提条件​

使用 AISIX Cloud 配置​

创建模型服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证模型服务提供方连接​

端点覆盖范围​

故障排除​

后续步骤​