应用接入实践

适合已经跑通最小 SDK 请求、准备把 BestAI 接进自己网站或服务的开发者。本页补齐密钥位置、流式结束判断、超时、重试和运行记录。

把 Key 放在应用后端

网页或移动应用可以采用这条链路：

text

你的网页 / 移动应用
        ↓ 用户登录态与业务请求
你的应用后端：校验用户、限制额度、保存 BestAI Key
        ↓ API 请求
BestAI → 模型服务

BestAI Key 存在后端环境变量或你的密钥管理系统中。前端只持有你自己应用的登录态，不接收完整 BestAI Key。VITE_*、NEXT_PUBLIC_* 等公开构建变量会进入前端产物，不用于保存服务端密钥。

后端需要限制用户可选模型、输入大小、并发和业务额度，避免形成任何人都能调用的开放代理。不同项目或运行环境使用可区分的 Key，便于在使用记录定位来源。

已有本地客户端直接读取用户自己提供的 Key 属于另一种场景，按对应工具接入指南配置。

流式输出的完整示例

下面演示 Python OpenAI SDK 的 Responses 文字流。沿用已设置的 BESTAI_API_KEY、BESTAI_MODEL 和 SDK 环境，将代码保存为 .py 后运行。模型与分组必须支持 Responses；不把这个示例用于 Images API。

示例显式关闭 SDK 自动重试，方便第一次接入时区分每次请求。它同时处理 HTTP 错误、网络错误、失败事件、不完整事件和没有完成事件就断开的情况：

python

import os
import sys
from openai import (
    OpenAI,
    APIError,
    APIStatusError,
    APIConnectionError,
    APITimeoutError,
)

client = OpenAI(
    base_url="https://api.bestai.chat/v1",
    api_key=os.environ["BESTAI_API_KEY"],
    timeout=60.0,
    max_retries=0,
)

completed = False
try:
    with client.responses.create(
        model=os.environ["BESTAI_MODEL"],
        input="用一句话说明流式输出是什么。",
        stream=True,
    ) as stream:
        for event in stream:
            if event.type == "response.output_text.delta":
                print(event.delta, end="", flush=True)
            elif event.type == "response.completed":
                completed = event.response.status == "completed"
            elif event.type in ("response.failed", "response.incomplete", "error"):
                raise SystemExit("\n请求未完成：" + event.type)
except APITimeoutError:
    raise SystemExit("\n请求超时：先检查使用记录，再决定是否重发。")
except APIConnectionError:
    raise SystemExit("\n连接或读取失败：保留已有输出，检查网络与请求记录。")
except APIStatusError as exc:
    print("\nHTTP 状态：", exc.status_code, file=sys.stderr)
    print("请求标识：", exc.request_id or "未返回", file=sys.stderr)
    raise SystemExit("请按 HTTP 状态和脱敏错误正文排查。")
except APIError:
    raise SystemExit("\n流式请求发生错误，已有输出不应视为完整结果。")
except Exception as exc:
    # 某些 SDK / 传输版本会直接抛出底层读取或解析异常。
    raise SystemExit("\n读取未完成（" + type(exc).__name__ + "），请保留部分输出排查。")
finally:
    client.close()

if not completed:
    raise SystemExit("\n连接结束，但未收到完成事件；保留部分输出并检查记录。")
print("\n[请求完成]")

这个示例只展示文字增量。模型拒绝、工具调用或其他输出可能不产生文字增量；收到完成事件表示请求流程结束，不代表内容一定满足任务要求。业务程序还需按自己使用的输出类型处理结果。

把流转发给网页时，应用后端应及时发送数据，避免代理把整个响应缓存到结束才下发；前端分别显示“生成中、完成、未完成”。不要把中断前的一半内容静默当成成功结果。

超时是等待设置，不是执行结果

示例的 timeout=60.0 是网络操作的等待设置，便于演示；不是整项任务必须在 60 秒结束的保证。持续收到流式数据时，总时长可以更长。

按连接、等待首个结果、流中停顿分别记录耗时。图片、长上下文和复杂任务可能需要更长等待；不要只把所有超时无限调大。业务如果有总时长要求，需要另外设置任务期限和取消逻辑。

请求超时或取消后，上游可能已经处理了部分或全部任务。用户看到“超时”时，先保留部分结果，再核对记录，不自动假定本次没有执行或没有用量。

重试由一层统一负责

OpenAI Python SDK 默认会自动重试部分连接错误、408、409、429 和 5xx。接入时先使用 max_retries=0 观察一次请求的结果；准备自动重试前，再决定由 SDK 还是自己的任务队列负责，避免多层重试叠加。

情况	应用侧处理
参数错误、认证错误、Key 过期或额度耗尽	先修正条件，不重发相同请求
临时限流、并发或队列已满	读取 `Retry-After`（若有），降低并发，采用有次数上限的退避
网络超时、5xx，执行结果未知	先查记录；按任务是否允许重复执行决定重试
已经显示部分流式输出	明确标成未完成；重试是新一次结果，不直接拼接两次文本
图片生成或其他代价较高的任务	避免自动重复提交，优先核对已完成结果与使用记录

HTTP 请求 ID 用于追踪，不自动提供幂等语义。仅重复发送相同请求内容或相同标识，不能保证只执行、只计费一次。

留下足够定位问题的记录

建议记录开始时间与时区、工具/SDK 版本、模型、Key 别名、HTTP 状态、总耗时、首个结果耗时、完成状态、尝试次数，以及响应头实际返回的请求标识。

默认不记录认证头、完整对话和图片 Base64。应用内部的业务任务 ID、模型响应 ID、网关响应头里的请求 ID 分开保存，不混为一个字段。出现问题时直接使用排障反馈模板。

从示例转到应用前

确认自己的后端能完成这些行为：

同一请求能按时间、Key 和模型找到对应记录。
Key 失效或 429 时，界面能显示可理解的错误，不无限重试。
流式成功与中断会进入不同状态，部分输出不会被误当完整结果。
用户取消、网络超时和任务重试都有清晰的处理规则。
Key 与额度只由应用后端控制，前端产物不包含服务端密钥。

参考说明

核对日期：2026-10-03。参考 OpenAI 流式响应说明和 Python SDK 的重试、超时与错误处理。SDK 的运行时要求与具体接口随版本变化，安装时按当前官方说明；BestAI 可用协议仍以所选分组为准。

应用接入实践 ​

把 Key 放在应用后端 ​

流式输出的完整示例 ​

超时是等待设置，不是执行结果 ​

重试由一层统一负责 ​

留下足够定位问题的记录 ​

从示例转到应用前 ​

参考说明 ​