百川智能 API 怎么用？模型选择、Python 调用与计费排错

直接答案：调用百川智能 API 不需要安装来历不明的 baichuan-sdk。当前官方文档公开的是 HTTP POST https://api.baichuan-ai.com/v1/chat/completions，使用 Bearer API Key 和 JSON 消息体。最稳妥的做法是：从控制台复制当前可用模型 ID，把密钥与模型名放进环境变量，用 requests 发起请求，并记录请求 ID、状态码、Token 用量和实际费用。不要把旧教程里的模型名、价格或显存要求当作永久配置。

先分清：托管 API 与开源权重不是一件事

旧稿把“API 调用”和“本地部署”混成一个教程，并给出固定的 16GB 显存与 CUDA 11.8 要求。实际显存取决于模型、精度、上下文、批量和推理引擎；如需本地运行，应单独参考模型量化说明，并用推理硬件与延迟证据边界建立自己的性能验收。Baichuan 2 仓库还附带社区许可条件，不能只看到 GitHub 页面上的 Apache 标识就忽略附加协议。

为什么不能照抄旧模型名

截至 2026 年 7 月 18 日复核时，官方通用 API 文档的参数表仍主要展示 Baichuan2-Turbo 与已经标注迁移的 192k 型号；同一官方平台的价格页却列出了 Baichuan-M3-Plus、Baichuan-M3、M2 系列、Baichuan4-Turbo、Baichuan4-Air 等更多型号。这说明公开页面存在更新节奏差异。

因此，本文不把任何模型名硬编码为“永久默认”。上线前应登录开放平台，在模型或调用页面复制账号当前可见的模型 ID，再设置为环境变量。若控制台、API 文档和价格页不一致，以账号实际可调用结果和官方支持答复为准，并保留复核日期。

五步完成第一次安全调用

1. 创建并保护 API Key

按官方流程完成账号、实名认证、余额与 API Key 创建。密钥只放在服务端环境变量或密钥管理系统，不写入 WordPress 正文、前端 JavaScript、截图、Git 仓库或日志。若怀疑泄露，立即撤销并轮换。

# PowerShell：只对当前终端会话生效
$env:BAICHUAN_API_KEY="替换为你的密钥"
$env:BAICHUAN_MODEL="从控制台复制当前可用模型ID"

2. 安装通用 HTTP 客户端

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade requests

官方示例本质上也是 HTTP 请求。使用通用客户端能避免虚构或过期 SDK 的包名、导入路径与方法签名。

3. 发送最小请求

import os
import requests

url = "https://api.baichuan-ai.com/v1/chat/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.environ['BAICHUAN_API_KEY']}",
}
payload = {
    "model": os.environ["BAICHUAN_MODEL"],
    "messages": [
        {"role": "user", "content": "回答要简洁；不确定时明确说明。用三点解释什么是向量检索。"},
    ],
    "temperature": 0.2,
    "stream": False,
}

response = requests.post(url, headers=headers, json=payload, timeout=(10, 90))
request_id = response.headers.get("X-BC-Request-Id")
print("status=", response.status_code, "request_id=", request_id)
response.raise_for_status()
data = response.json()
print(data["choices"][0]["message"]["content"])
print("usage=", data.get("usage"))

这段代码不会打印密钥，但会输出状态码、官方响应中的请求 ID 与可能存在的用量字段。生产环境不要直接记录完整提示词或回答；日志应按数据敏感度脱敏。

这里没有使用 system 角色，因为截至复核日，官方通用参数表明确列出的消息角色是 user 与 assistant。如果你的控制台或专属文档后来支持更多角色，应先做契约测试再启用，不能仅因其他厂商兼容 OpenAI 风格接口就推定百川拥有相同字段。

请求与响应中哪些字段必须验收

4. 按错误类型处理，而不是无限重试

• 401：检查 Bearer 格式、密钥是否正确或已撤销；不要用重试掩盖鉴权错误。
• 429 频率限制：降低并发，使用带抖动的指数退避；只重试幂等且允许重复执行的请求。
• 429 余额不足：这是计费状态，不应自动重试；先检查账户余额和预算。
• 500：短暂等待后有限次数重试，同时保存请求 ID 供官方支持定位。

