面向多模型产品的 OpenAI API 访问：生产环境搭建指南

获取 OpenAI API key 很容易。真正的工程工作，是设计在产品增加更多模型时依然保持安全、可测试且可替换的OpenAI API access。

对于原型，一个个人 key 和一次模型调用可能就够了。生产级多模型产品需要不同的方案：按项目划分的凭据、独立环境、明确的端点和能力检查、限流处理、使用情况可见性，以及引入备用提供方的受控路径。

本指南将这些要求转化为实施清单。它先介绍直接的 OpenAI 访问，然后说明当你的产品扩展到一个以上的提供方时，OpenAI-compatible gateway 可以在哪些地方减少运维工作。

Checked July 28, 2026: OpenAI's current platform guidance centers API development on projects, supports project service accounts and restricted key permissions, recommends secure server-side key handling, and positions the Responses API as the primary interface for new agentic and multimodal workflows. Verify current model access and limits in your own account before production deployment.

The Short Version

新建多模型产品时，请按以下顺序：

1. 为开发、预发布和生产创建独立的 OpenAI projects。
2. 为服务器工作负载使用 project service account 或权限范围非常严格的 project key。
3. 将 secrets 保留在服务器端，且不要放在源代码管理、浏览器和移动应用中。
4. 根据应用实际使用的功能，选择 Responses API 或 Chat Completions。
5. 分别测试 model availability、structured outputs、tools、streaming 和 multimodal inputs。
6. 衡量 rate limits、timeouts、retries、latency 以及每次成功任务的成本。
7. 通过 configuration 来管理 provider base URL、key 和 model。
8. 只有在你已经有共享 evaluation set 和 rollback path 之后，再添加第二个 provider。

目标不仅仅是让一次请求成功，而是让访问具备可治理性和可移植性。

What OpenAI API Access Means in Production

生产环境访问包含六层。如果其中任何一层保持隐含，它通常都会在后续演变成事故。

这个访问矩阵比一份 API 密钥列表更有用。它把每个凭证绑定到一个工作负载，把每个工作负载绑定到一份合同，把每份合同绑定到一个运行计划。

Step 1: Separate Projects by Environment

OpenAI 项目为 API 密钥、服务账号、用量、模型访问、速率限制和预算提供了边界。这使得项目成为区分开发、预发布和生产环境的正确起点。

一个实用的结构是：

不要在笔记本电脑、CI、预发布环境和多个服务之间共享同一个生产密钥。共享凭证会让轮换变得有破坏性，也会让归因意外用量变得困难。

OpenAI 将项目服务账号定义为项目范围内的身份。创建服务账号时，其密钥只会显示一次，因此请立即将其存入你的密钥管理器。OpenAI 还支持 All、Restricted 和 Read Only 等密钥权限；请根据工作负载使用最小且兼容的权限。

Step 2: Keep API Keys Server-Side

OpenAI API 密钥是机密信息，而不是应用标识符。切勿将其暴露在浏览器 JavaScript、移动应用安装包、公共仓库、客户端日志或支持工单截图中。

使用环境变量或托管密钥存储：

OPENAI_API_KEY="your-project-or-service-account-key"
OPENAI_MODEL="your-validated-model-id"
OPENAI_BASE_URL="https://api.openai.com/v1"

然后在一个服务器端模块中创建客户端：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
)

即使你今天只使用 OpenAI，base URL 也应该放在配置中。这个小选择能让预发布代理、区域性基础设施以及未来与 OpenAI 兼容的路由更容易测试，而无需修改每个调用点。

Minimum key-management policy

• 为每个生产凭证分配一个负责人。
• 记录使用它的服务和环境。
• 将其存放在密钥管理器中，而不是共享文档里。
• 按计划轮换，并在怀疑泄露后立即轮换。
• 移除未使用的密钥和前团队成员的访问权限。
• 对异常用量和支出变化进行告警。
• 避免将密钥嵌入图片、工单、分析事件或应用错误中。

OpenAI 的密钥安全指南也建议不要将密钥提交到仓库中，并使用环境变量而不是硬编码。

Step 3: Choose the API Interface Before the Model

模型选择往往最受关注，但端点选择通常会带来更大的迁移成本。

OpenAI 现行文档建议：对于需要内置工具、多模态输入或类 agent 工作流的新项目，使用 Responses API。Chat Completions 在你的应用已经有稳定的基于消息集成，或者需要与 OpenAI 风格的客户端和网关保持广泛兼容时，仍然非常有用。

