Python 调用国产大模型 API：OpenAI SDK 完整示例与 401、429、超时排查

本文以 FlowBarCN 国内站为例，使用 OpenAI Python SDK 完成三个步骤：查询可用模型、发送普通对话请求、接收流式响应。后半部分整理首次接入常见的配置与错误排查方法。

作者说明：本文由 FlowBarCN 团队撰写，示例使用自家服务，内容由 AI 辅助整理并结合真实调用记录核对。验证日期为 2026 年 10 月 21 日，范围限于本文的文本对话示例。

1. 接入参数与运行环境

本次验证环境：Windows、Python 3.11.9、openai==3.35.1。

项目	本文配置
SDK	OpenAI Python SDK
Base URL	https://flowbar.cn/v1
对话接口	POST /v1/chat/completions
模型目录	GET /v1/models
模型 ID	deepseek-v4-flash-0731-new
密钥环境变量	FLOWBAR_API_KEY

需要准备 FlowBarCN 账号、有效 API Key 和足够的调用额度。该模型 ID 已在本次带鉴权的目录查询中确认，并完成普通与流式调用；这不是对上游模型身份的独立认证，也不代表所有账号或所有时间均可调用。

OpenAI 是 SDK 中的客户端类名。请求实际发往哪里，取决于 base_url。本文使用的是兼容的 Chat Completions 文本对话接口，不代表 SDK 中所有其他接口也受到支持。

2. 创建虚拟环境并配置密钥

在项目目录打开 PowerShell：

python -m venv .venv
.venv\Scripts\python.exe -m pip install openai==3.35.1
$env:FLOWBAR_API_KEY = "替换为你自己的 FlowBarCN API Key"
$env:FLOWBAR_MODEL = "deepseek-v4-flash-0731-new"

这里直接使用虚拟环境中的 Python，不依赖 PowerShell 的激活脚本。后续安装依赖和运行示例，都使用同一个解释器，避免“明明安装了包，却提示找不到模块”的环境错位。

环境变量仅供当前终端及其子进程使用。换一个终端运行时，需要重新配置，或采用你自己的安全配置管理方式。真实密钥不能提交到 Git、写进前端代码或出现在截图中。

3. 完整代码：一个脚本支持三种运行方式

保存为 demo.py：

import argparse
import os
import sys

from openai import OpenAI


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument('--stream', action='store_true')
    parser.add_argument('--list-models', action='store_true')
    args = parser.parse_args()
    key = os.getenv('FLOWBAR_API_KEY', '').strip()
    if not key:
        sys.exit('请先设置 FLOWBAR_API_KEY 环境变量。')
    model = os.getenv('FLOWBAR_MODEL', 'deepseek-v4-flash-0731-new')
    with OpenAI(
        api_key=key,
        base_url='https://flowbar.cn/v1',
        timeout=60.0,
        max_retries=0,
    ) as client:
        if args.list_models:
            ids = sorted(item.id for item in client.models.list().data)
            print('\n'.join(ids))
            print(f'当前示例模型在目录中: {model in ids}')
            return
        result = client.chat.completions.create(
            model=model,
            messages=[{'role': 'user', 'content': '请用一句简短的中文解释什么是 API。'}],
            max_tokens=128,
            stream=args.stream,
        )
        if args.stream:
            with result:
                for chunk in result:
                    if chunk.choices:
                        content = chunk.choices[0].delta.content
                        if content:
                            print(content, end='', flush=True)
            print()
        else:
            print(result.choices[0].message.content or '')
            if result.usage:
                print('Token 用量:', result.usage.model_dump())


if __name__ == '__main__':
    main()

3.1 查询模型目录

.venv\Scripts\python.exe demo.py --list-models

脚本列出接口返回的模型 ID，并打印当前示例模型是否在目录中。如果显示 False，先检查最新目录和账号权限，不要自行猜测模型名称。

目录可见不等于生成一定成功。生成还依赖令牌权限、额度和当时服务状态，因此需要继续进行下面两项检查。

3.2 普通对话

.venv\Scripts\python.exe demo.py

普通模式读取 result.choices[0].message.content，在响应带有 usage 时打印用量。本文实际获得的文本为：

API 是让不同软件之间按约定方式互相调用功能、交换数据的接口。

