大模型API实操指南:三层用法与费用控制

作者:公子世无双2026.11.17 03:29浏览量:0

简介:想把大模型接入插件、表格或小脚本,却不知从哪下手?本文从 API Key 与接口地址讲起,依次介绍零代码工具、轻代码调用示例、Key 安全清单,以及费用估算公式、预算告警和常见报错排查。读完可以独立完成第一次调用,并心里有数地控制开销。

大模型 API 让程序调用云端模型。你不需要训练模型,也不需要显卡。拿到凭证和接口地址后,浏览器插件、电子表格或几十行的 Python 脚本都能接入 AI。本文按三层展开:零代码工具、轻代码调用,以及费用控制。

一、API 与鉴权

模型厂商把模型部署在云端,通过 HTTP 接口提供推理服务。调用通常分三步:

  1. 在控制台创建 API Key,它是你的调用凭证;
  2. 记下接口地址(Base URL);
  3. 按约定格式发送文字,再读取返回结果。

多数平台支持 OpenAI 兼容格式。以百度智能云千帆为例,兼容地址是 https://qianfan.baidubce.com/v2/。如果你的代码原本使用 OpenAI 的 SDK,通常只需要修改 base_url、Key 和模型名。

常见鉴权方式有 API Key、access_token 和 Access Key ID / Secret Access Key 三种。不同平台和接口支持的组合不同。一次请求通常只用一种鉴权方式,混用时可能返回鉴权失败。具体规则以平台文档为准。

Key 能否调用某项服务,取决于两点:服务是否已开通,以及 Key 是否具备对应权限。遇到问题时,先到控制台确认这两项,通常比反复修改代码更快。

二、零代码:会填空就能用

最低门槛的做法是安装浏览器插件,在设置页填入 API Key 和接口地址。常见功能包括:

  • 网页总结:对长文、报告和问答页面提取要点;
  • AI 翻译:相比传统机器翻译,更能保留上下文和语气;
  • 信息抽取:从列表或资料页中提取固定字段,整理成表格。

这类工具上手快,适合先验证需求。使用前,先看清插件会把哪些页面内容发送到第三方服务器,以及它的隐私策略和免费额度。

涉及个人信息或内部资料时,上传前先做数据最小化处理:删除姓名、手机号、身份证号、客户编号等字段,只保留分析需要的内容。未公开的合同、财务数据和客户资料,不建议交给第三方插件处理。

如果某个功能需要长期使用,可以再评估自建。编排平台不写代码也能搭建工作流。Dify 支持添加 OpenAI-API-compatible 类型的模型供应商,填入千帆 API Key 后,即可添加多个模型并在应用中切换。One API 可以新建渠道,类型选择千帆 V2 对应的渠道,填入 Key 后点击测试,确认连通性。具体配置项以各平台最新文档为准。

三、轻代码:运行第一个调用脚本

这一层的收益最高。你可以请 AI 帮忙写调用模型的脚本,自己负责整理数据、保管 Key 并调整提示词。

运行前的准备

  1. 安装 Python 3.9 或更高版本。
  2. 安装 SDK:pip install openai。运行 pip show openai 可查看版本,本文示例基于 openai 1.x 版本编写。
  3. 在环境变量中设置 Key,不要把 Key 直接写进代码。

各系统设置环境变量的命令如下:

  • macOS / Linux(当前终端):export QIANFAN_API_KEY="你的Key"
  • Windows PowerShell:$env:QIANFAN_API_KEY="你的Key"
  • Windows 命令提示符:set QIANFAN_API_KEY=你的Key

环境变量只在当前终端窗口有效。关闭窗口后需要重新设置,或写入系统的永久环境变量。

  1. 在千帆控制台确认模型已开通,并复制准确的模型名。示例使用 deepseek-v3,如果控制台显示的名称不同,以控制台为准。

最小示例:总结一段文本

