百度千帆免费额度领取：文心轻量模型不限量调用教程

百度千帆提供 OpenAI 兼容风格的 v2 接口，base_url 形如 https://qianfan.baidubce.com/v2，对话补全路径为 /chat/completions。也就是说，任何支持自定义 base_url 的 OpenAI SDK 都能直接接过来用，迁移成本很低。

先把密钥放进环境变量

不要硬编码密钥，先在终端设置环境变量，后续命令和脚本都从环境变量读取：

export QIANFAN_API_KEY="你的 API Key"

用 curl 跑通第一次调用

下面的请求体包含一次最小的对话补全调用，注意 model 要与控制台里已开通的模型名一致（例如 ernie-speed-128k、ernie-lite-8k、ernie-tiny-8k，完整可用列表以控制台模型页为准）：

curl https://qianfan.baidubce.com/v2/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $QIANFAN_API_KEY" \
  -d '{
    "model": "ernie-speed-128k",
    "messages": [
      {"role": "system", "content": "你是一个简洁的技术助手"},
      {"role": "user", "content": "用一句话解释什么是 RESTful 接口"}
    ],
    "temperature": 0.7,
    "top_p": 0.8,
    "max_tokens": 512,
    "stream": false
  }'

用 Python SDK 调用

把 base_url 换成千帆的地址即可，其余写法与 OpenAI 一致：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["QIANFAN_API_KEY"],
    base_url="https://qianfan.baidubce.com/v2",
)

resp = client.chat.completions.create(
    model="ernie-speed-128k",
    messages=[
        {"role": "system", "content": "你是一个简洁的技术助手"},
        {"role": "user", "content": "写一句对象存储产品的宣传语"},
    ],
    temperature=0.7,
    max_tokens=512,
)

print(resp.choices[0].message.content)

关键参数说明

• model：必填，取值必须是控制台已开通的模型名，拼错或未开通会直接报错。
• messages：必填，消息数组，元素含 role（system / user / assistant）与 content。多轮对话就是把历史消息按顺序追加进去。
• temperature：随机性，0 到 1 之间取值，做结构化输出时调低到 0.1 至 0.3。
• top_p：核采样阈值，通常与 temperature 二选一调整，不要同时大幅改动。
• max_tokens：限制回复长度，设太小会被截断，设太大在长上下文模型上更容易触发限流。
• stream：设为 true 时返回 SSE 流式分片，适合聊天类前端；服务端渲染场景保持 false 更省事。

额度耗尽与限流的典型表现

常见两类：一类是频率或并发超限，返回 HTTP 429 或带「rate limit / QPS」字样的错误体；另一类是账户层面不可用，例如赠送额度用尽、账户欠费、模型未开通或实名未通过，这类通常返回 4xx 并在 message 中给出明确原因（涉及余额、quota、权限等关键词）。

排查顺序建议按下面的链条走，能覆盖绝大多数问题：

1. 检查请求头是否写成 Authorization: Bearer 密钥，前缀和空格都不能少，密钥前后不要带引号或换行。
2. 核对 model 是否与控制台模型列表完全一致，并确认该模型已经开通。
3. 回到控制台看账户状态：实名认证是否通过、有无欠费、赠送额度是否已过有效期。
4. 若为 429，先降低并发与 max_tokens，在代码里加指数退避重试，避免瞬时打满 QPS。
5. 若仍失败，用 curl 最小请求体复测，排除 SDK 参数或代理层干扰，再比对返回体里的错误码与提示原文。

做生产兜底时，建议给免费模型单独设一条通道并配置超时与降级逻辑，避免主通道异常时被免费通道的限速拖慢整体响应。