Llama API 接入教程：Base URL、模型名与第一次调用（2026）

“Llama API 接入”最常见的失败，不是模型能力不够，而是三个参数没对齐：Base URL、鉴权方式、模型名。2026 年 7 月 Meta 的 Llama API 公共预览下线后，Llama 的调用入口分散到云厂商、推理平台、自建服务和 OpenAI 兼容网关。它们的请求形状接近，但细节并不完全一致。

本文按“确认入口、拼 URL、找模型名、发第一次请求、处理流式与工具调用、排查错误、从旧接口迁移”的顺序走一遍。示例使用 OpenAI 兼容接口，模型清单和价格以站内模型价格为准。

说明：Meta、Llama 是 Meta Platforms, Inc. 的商标；Groq、OpenRouter、AWS、Google Cloud 等名称分别为其权利人的商标。本文仅作技术说明，与上述平台不存在隶属、代理或背书关系。

一、接入前先确认三件事

无论用哪家，先把三件事写进配置：

Base URL：协议、域名、路径前缀，通常以 /v1 结尾。
鉴权：Bearer Token、IAM 签名、服务账号，三者不能混用。
模型名：平台内部的模型 ID，不是宣传页上的产品名。

再加两项非技术确认：数据经过哪些区域和节点，以及模型的版本生命周期。前者影响合规，后者影响你半年后是否要迁移。

二、Base URL：SDK 会自动补路径

OpenAI SDK 的 base_url 只写到版本前缀，SDK 会在后面拼 /chat/completions。所以：

正确：https://api.groq.com/openai/v1
错误：https://api.groq.com/openai/v1/chat/completions（会变成双路径）
错误：https://api.groq.com/openai（少了 /v1，多数平台返回 404）

不同平台的路径前缀不同：Groq 是 /openai/v1，OpenRouter 是 /api/v1，自建 vLLM 默认是 /v1。云厂商的端点更复杂，Vertex AI 的 OpenAI 兼容地址包含项目、区域和端点路径，不能只抄域名。最稳妥的做法是从控制台的“示例请求”里复制完整 Base URL，再用最小请求验证。

三、模型名：每个平台都不一样

同一个 Llama 模型，在不同平台的写法可能完全不同：

入口	Base URL 示例	模型名示例	备注
Groq	`https://api.groq.com/openai/v1`	`llama-3.3-70b-versatile`	以当前模型列表为准
OpenRouter	`https://openrouter.ai/api/v1`	`meta-llama/llama-3.3-70b-instruct`	聚合路由，注意前缀
vLLM 自建	`http://localhost:8000/v1`	由 `--served-model-name` 指定	不写就用权重路径
AWS Bedrock	`https://bedrock-runtime.us-east-1.amazonaws.com`	`us.meta.llama4-scout-17b-instruct-v1:0`	用 Invoke/Converse，非 OpenAI 兼容
兼容网关	`https://ai.zhongshangqihang.com/v1`	以控制台模型列表为准	一个 Key 多模型

模型名要区分大小写、版本号、量化和推理变体。Llama-3.3-70B-Instruct、llama-3.3-70b-versatile、meta-llama/llama-3.3-70b-instruct 指的可能不是同一个部署。不要从博客里抄一个 ID 就上线，先在控制台或 GET /models 接口确认。

还要看生命周期。Google Cloud 已公告 llama-3.3-70b-instruct-maas 于 2026 年 10 月 21 日退役；AWS 的 Llama 4 Scout 处于 Legacy 阶段，公告的终止支持日期是 2027 年 3 月 30 日。把模型 ID 放进配置，不要散落在业务代码里，迁移时才不用全仓库搜索。

四、第一次调用：先跑通 curl

准备一个测试 Key，把它放进环境变量，避免出现在命令历史里：

export LLAMA_API_KEY="你的密钥"

curl -s https://api.groq.com/openai/v1/chat/completions \
  -H "Authorization: Bearer $LLAMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b-versatile",
    "messages": [{"role": "user", "content": "用一句话解释什么是 OpenAI 兼容接口"}],
    "max_tokens": 128
  }'

返回的 JSON 里重点看四个字段：choices[0].message.content 是否有内容，finish_reason 是 stop 还是 length，usage 是否统计了输入输出 Token，model 是否与你请求的一致。如果平台返回的 model 与你写的不一样，可能发生了路由或别名替换，账单和评测都会受影响。

五、Python SDK：把差异放进配置

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LLAMA_API_KEY"],
    base_url=os.environ["LLAMA_BASE_URL"],
)

resp = client.chat.completions.create(
    model=os.environ["LLAMA_MODEL"],
    messages=[{"role": "user", "content": "用一句话解释什么是 OpenAI 兼容接口"}],
    max_tokens=128,
    timeout=60,
)
print(resp.choices[0].message.content)

三个工程习惯能让后续少踩坑：显式设置超时；给重试设上限并只重试可重试错误；把 base_url、model、max_tokens 全部放进配置。不要用无限重试，也不要对 400 这类参数错误重试。