以弹幕分析为例,程序分成两部分。第一部分是抓取并整理弹幕,这部分由你负责,且需遵守第四节的数据来源规则。第二部分把文本交给模型,请它总结争议点、情绪分布或高频话题。真正调用模型的代码只有二十多行:

  1. import os
  2. from openai import OpenAI
  3. api_key = os.getenv("QIANFAN_API_KEY")
  4. if not api_key:
  5. raise SystemExit("未检测到环境变量 QIANFAN_API_KEY,请先设置后再运行。")
  6. client = OpenAI(
  7. api_key=api_key,
  8. base_url="https://qianfan.baidubce.com/v2/",
  9. )
  10. text = "这里替换为你整理好的文本"
  11. resp = client.chat.completions.create(
  12. model="deepseek-v3",
  13. messages=[
  14. {"role": "system", "content": "你是严谨的分析助手,只依据给定文本作答。"},
  15. {"role": "user", "content": f"以下是某视频的弹幕,请总结主要争议点:\n{text}"},
  16. ],
  17. )
  18. print(resp.choices[0].message.content)
  19. print("输入 tokens:", resp.usage.prompt_tokens)
  20. print("输出 tokens:", resp.usage.completion_tokens)

运行后,终端会输出模型回复,以及本次调用的输入和输出 token 数。第五节会用这两个数字估算费用。

代码通过 os.getenv 从环境变量读取 Key,代码本身不含密钥。如果提示未检测到环境变量,先确认当前终端是否是设置变量的那个窗口。

用 curl 先验证

写代码前,可以用 curl 直接发送请求,检查 Key、地址和模型名是否正确。Linux 和 macOS 终端可直接运行下面的命令,Windows 用户可在 Git Bash 或 WSL 中运行:

  1. curl https://qianfan.baidubce.com/v2/chat/completions \
  2. -H "Content-Type: application/json" \
  3. -H "Authorization: Bearer $QIANFAN_API_KEY" \
  4. -d '{"model": "deepseek-v3", "messages": [{"role": "user", "content": "你好,请用一句话介绍你自己。"}]}'

请求包含三部分:URL 是接口路径,Header 中的 Authorization 携带 Key,body 中的 model 和 messages 分别是模型名与对话内容。如果返回 200 并有正常回复,说明三者都正确。

API 能做什么

API 擅长对文本做分析、总结、抽取、改写和分类。弹幕分析有价值,是因为弹幕这类数据还没有被整理。同样的思路可以用在周报、会议记录、用户评论和合同条款上。只要数据已经是文本,且你有权使用,就可以交给模型处理。

四、安全与合规

API Key 最常见的风险是泄露。泄露后,别人可以用你的额度调用服务,费用就会计在你的账户上。

Key 安全清单

  • 不把 Key 写进代码或提交到代码仓库,改用环境变量读取。
  • 本地项目用 .env 保存 Key,同时提交一份 .env.example,里面只写变量名和占位符:
  1. QIANFAN_API_KEY=your_key_here
  • 在 .gitignore 中加入 .env。提交前运行 git status,确认 .env 不在待提交列表中。
  • 平台提供短期 Key 时优先使用,减少长期明文 Key 的暴露面。
  • 为 Key 设置用量上限或告警。
  • 面向他人的功能由后端调用模型,Key 不下发到浏览器或插件前端。
  • 不同用途使用不同 Key,不再需要的 Key 及时删除。

怀疑 Key 泄露时怎么办

  1. 在控制台撤销或轮换该 Key。
  2. 检查用量记录,确认是否有异常调用。
  3. 把新 Key 更新到环境变量或 .env 中,并重启相关程序。
  4. 如果 Key 已推送到公开仓库,视为已泄露,立即轮换。删除历史提交不能保证 Key 不再被获取。

数据来源与合规检查