HTTP 状态码的一般语义可交叉参考RFC 9110，但百川错误页对同一个 429 同时列出“频率限制”和“余额不足”，所以程序还要读取响应体并分类。Requests 默认不会替你设置业务合理的超时；连接与读取超时的差异可参考Requests 超时文档。

5. 用真实任务验收

“请求返回 200”只代表接口成功，不代表业务质量合格。至少准备事实问答、结构化 JSON、长文本摘要和拒答边界四类样本，记录首响应时间、总耗时、输入输出 Token、任务通过率和人工纠错。有关 Token 的定义与计价边界可参考Token 计算主页面；关于回答核验可参考AI 幻觉核验清单。

当前价格应该怎样阅读

官方价格页按“千 Tokens”列价，并说明一般情况下 1 Token 约等于 1.5 个中文汉字；这只是平台给出的经验换算，不适合替代实际账单。部分型号把输入、输出分开计费，部分型号采用合并单价；搜索增强、医疗搜索、知识库文件存储和 Embedding 还可能单独收费。

预算公式应按所选型号当日口径计算：输入千Token × 输入单价 + 输出千Token × 输出单价 + 附加服务。上线前用 50—100 条真实请求核对控制台账单，不要根据“每篇文章大约多少汉字”估算。价格会变化，本文不会把某个单价写成长期承诺。

知识库与联网搜索何时再加

先让基础对话请求稳定，再考虑知识库。官方知识库接口包含文件上传、知识库创建、分片和文件关联等步骤；它不是在请求里随手加一个参数就自动获得可靠答案。应准备可授权文档、版本号、更新时间、引用回传和删除流程，并测试“没有答案时是否拒答”。有关检索原理可先阅读RAG 是什么。

官方价格页还说明搜索增强可能按次收费，某些模型可能自动触发特定搜索。是否启用 with_search_enhance 应结合控制台与当前文档验证，并同时评估来源质量、隐私和费用，不能把联网等同于事实正确。

向量化与知识库也要分开记账：文本先经 Embedding 生成向量，文件还可能按存储容量和天数计费。当前规则可查看官方 Embedding 接口。删除知识库前应确认文件、分片、向量数据和业务索引的清理顺序，并用一个已删除文档的专属问题验证它不再被召回。

从演示代码到生产服务还缺什么

生产服务应在百川接口前增加自己的输入校验、权限、限流、超时、重试预算和审计层。API Key 的环境变量读取可参考Python os.environ 文档；团队级密钥生命周期可参考OWASP Secrets Management 指南。环境变量不是完整密钥管理系统，但比把 Key 写进源代码安全得多。

还要准备降级路径：目标模型不可用时，是切换已验收的备用模型、返回稍后重试、还是转人工？切换模型可能改变价格、能力和合规边界，不能在代码里静默替换。任何自动降级都应记录原模型、替代模型、触发原因和结果，并允许回滚。

把一次调用变成可审计的请求合同

能返回 200 只说明某次请求被接口接受，不代表生产接入完成。调用方应在自己系统中为每次业务请求生成关联 ID，并记录模型 ID、接口版本、超时、重试次数、输入/输出 Token、搜索或知识库开关、HTTP 状态码、供应商响应 ID、延迟和最终业务结果。关联 ID 是本站应用层的审计字段，不应伪装成百川官方未承诺的幂等参数；是否支持某个 Header 或请求字段，必须以当前文档和真实小流量测试为准。

日志还要区分“请求失败”和“结果不可用”。401/403 多半要检查密钥、权限和账号状态；429 需要遵循服务端提示并限制并发；5xx 可以在有上限的退避策略下重试；200 但输出为空、格式错误、事实不可靠或超出业务边界，则属于质量失败。HTTP 429 的通用语义可对照RFC 6585，但具体配额、响应体和恢复时间仍以百川当前错误码、响应头与支持答复为准。

怎样把价格页变成可复算预算

价格页会变，预算表不能只抄“每千 Token 单价”。截至本次复核，页面同时存在输入/输出分别计价的型号、输入输出合并计价的旧型号、搜索增强按次收费、医疗搜索可能自动触发、Embedding 按 Token 收费和知识库文件按 GB/天收费等不同单位。先锁定账号当前模型和功能，再建立公式；页面还明确提醒价格可能变动，因此正式上线应保存日期和页面快照。