多模型架构可以使用不止一种接口。关键原则是显式定义每种工作负载的契约，而不是把不兼容的行为隐藏在一个通用的 generate() 函数后面。

步骤 4：运行访问烟雾测试

从最小的服务端请求开始，用它来证明身份验证、端点访问和模型访问都正常。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
)

response = client.responses.create(
    model=os.environ["OPENAI_MODEL"],
    input="Return exactly: access-ok",
)

print(response.output_text)

对于现有的 Chat Completions 客户端：

response = client.chat.completions.create(
    model=os.environ["OPENAI_MODEL"],
    messages=[
        {"role": "user", "content": "Return exactly: access-ok"}
    ],
)

print(response.choices[0].message.content)

不要把这当作完整的集成测试。它只能证明一条狭窄路径可用。

记录：

• HTTP 状态和规范化后的应用结果
• 请求的模型 ID 和返回的模型 ID（如可用）
• 请求 ID 或追踪标识符
• 延迟和超时
• 输入和输出用量
• 项目和环境
• SDK 版本
• 重试次数

步骤 5：构建能力测试矩阵

模型名称变化得比生产需求更快。测试能力，而不是营销标签。

为每个工作负载创建一行：

对于每个候选模型，测试相同的提示词集合和相同的评分规则。包含格式错误的输入、空上下文、长上下文、超时以及提供方错误。一个成功的演示提示并不能证明其具备生产环境兼容性。

有用的指标包括：

• 任务成功率
• schema 有效响应率
• 工具调用成功率
• p50 和 p95 延迟
• 重试率
• 每次成功任务的成本
• 人工升级率

这就是 OpenAI API 访问 与多模型路由之间的桥梁：路由应基于测得的工作负载性能，而不是静态的提供方偏好。

步骤 6：规划速率限制和使用层级

OpenAI 速率限制可能适用于请求和 token 等多个维度，且限制会因模型和账户层级而异。在设置生产并发之前，请先查看你所在组织和模型的当前限制页面。

你的客户端至少应区分以下四类失败：

使用带抖动的指数退避，并设置最大尝试次数。为整个操作设置总时间预算，而不仅仅是每个 HTTP 调用。否则，三次长重试可能会超过面向用户的服务级目标。

对于适合异步或批处理的工作，队列可以吸收临时限制。对于交互式工作，经过验证的回退模型可能更合适。这些是不同的运行模式，应当有不同的重试策略。

步骤 7：设计多模型边界

添加更多模型有两种常见方式。

选项 A：直接提供方集成

为每个提供方使用独立的原生 SDK 和凭据。

这适用于以下情况：

• 你需要立即使用特定供应商的功能；
• 你的团队可以管理多个计费账户和凭据；
• 你希望尽早获得各供应商的原生能力；
• 你已准备好自行规范化错误、用量、重试和遥测。

Option B: An OpenAI-compatible gateway

使用一个兼容的基础 URL，并通过配置或路由策略选择模型。

在以下情况下，这是一个不错的选择：

• 多个工作负载共享 OpenAI 客户端模式；
• 你希望有一层统一的访问、计费、配额和用量管理；
• 你需要更快的模型评估和回退实验；
• 供应商账户管理正逐渐成为运维负担。

Flatkey 提供一个 OpenAI-compatible 基础 URL：https://router.flatkey.ai/v1。对于兼容的工作负载，客户端边界可以保持稳定，而密钥、基础 URL 和模型则迁移到配置中。

FLATKEY_API_KEY="your-flatkey-key"
OPENAI_BASE_URL="https://router.flatkey.ai/v1"
FLATKEY_MODEL="your-validated-flatkey-model-id"

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url=os.environ["OPENAI_BASE_URL"],
)

“OpenAI-compatible” 并不意味着每个端点和参数的行为都完全相同。在切换生产流量之前，请重新运行针对流式输出、结构化输出、工具、多模态输入、错误响应、用量字段和超时的能力矩阵。

如需实际迁移步骤，请使用 OpenAI-compatible API gateway migration checklist。如需模型级测试，请使用 multi-model prompt testing workflow。

Step 8: 使用预发布、影子测试和金丝雀发布

即使新路径通过了所有离线评估，也要采用分阶段发布。