调用模型前,先确认数据本身能否合法使用:

  • 平台是否提供官方开放接口,或你是否有合法授权;
  • 平台服务条款是否允许该用途;
  • 目标站点的 robots 协议和访问限制是否允许自动化访问;
  • 数据是否包含个人信息,是否已取得相应授权;
  • 分析结果是否会公开发布,发布时是否需要脱敏。

对平台上未开放的数据,不要绕过登录限制、验证码或访问频率限制去抓取,也不要把这类数据用于公开服务。

五、成本控制与排错

API 费用怎么估算

多数平台按 token 计费。输入(提示词加你发送的文本)和输出(模型生成的回复)单价可能不同。估算公式如下:

单次费用 ≈ 输入 tokens ÷ 1000 × 输入单价 + 输出 tokens ÷ 1000 × 输出单价

总费用 ≈ 单次费用 × 计划调用次数

举个例子。假设某模型输入单价为每千 tokens 0.002 元,输出单价为每千 tokens 0.004 元(仅为演示数字,请以官网价格为准)。一次调用输入 3000 tokens、输出 800 tokens,单次费用为 3 × 0.002 + 0.8 × 0.004 = 0.0092 元。计划调用 1000 次,总费用约为 9.2 元。

估算前不必猜 token 数。先用 3 到 5 条代表性样本运行脚本,读取 usage 中的 prompt_tokens 和 completion_tokens,取平均值,再乘以计划调用次数。实际 token 数与文本内容和分词方式有关,以返回的 usage 为准。

如何设置预算

  1. 在控制台设置用量上限和告警。常见做法是在用量达到 50%、80% 和 100% 时提醒。
  2. 每天或每周查看用量明细,与估算值对比。实际用量明显高于估算时,先暂停任务,再排查原因。
  3. 在代码中加入本地预算检查,防止循环或重试造成失控调用:
  1. MAX_TOTAL_TOKENS = 2_000_000
  2. used_tokens = 0
  3. # 每次调用成功后执行
  4. used_tokens += resp.usage.prompt_tokens + resp.usage.completion_tokens
  5. if used_tokens > MAX_TOTAL_TOKENS:
  6. raise SystemExit("已达到本地 token 预算上限,停止调用。")

这段计数只在当前进程内有效,程序重启后会归零。长期运行的任务应把累计值写入文件或数据库。批量调用时,还应限制并发数,避免短时间内集中消耗额度。

常见报错排查

现象 常见原因 处理方法
401 鉴权失败 Key 错误、已过期,或混用了鉴权方式 核对 Key,统一使用一种鉴权方式
403 权限不足 服务未开通,或 Key 缺少权限 在控制台开通服务并检查权限
404 地址错误 Base URL 写错或路径不完整 对照官方文档核对地址
model not found 模型名拼写错误,或未开通该模型 在控制台复制准确的模型名
429 请求过于频繁 并发或请求频率超过限制 降低并发,增加重试间隔
欠费或余额不足 账户余额不足,或资源包已用完 查看控制台余额,充值或开通付费后再调用

具体错误码和提示文字以平台文档为准。欠费的返回形式可能与 429 不同,排查时以实际返回的信息为准。

429 和欠费有什么区别

429 通常表示请求太快或并发太高,等待一段时间后可以恢复。欠费和额度耗尽则需要在账户侧处理,单纯等待无效。遇到 429 时,先降低并发并查看返回信息。遇到欠费类提示时,先到控制台检查余额、资源包和免费额度的使用情况。

重试与退避

只对临时性错误重试,例如 429 和 5xx。重试时采用指数退避,即第一次等待 1 秒,之后依次等待 2 秒、4 秒,最多重试 3 到 5 次。401、403、404、模型名错误和欠费类错误不要重试,重试无法解决这些问题。

排查顺序

  1. 先看 HTTP 状态码和返回的错误信息。
  2. 确认环境变量已被读取。可以打印 Key 的长度,但不要打印 Key 本身。
  3. 在控制台检查服务开通状态、模型名和账户余额。
  4. 用前文的 curl 命令验证,判断问题出在代码还是账户。