另外注意参数名差异。有的平台只接受 max_tokens，有的已转向 max_completion_tokens；有的对 temperature 范围、stop 数量或消息角色有限制。以目标平台的接口文档为准，不要假设 OpenAI 的参数可以原样透传。

六、流式输出：逐块处理，别等整段

开启 stream=True 后，服务端通常以 Server-Sent Events 返回，每行以 data: 开头，最后以 data: [DONE] 结束。客户端要逐块读取 choices[0].delta.content，并处理空块、心跳和连接中断。三个常见问题：

把 delta.content 当成一定存在，遇到 None 就报错。
代理或网关缓冲了响应，前端看起来“没有流式”，实际是整段到达。
客户端断开后服务端仍在生成，导致额度浪费；要在业务层设置取消和超时。

如果使用网关，先确认它是否透传 SSE，以及是否改写错误事件。流式接口的兼容性比非流式更容易出问题，上线前单独测一轮。

七、工具调用：先确认平台真的支持

OpenAI 风格的 tools 参数不是所有 Llama 托管商都完整支持。调用前确认三件事：模型本身支持工具调用，平台透传了 tools 和 tool_choice，返回的 finish_reason 能出现 tool_calls。

模型返回的工具参数通常是 JSON 字符串，不是对象。后端要先做 JSON 解析和 schema 校验，再执行真实函数；不要直接把模型输出拼进 SQL、Shell 或内部接口。工具执行要有超时、幂等和权限边界，失败结果要回传给模型，让它决定重试还是改参数。并行工具调用、严格 schema、流式工具调用这三项，各平台差异最大，必须逐个验证。

八、常见错误：先看状态码，再看响应体

401：Key 缺失、格式错误、来自其他平台或已被吊销。
404：Base URL 多写或少写 /v1，或模型名不存在。
400：参数不被支持，例如 max_tokens 与 max_completion_tokens 混用、消息角色不合法。
403：Key 有效，但没有目标模型、项目或区域的权限。
429：触发速率或并发限制。读取 Retry-After，用指数退避加随机抖动，不要固定间隔猛重试。
5xx：上游故障或超时。只重试幂等请求，并记录请求 ID。
200 但内容为空：可能是 finish_reason=length、内容过滤或流式解析错误。

排查顺序建议从外到内：先用 curl 绕过业务代码，再换官方 SDK，最后才怀疑提示词。把请求 ID、状态码、模型名和 Base URL 记进日志，否则跨平台问题很难复现。

九、从旧 Llama API 迁移：按顺序做

搜索代码和配置中的 api.llama.com、/compat/v1 和旧模型名，列出所有调用点。
在新平台创建 Key，确认 Base URL 和模型名，先用 curl 跑通一条最小请求。
建立模型映射表，记录新模型 ID、上下文上限、输出上限、是否支持流式和工具调用。
替换 Base URL 与鉴权方式，保留超时、重试和日志字段，不要顺手改业务逻辑。
单独测试流式输出和工具调用，这两项最容易出现“非流式正常、流式失败”。
用真实请求做小样本评测，再切百分之五到百分之十的流量，观察错误率和 p95 延迟。
保留旧通道或备用托管商，完成回滚演练后再全量切换。

迁移完成的标志不是“能返回文字”，而是质量、延迟、限流和账单都可接受，并且出现问题时能定位到具体请求。

常见问题

Llama API 的 Base URL 是固定的吗？

不固定。Meta 的旧 Llama API 入口已经下线，现在的 Base URL 由所选平台决定。Groq、OpenRouter、自建 vLLM 和兼容网关的路径前缀都不同，必须以控制台示例为准。

为什么同一个 Llama 模型在不同平台名字不一样？

平台会加入自己的前缀、版本、量化和部署标识。模型名是平台内部的 ID，不是模型家族的通用名称。切换平台时，模型名通常要跟着换。

OpenAI SDK 可以直接调用 Llama 吗？

可以，前提是目标平台提供 OpenAI 兼容的 /chat/completions 接口。把 base_url 指向平台地址、api_key 换成平台 Key、model 换成平台模型 ID，即可完成最小调用。工具调用、流式和错误结构仍要逐项验证。

流式输出需要换 SDK 吗？

多数 OpenAI SDK 都支持 stream=True，不需要换 SDK。但要确认平台返回的是标准 SSE、结束标记是否为 [DONE]，以及网关是否缓冲响应。

工具调用失败先查什么？

先确认模型和平台是否声明支持工具调用，再检查 tools 的 JSON Schema 是否合法、tool_choice 是否被平台接受，最后看返回的 finish_reason 和参数 JSON 是否能解析。逐层缩小，不要先改提示词。

下一步

先选一个入口，用控制台示例的 Base URL 和模型名跑通 curl，再接入 Python SDK；流式和工具调用要单独验收。需要统一入口、日志和多模型切换，可以从注册中商起航 AI 网关开始，模型清单与计费口径以模型价格为准。