1. Staging: 在接近生产的并发和超时设置下运行具有代表性的流量。
2. Shadow: 将符合条件的请求复制到候选路径，但不将其响应用于客户。
3. Canary: 将一小部分真实流量发送到候选方案。
4. Expand: 仅当成功率、延迟和成本都保持在阈值内时，才增加流量。
5. Rollback: 通过配置恢复先前的密钥、基础 URL 和模型。

在发布前定义回滚阈值。示例包括：

• schema-valid rate 低于基线；
• p95 延迟超过工作负载 SLO；
• 重试率或 429 率高于约定上限；
• 在受保护的客户细分上任务成功率下降；
• 每个成功任务的成本超过预算阈值；
• 必需的工具或模态失败。

回滚必须能够由值班工程师在无需部署代码的情况下执行。

生产就绪的 OpenAI API 访问检查清单

身份与密钥

• 开发、预发布和生产环境使用独立的项目或等效边界。
• 生产环境使用项目服务账号或最小权限范围的项目密钥。
• 密钥存储在服务端的密钥管理器中。
• 密钥所有者、服务、环境、创建日期以及轮换流程均有文档记录。
• 密钥不应出现在仓库、浏览器构建包、移动应用、日志和工单中。

API 合同

• 针对每种工作负载都记录了端点选择。
• 已在目标项目中验证当前模型访问权限。
• 所需工具、模态、结构化输出和流式传输都已单独测试。
• SDK 和 API 行为已固定版本或记录在案，以保证可复现性。
• 提供商特定字段与共享应用逻辑隔离。

可靠性和成本

• 已测试 401/403、429、4xx、5xx 和超时行为。
• 重试使用指数退避、抖动、尝试次数上限以及总时间预算。
• 可观测使用量、延迟、请求 ID、错误和成本。
• 已针对当前项目限制测试并发能力。
• 成本按每个成功任务衡量，而不只是按每个 token 衡量。

多模型就绪性

• Base URL、API 密钥和模型都是配置值。
• 候选模型使用同一套具有代表性的评估集。
• 回退规则按工作负载分别定义。
• 预发布、影子流量、金丝雀和回滚流程均有文档记录。
• 已针对每项所需功能测试网关兼容性。

常见问题

每个开发者都需要一个 OpenAI 账号吗？

可以将开发者添加到相关组织和项目中，并赋予适当角色。生产工作负载应使用专用的项目服务账号或项目凭证，而不是个人密钥。

多模型产品应该使用 Responses API 还是 Chat Completions？

对于需要 agentic 功能、内置工具或多模态行为的新 OpenAI 原生工作流，请使用 Responses API。若与现有稳定合同相匹配，或 OpenAI 兼容的可移植性更重要，则保留 Chat Completions。无论采用哪种方式，都要测试你实际需要的确切能力。

我可以把 OpenAI API 密钥放在前端应用中吗？

不可以。应通过后端转发请求，这样密钥才能保持机密，同时你也可以强制执行身份验证、配额、日志记录和滥用控制。

一次成功的 API 调用是否就能证明生产访问已经可用？

不能。它只能证明某个密钥、端点、模型和请求曾成功执行一次。生产就绪还需要权限检查、能力测试、速率限制行为、可观测性、成本测量和回滚。

什么时候应该添加 API 网关？

当管理不同提供商的密钥、计费、配额、重试和使用日志开始拖慢产品交付时，或者当你需要可重复的跨模型测试和回退路由时，就应该添加。若提供商原生功能在战略上很重要，并且你的团队能够运维额外的集成，则可以保持直接访问提供商。

构建可演进的访问方式

最佳的 OpenAI API 搭建方案，不是配置项最少的那个，而是能够让所有权、权限、工作负载合同、限制和回滚都一目了然的那个。

如果产品只需要直接使用 OpenAI 访问，就从这里开始。将密钥、基础 URL 和模型放在同一层配置中。在添加其他提供商之前，先构建一套能力测试矩阵。然后，如果多提供商运维成为瓶颈，再把兼容的工作负载迁移到统一路由层，同时保留证明其可用性的测试。

Flatkey 为多模型团队提供一个兼容 OpenAI 的基础 URL、一个密钥以及集中化的使用控制。请查看当前模型访问与定价，然后按照 Flatkey 集成入门运行你的第一个受控测试。

OpenAI 官方参考资料

• 生产最佳实践
• 迁移到 Responses API
• 速率限制
• 在 API 平台中管理项目
• API 密钥安全最佳实践