该次响应报告输入 40 Token、输出 61 Token、合计 101 Token；输出中包含接口报告的 42 个 reasoning token。可见文字长度不能直接替代用量字段。

3.3 流式响应

.venv\Scripts\python.exe demo.py --stream

流式模式按收到的文本增量输出，本次结果为：

API 是软件之间约定好的接口，让不同程序无需了解内部实现就能互相调用功能或交换数据。

与普通响应不同，流式文本取自 chunk.choices[0].delta.content。先判断 choices 是否存在，再判断 content，可以处理没有文本增量的数据块。flush=True 则让终端及时显示已收到的文本。

4. 为什么示例这样设置？

显式指定 Base URL。 传入 https://flowbar.cn/v1，不要把完整的 /chat/completions 路径作为 Base URL，也不要重复拼接 /v1。

使用独立的密钥变量。 FLOWBAR_API_KEY 可以避免与电脑上其他服务的 OPENAI_API_KEY 混淆。其他厂商的密钥不会因为采用同一个 SDK 就自动通用。

关闭自动重试。 max_retries=0 便于首次验证时看清请求次数。生产环境可以按业务设计有上限的退避重试，但不能对所有错误无限重试。

使用短输出上限。 max_tokens=128 只用于本文的一句话回答。长文本和推理任务需要结合模型规则调整参数，不能把这个值当成通用推荐配置。

显式关闭客户端和流。 with 语句负责退出时释放连接资源，让示例在命令行使用时更完整。

5. 常见错误排查表

以下是排查顺序，不代表本文主动制造并测试过所有错误场景。具体原因应结合服务返回的错误正文判断。

现象	优先检查	处理方向
ModuleNotFoundError: openai	安装与运行是否使用同一 Python	用 .venv\Scripts\python.exe -m pip 安装，并用同一解释器运行
提示未设置 FLOWBAR_API_KEY	是否在当前终端配置	在运行脚本的终端重新设置
HTTP 401	密钥归属、有效性及是否复制完整	使用国内站签发的有效密钥，不向他人发送原始密钥
HTTP 404	Base URL 与请求路径	排除重复路径，再按错误正文检查模型等信息
模型不存在或无可用渠道	完整模型 ID、权限和服务状态	查目录、核对令牌限制，必要时提供脱敏错误信息
HTTP 429	限流或额度相关错误	读取具体错误，区分等待退避与额度处理
超时、连接失败	网络、代理、TLS、服务状态	先定位连接问题，不关闭证书校验来绕过错误
成功但文本为空	结束原因、输出上限与推理行为	检查响应字段后再决定是否调大输出上限

特别注意：超时不等于服务端一定没有处理请求。连续重试可能形成重复调用。向支持人员反馈时，提供调用时间、模型 ID、HTTP 状态码和脱敏错误即可，不要提供 Authorization 请求头。

6. 如何切换模型，如何接到网页里？

切换到另一个支持同一文本对话接口的模型时，先确认准确 ID 和参数支持，再修改 FLOWBAR_MODEL。本文只验证了表格中的一个模型，未对其他模型作可用性承诺。

如果需要网页聊天界面，建议采用“浏览器 → 自己的后端 → 模型服务”的结构。密钥放在后端，由后端处理访问控制、限流与日志，再把普通结果或流式文本返回浏览器。

不要为了省去后端，直接把服务端 API Key 写进网页 JavaScript。浏览器中的代码和请求可以被用户查看。

7. 本次验证清单

• 使用测试密钥查询 /v1/models，找到 deepseek-v4-flash-0731-new。
• 原样运行本文脚本的普通模式，成功返回中文回答。
• 原样运行本文脚本的流式模式，成功接收文本增量。
• 共使用两次短文本生成，不是并发、长上下文或持续稳定性测试。
• 流式示例没有请求最终 usage；不据此声称已核对两次调用的完整用量或实际账单。

先让最小示例跑通，再逐步接入业务逻辑，可以把模型调用问题和应用自身的问题分开定位。FlowBarCN 国内站的接入文档与模型目录可用于核对后续配置变化。

参考资料

• FlowBarCN 接入文档
• FlowBarCN 模型目录
• OpenAI Python SDK