力 力达云
教程聚合APItoken成本国产模型资讯工具关于内测申请
← 返回资讯

文心一言 API 接入、价格与能力详解

2026-07-24

文心一言（ERNIE Bot）是百度推出的大语言模型，背靠百度搜索与知识图谱生态，在中文理解、知识问答、多模态（文图）能力上积累深厚。其 API 平台”百度智能云千帆”提供 OpenAI 兼容接口，具备 IAM 认证体系，适合已有百度云基础设施的企业快速落地。

如果你是从 OpenAI 或者其他厂商迁移过来的，第一次接千帆最容易踩的坑不是代码写法，而是认证体系——百度这套东西历史包袱比较重，新旧两代接口并存，下面把这些坑一次讲清楚。

注册与获取 API Key

  1. 访问 cloud.baidu.com 完成百度账号实名认证；
  2. 进入千帆大模型平台 → 应用接入 → 创建应用，获取 API Key 与 Secret Key；
  3. 通过 API Key + Secret Key 换取 access_token（有效期 30 天），或直接使用应用级 API Key 走 Bearer 鉴权（较新接口）；
  4. 控制台可查看 token 用量与余额充值入口。

这里有个容易搞混的地方：千帆控制台里同时存在”应用级 API Key”和”IAM 用户的 Access Key/Secret Key”两套体系，前者是给大模型调用用的，后者是百度云通用资源管理（跟 ECS、对象存储共用）。新手常常把 IAM 的密钥拿去调 /v2/chat/completions，结果收到 invalid client 或者鉴权失败，排查半天发现用错了密钥对——一定要在”千帆 ModelBuilder”或”应用接入”页面单独创建应用，拿应用级的 Key，不要复用 IAM 的密钥。

另外，个人认证账号和企业认证账号的调用配额不一样。个人账号免费额度通常只够跑通demo，真要上生产环境（比如日调用量过万），建议先做企业实名认证，配额和并发上限都会宽松不少，也更容易申请到临时扩容。

接入示例：OpenAI 兼容调用

千帆平台提供 OpenAI 兼容端点，直接替换 base_url 和模型名即可：

from openai import OpenAI

client = OpenAI(
    api_key="your-qianfan-api-key",          # 千帆应用 API Key
    base_url="https://qianfan.baidubce.com/v2",
)

response = client.chat.completions.create(
    model="ernie-4.5-8k",                    # 或 ernie-4.0-8k、ernie-lite 等
    messages=[
        {"role": "system", "content": "你是一个专业的中文写作助手"},
        {"role": "user", "content": "帮我写一份产品发布公告"},
    ],
)
print(response.choices[0].message.content)

流式输出：

