Meta Llama API

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

本页介绍 api.llama.com 上的 Llama API，不涵盖 Meta 在 api.meta.ai 上提供的独立 Model 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。

请勿将该基础地址替换为 https://api.llama.com/v1。后者采用 Meta 原生 Llama API 协议，其 Chat 响应和流式事件结构不同于 OpenAI Chat Completions。AISIX openai 适配器要求使用 /compat/v1 接口。

创建模型

列出上游账号可用的模型：

curl -sS "https://api.llama.com/compat/v1/models" \
  -H "Authorization: Bearer ${LLAMA_API_KEY}" \
  | jq -r '.data[].id'

为返回的某个模型 ID 创建面向调用方的别名。此示例使用 Meta 当前官方 Llama API 客户端示例中的 Llama 4 Maverick 模型：

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-4-Maverick-17B-128E-Instruct-FP8",
      "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
    }' | jq -er '.model.id'
)

echo "$MODEL_ID"

display_name 是应用向 AISIX 发送的稳定别名。model_name 是发送给 Meta 的确切且区分大小写的 ID。请使用该账号 /models 请求返回的 ID，因为可用性可能因账号和 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-4-Maverick-17B-128E-Instruct-FP8"
    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-4-Maverick-17B-128E-Instruct-FP8，向 Llama API 兼容端点发送经过 Bearer Token 认证的请求，并返回兼容 OpenAI 的响应。

端点覆盖范围

配置的 API 根地址是 Meta 的 OpenAI 兼容接口。AISIX 路由行为如下：

路由	使用 llama 模型别名时的行为
/v1/chat/completions	通过 Meta /compat/v1/chat/completions 路由支持。Llama 4 模型可在 Chat 中接受图片内容块；这是视觉输入，不是图片生成。
/v1/responses	通过 AISIX 跨服务提供方桥接支持，该桥接会将请求转换为 Chat Completions，再把结果转换回 Responses 结构。AISIX 不会把此请求转发到 Meta Responses 路由。没有 Chat 等价项的 OpenAI 特定字段会被忽略。
/v1/messages	通过 AISIX Anthropic 到 Chat 的转换支持。/v1/messages/count_tokens 仍仅限 Anthropic 后端目标。
/v1/embeddings 和 /v1/completions	不支持。Meta /compat/v1 根地址不提供这些路由。
/v1/audio/*、/v1/images/generations、/v1/videos 和 /v1/rerank	不支持。路由特定的服务提供方门禁或 Meta 端点覆盖范围不接受此配置。
/v1/batches	不支持。Meta 兼容根地址不提供此路由。
/v1/files 和 /v1/fine_tuning/jobs	尚未验证。Meta 兼容根地址提供匹配路由，但此 AISIX 工作流尚未完成端到端验证，且上游缺少文件内容路由。在测试所需操作前请勿依赖。
/passthrough/llama/*rest	通过以 /compat/v1 基础地址为目标的已配置透传路由可用，可用于 AISIX 未建模的 /moderations 等兼容 Meta 路由。透传会保留请求体和响应体。可识别的 Chat、Completions 和 Responses 信封会记录受支持的用量字段。没有可识别载体字段的请求保持不透明：缓冲响应记录零 Token，而不透明 SSE 仍可记录顶层受支持的 usage 字段。

透传不会重写 model 字段，因此原生操作需要模型时请发送确切的上游模型 ID。/passthrough/llama 前缀假定一条透传路由认领它：target_url 设为 /compat/v1 基础地址，凭证注入使用此服务提供方密钥；在调用方 Key 的 allowed_routes 上授予该路由。如果为 Meta 原生 /v1 资源添加第二个 llama 密钥，请在独立前缀下再建一条路由并绑定那把密钥。不要将规范化 Chat 路由到原生密钥，因为其响应协议不兼容 OpenAI。

转换与端点详情请参阅 Responses、Anthropic Messages和模型服务提供方兼容性。

故障排除

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

后续步骤

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

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