建议用三种真实任务算预算：短问答、带多轮历史的长对话、开启搜索或知识库的检索任务。每种至少记录 30 次请求的中位数与高分位 Token、延迟、失败率和人工返工率，再计算单次有效结果成本。便宜但经常需要人工重写的模型，最终业务成本可能更高；价格更高但能稳定满足格式、引用和安全要求的模型，也可能减少总成本。跨供应商比较时可参考站内模型选型与验收方法，不要只比较标价。

上线前必须演练的六种故障

生产门槛应由演练结果决定，而不是由演示成功决定。至少模拟密钥失效、模型 ID 不存在、请求超时、429 限流、5xx 服务故障和 200 但输出不合格六种情况。每次演练都要验证：是否停止无限重试、是否避免重复扣费或重复业务动作、是否向用户给出可理解状态、是否触发降级或人工接管、是否保留足够但不泄密的诊断信息。

完成演练后再设上线阈值，例如：技术成功率、P95 延迟、格式通过率、人工接管率、单个有效结果成本和高风险错误数。阈值必须使用自己的数据，不照抄供应商宣传数字。任何更换模型、开启搜索、增加知识库或修改提示词的操作，都应视为需要回归测试的版本变更。

最小上线证据包至少包括：一次已脱敏的成功请求与响应、六类故障演练记录、模型和价格页复核日期、30 个以上真实任务的质量与延迟汇总、Token/附加服务/人工返工成本表、密钥轮换记录、数据保留与删除规则、降级和回滚步骤。代码仓库只保存环境变量名和示例占位符，不保存真实 Key；截图也要检查浏览器地址栏、控制台和网络面板是否泄露凭证。

上线审批人还应能回答三个问题：某次结果怎样追溯到模型与配置版本；百川接口不可用时业务怎样安全停止或降级；账单突然升高时怎样定位到具体任务、Token 与附加服务。只要其中一个问题没有可执行答案，就应继续停留在灰度阶段。医疗、法律、财务、账号修改、外部发送和自动采购等高影响场景还要增加专业审核、最小权限与明确确认，不能因为接口返回成功就自动执行。

正式发布后的第一周应每天复盘失败样本和费用差异，随后再按风险调整周期。若控制台、文档和价格页发生冲突，先暂停扩量，保存页面快照与请求证据，再向官方支持确认；不要用旧文章、搜索摘要或模型自己的回答替代当前平台事实。每次确认都要写入变更记录，并注明验证账号、区域、模型 ID、请求时间和受影响功能，以便下一次复核能够真正比较。

上线前检查表

1. 模型 ID 来自当前控制台，不是搜索结果或旧教程。
2. 密钥不进入浏览器、仓库、正文、截图和普通日志。
3. 为连接与读取设置超时，并限制 429/500 重试次数。
4. 记录请求 ID、模型 ID、复核日期、Token 与费用，不记录敏感原文。
5. 对四类真实样本做回归测试，并设置错误答案的人工升级路径。
6. 知识库、搜索、医疗等附加能力单独核验计费与数据边界。
7. 若改为本地权重，重新评估硬件、许可证、安全备案和运维责任。

资料来源与复核边界

接口地址、鉴权、消息结构与请求 ID 依据百川开放平台 API 文档；型号、Token 计费与附加服务依据官方价格页；错误处理依据官方错误码；文件与知识库步骤依据文件接口和知识库接口；本地权重与许可边界依据Baichuan 2 官方仓库。企业与产品背景可另见站内百川智能介绍。资料复核日期：2026 年 7 月 19 日。

控制台入口与产品能力变化可从百川开放平台首页重新进入，避免通过仿冒登录页提交 Key。本文没有使用控制台私有内容，也没有代替读者验证账号是否具备某个模型权限；“当前可用”必须由账号自己的最小请求确认。

编辑复核与纠错记录：本文由兰塞 AI 编辑流程于 2026 年 7 月 19 日复核。旧稿中的 pip install baichuan-sdk、from baichuan import Baichuan、固定模型名、固定显存和“秒级响应”等说法均未得到当前官方资料的完整支持，已全部撤下；本次还移除了官方通用参数表未列出的 system 角色，新增页面漂移、请求合同、分类重试、可复算账单、六类故障演练、生产门禁与降级记录。本文只提供通用技术接入方法，不构成医疗用途、商用许可或费用承诺。本站的来源、更新与纠错原则见关于本站与编辑规范。

下一次复核将重新检查模型、价格、配额、错误码与账号可见能力。