OpenAI 兼容 API

如何接入 OpenAI 兼容 API？

接入 OpenAI 兼容 API 的核心并不是复制一段代码，而是先确认账号可用模型、将 SDK 基础地址指向正确端点、用独立测试密钥完成最小请求验证。这样做可以在迁移已有应用时，尽早发现模型名称、权限或参数差异。

第一步：使用单独的测试密钥

不要直接拿生产密钥进行首次调试。先在控制台创建一个只用于本地或测试环境的密钥，并通过环境变量注入运行环境。这样既能区分使用记录，也能在调试结束后随时撤销，不会影响线上服务。

第二步：查询模型而非猜模型名

模型目录会更新，不同账号能使用的范围也可能不同。先调用 GET https://longhua-ai.com/v1/models，再从结果中选择模型名称。把模型名配置化，而不是散落在业务代码中，后续调整会更安全。

第三步：配置 SDK 基础地址

以 Python SDK 为例，将基础地址设置为 https://longhua-ai.com/v1，然后按常规的聊天完成接口发起请求。请求结构兼容并不代表每项扩展参数都被每个模型支持；第一次验证应从消息、模型名和最小生成参数开始。

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LONGHUA_API_KEY"],
    base_url="https://longhua-ai.com/v1",
)

response = client.chat.completions.create(
    model=os.environ["LONGHUA_MODEL"],
    messages=[{"role": "user", "content": "请用一句话介绍自己。"}],
)
print(response.choices[0].message.content)

第四步：从最小请求扩展到业务请求

最小请求成功后，再逐项加入流式输出、系统消息、工具调用、结构化输出或多模态字段。每增加一项能力，都记录模型、请求参数和失败响应。这样问题出现时，可以判断是 SDK 配置、模型能力还是业务参数导致的。

常见迁移误区

把基础地址写成网页地址：SDK 应使用 API 版本路径，而不是登录或控制台路径。
使用文章中的旧模型名：始终以当前 /v1/models 返回为准。
把密钥放到浏览器端：前端代码和公开仓库都不应保存可用密钥。
默认所有参数通用：先看模型文档和实测结果，再启用模型特有能力。

上线前检查

将密钥放入受控环境变量；设置连接、读取和整体超时；记录不包含敏感内容的错误上下文；为可恢复失败设置有限次数的重试。更多完整示例见快速接入，密钥管理建议见安全实践清单。