stream = client.chat.completions.create(
    model="ernie-4.5-8k",
    messages=[{"role": "user", "content": "解释什么是 RAG"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

流式输出这段代码看着简单，但生产环境里有个细节容易漏：chunk.choices 有时候是空列表（比如流的最后一个心跳包，或者被安全审核打断的中间帧），直接取 chunk.choices[0] 会抛 IndexError。稳妥的写法是先判断 if chunk.choices: 再往下取，尤其是文心的审核机制比某些厂商更”神经质”，一旦命中敏感词，流可能会在中途直接截断而不是抛异常，你的代码得能优雅处理这种”半截话”的情况，而不是假设流永远完整。

老版本 access_token 获取方式（历史遗留，了解即可）：如果你接的是文心早期的 ERNIE Bot 原生接口（非 v2 OpenAI 兼容端点），仍然需要先用 API Key + Secret Key 换 access_token：

import requests

def get_access_token(api_key: str, secret_key: str) -> str:
    url = "https://aip.baidubce.com/oauth/2.0/token"
    params = {
        "grant_type": "client_credentials",
        "client_id": api_key,
        "client_secret": secret_key,
    }
    resp = requests.post(url, params=params, timeout=10)
    resp.raise_for_status()
    return resp.json()["access_token"]

这个 access_token 有效期 30 天，不是永久的。很多人第一次上线时忘了做刷新逻辑，跑了一个月后突然大面积报 110 或 111 错误码（token 过期/无效），排查半天才想起来是这个坑。如果你还在用老接口，建议把 token 缓存到 Redis 或本地文件，设一个 25 天的过期时间提前刷新，别等它真过期了再手忙脚乱。新版 v2 接口直接用应用 API Key 走 Bearer 鉴权，从根上避免了这个问题，这也是官方现在力推新接口的原因。

生产环境实战：常见报错与重试策略

接文心 API 上生产，比接 demo 麻烦的地方在于你要处理三类高频异常：限流、鉴权失败、内容审核拦截。下面是一个带指数退避重试的封装，实际项目里可以直接抄：

import time
import random
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI(api_key="your-qianfan-api-key", base_url="https://qianfan.baidubce.com/v2")

def chat_with_retry(messages, model="ernie-4.5-8k", max_retries=4):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(model=model, messages=messages)
        except RateLimitError:
            # 触发 QPS 限流，指数退避 + 抖动，避免多个进程同时重试造成惊群
            wait = (2 ** attempt) + random.uniform(0, 0.5)
            time.sleep(wait)
        except APIStatusError as e:
            if e.status_code == 401:
                raise RuntimeError("鉴权失败，检查 API Key 是否正确或已过期") from e
            raise
    raise RuntimeError("重试多次仍失败，请检查配额或联系千帆工单")

三个高频问题实测过的现象和根因：

  • 429 限流：千帆对每个应用有 QPS 上限（默认档位通常是个位数到十几 QPS，具体看你开通的付费档位），超了直接返回 429。别一股脑加大并发去硬扛，先去控制台查看当前应用的限流配置，能提额就提额，提不了就在客户端做排队或者令牌桶限速。
  • 401 鉴权失败：八成是 API Key 复制时带了多余空格或换行符（尤其是从网页复制粘贴到代码里），或者用错了应用（比如把测试环境的 Key 用到了生产请求上）。打印一下 len(api_key) 看有没有异常字符，是排查这类问题最快的手段。
  • 336003 内容审核拦截：这是百度自己的业务错误码，不是标准 HTTP 状态码，说明请求内容命中了安全策略。它可能出现在 system prompt、用户输入，甚至上下文历史里，报错信息不会精确告诉你是哪句话触发的，只能自己二分排查——先砍掉一半上下文重试，缩小范围。

ERNIE 主要模型对比

模型定位上下文窗口适用场景
ernie-4.5-8k旗舰，最强综合能力8k tokens复杂推理、长文生成、多轮对话
ernie-4.0-8k上一代旗舰，稳定8k tokens生产级通用任务
ernie-speed-128k极速版，超长上下文128k tokens长文档处理、大批量摘要
ernie-lite-8k轻量经济型8k tokens高频简单问答、成本敏感型应用
ernie-tiny-8k超轻量8k tokens简单分类、意图识别

选择建议：正式产品用 ernie-4.5-8k；长文档场景用 ernie-speed-128k；预算紧或请求量极大时选 ernie-lite-8k。

价格定性

截至 2026-06，以官方公示为准：

  • ERNIE 4.5 系列属旗舰区间，价格高于轻量版，在国产旗舰中处于中等水平；
  • ERNIE Speed / Lite 系列价格较低，适合量大频次高的场景；
  • 新用户有免费 token 赠送，千帆平台还提供预付费与后付费两种模式。

具体单价以 千帆价格页 为准，也可用 价格对比工具 做横向比较。

估算成本时有个容易漏算的点：文心的计费是输入 token 和输出 token 分开算单价的，而且不同模型的比例不一样，不能简单按”总 token 数 × 一个平均单价”来估。正确做法是先跑一批真实业务样本（比如你产品里最常见的 20 条 query），分别统计输入输出 token 数，再套官方单价算出单条请求的实际成本，乘以预估日调用量，这样估出来的月度账单误差能控制在个位数百分比以内，而不是拍脑袋估出一个数字后上线才发现差了好几倍。

另外要提醒一句：千帆预付费套餐通常比按量付费的后付费单价更划算，但前提是你对自己的调用量有比较准的预估——套餐买多了是浪费，买少了超出部分可能按更贵的溢出单价计费，具体规则同样以官方价格页为准，别凭经验套用其他厂商的套餐逻辑。

并发调用怎么写

如果你的场景是批量处理（比如给几千条商品描述做摘要），别用 for 循环顺序调用，太慢。用 asyncio + 异步客户端并发发请求，同时配合信号量控制并发数，避免一下子打满限流：

import asyncio
from openai import AsyncOpenAI

async_client = AsyncOpenAI(api_key="your-qianfan-api-key", base_url="https://qianfan.baidubce.com/v2")
sem = asyncio.Semaphore(5)  # 并发数按你的 QPS 配额设置，别一上来就拉满

async def ask(prompt: str):
    async with sem:
        resp = await async_client.chat.completions.create(
            model="ernie-lite-8k",
            messages=[{"role": "user", "content": prompt}],
        )
        return resp.choices[0].message.content

async def main(prompts: list[str]):
    return await asyncio.gather(*[ask(p) for p in prompts])

信号量的数值不是随便拍的，建议先从你申请到的 QPS 配额的 60%~70% 起步，观察一段时间没有 429 再逐步往上加，直接顶满配额跑，一旦有网络抖动或者对方后端瞬时压力大，很容易连锁触发限流。

常见问题

文心 API 需要先换 access_token 才能调用吗？ 旧版 ERNIE Bot API 需要 API Key + Secret Key 换取 access_token；千帆新版已支持直接用应用 API Key 走 Bearer 鉴权，推荐使用新版接口，省去 token 刷新逻辑。

调用失败返回 336003 错误怎么办？ 该错误通常是输入内容命中安全策略（如政治敏感词）。检查 system prompt 和用户输入，避免触发内容过滤；也可在千帆控制台查看详细错误说明。

能用 LangChain 接文心吗？ 可以。LangChain 有专门的 QianfanChatEndpoint，也可通过 OpenAI 兼容端点 + ChatOpenAI(base_url=...) 方式接入，后者更通用。

相关阅读：国产大模型 API 全景指南 · 六大模型横向对比 · 豆包 API 接入详解

分类导航：国产模型专题

实用工具：价格对比表 · Token 计数器