# 从 OpenAI 官方迁移 (/docs/cookbook/migration/from-openai)



保留 OpenAI SDK，改地址、Key 和模型 ID，先迁移一次 Chat Completions 请求。更换模型会改变回答行为；这不是让 DeepSeek 变成 GPT-4o。

```diff
 client = OpenAI(
-    base_url="https://api.openai.com/v1",
-    api_key=os.environ["OPENAI_API_KEY"],
+    base_url="https://api.deepraxis.ai/openai/v1",
+    api_key=os.environ["PRAXIS_API_KEY"],
 )
-model = "gpt-4o"
+model = "deepseek-flash"
```

## 1. 准备 [#1-准备]

需要 Python 3.10+、[uv](https://docs.astral.sh/uv/getting-started/installation/) 和一个 Praxis Key。在[控制台 → API Keys](https://console.deepraxis.ai/keys)创建 Key，将它安全注入当前终端的 `PRAXIS_API_KEY` 环境变量；不要把 Key 写进代码或日志。保留原服务的配置与 Key，供回滚使用。以下命令在 macOS / Linux 的 Bash 中执行。

```bash
test -n "${PRAXIS_API_KEY:-}"
```

期望：退出码 0；退出码 1 表示变量未设置，先设置再继续。

## 2. 选择模型 ID [#2-选择模型-id]

下表是迁移选择，不是别名或等价效果承诺。可用性核对于 2026-10-12；切换流量前再查[模型目录](https://console.deepraxis.ai/models)。

| 原 ID                        | Praxis 选择                          | 需要注意                              |
| --------------------------- | ---------------------------------- | --------------------------------- |
| `gpt-4o`、`gpt-4o-mini`      | `deepseek-flash`                   | 原 ID 不存在；重新评估提示词、工具与回答质量          |
| `gpt-4.1`、`o3-mini`、`gpt-5` | `deepseek-flash`                   | 不自动映射；原 ID 返回 404                 |
| 必须使用 OpenAI 系模型             | `gpt-5.6-sol`                      | 可用 Chat Completions，不支持 Responses |
| 原代码使用 Responses             | `deepseek-flash` 或 `glm-5.3-flash` | 当前可用的 Responses 选择                |

使用 Responses 时，确认选定 ID 出现在 `GET /openai/v1/models?api=responses`（Python：`client.models.list(extra_query={"api": "responses"})`）。也可查看 `GET /model/v1/models` 或 `GET /model/v1/models/{id}` 的 `supported_apis`，确认包含 `openai.responses`。OpenAI 面还可按 `chat`、`embeddings`、`images`、`audio`、`videos` 筛选；逗号分隔表示匹配任一协议。

## 行为差异 [#行为差异]

* 同协议请求按原协议转发，不代表所有官方模型、端点、字段都可用。
* 列表内的模型仍可能对某个操作返回 `404 model_protocol_not_offered`；Chat 与 Responses 要分别确认。
* 切流量前用自己的提示词检查流式、工具执行、结构化输出和思考行为。字段差异以 [Chat Completions](/docs/api/compatible/openai/createChatCompletion) 与 [Responses](/docs/api/compatible/openai/createResponse) 为准。
* 原服务的文件、会话与响应 ID 不随地址修改自动迁移；保留源数据，并重建应用需要的资源。
* Chat 的 `usage.cost` 是实付金额；Responses 和 Messages 目前不返回该字段。收到 `X-Praxis-Generation-Id` 时，可按 [生成记录 API](/docs/api/native/model/getGeneration) 用 `GET /model/v1/generation?id=生成ID` 查费用（记录可能延迟几秒）。若响应没有该头，去[控制台 → 用量与费用](https://console.deepraxis.ai/usage)查本次调用；不要把响应正文的 `id` 或 `X-Request-Id` 当成生成 ID，也不要将缺失费用当成零。

## 不支持的端点与替代 [#不支持的端点与替代]

以下路径相对于 `/openai/v1`，调用返回 404。替代流程不保证与原端点等价；有依赖时先拆分调用，保留原服务。

| 原端点                  | 迁移选择                                    |
| -------------------- | --------------------------------------- |
| `moderations`        | 无直接替代，继续使用原审核服务                         |
| `batches`            | 由应用逐次调用并控制并发                            |
| `fine_tuning`        | 选已有模型；保留原微调流程                           |
| `assistants`         | 重新组织为 Responses / Conversations 与应用工具循环 |
| `completions`        | 改用 `chat/completions` 和 `messages`      |
| `audio/translations` | 先转写，再用对话翻译                              |
| `uploads`            | 改用 `files`；核对文件大小与用途限制                  |
| `images/variations`  | 用 `images/edits` 提交图片与编辑提示词，重新评估效果      |

可用端点包括 `chat/completions`、`responses`、`embeddings`、`images/generations`、`images/edits`、`audio/speech`、`audio/transcriptions`、`videos`、`files`、`models`。可用端点不表示每个模型都支持该能力；具体操作与限制见 [OpenAI API 参考](/docs/api/compatible/openai)。

## 3. 验证一次请求 [#3-验证一次请求]

设置好 `PRAXIS_API_KEY` 后运行以下完整示例：

```bash
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy
uv run -q --no-project --with openai --with anthropic python - <<'PY'
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.deepraxis.ai/openai/v1",
    api_key=os.environ["PRAXIS_API_KEY"],
    timeout=90.0,
    max_retries=0,
)
models = client.models.list(extra_query={"api": "chat"})
assert "deepseek-flash" in {m.id for m in models.data}
raw = client.chat.completions.with_raw_response.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Reply OK."}],
    max_tokens=1024,
)
reply = raw.parse()
text = reply.choices[0].message.content
print("HTTP", raw.status_code)
print("X-Request-Id:", raw.headers.get("x-request-id"))
print("X-Praxis-Generation-Id:", raw.headers.get("x-praxis-generation-id"))
print(text)
assert raw.status_code == 200 and text and text.strip()
assert raw.headers.get("x-request-id")
PY
```

期望：退出码 0，输出 `HTTP 200`、非空正文（通常为 `OK.`）和 `X-Request-Id`。断言同时检查模型存在与真实回复；不是只检查能否连接。保留请求 ID 便于排查，不要记录 Key。示例会产生少量调用费用。

## 失败分支 [#失败分支]

| 实测报错                                   | 处理                                                       |
| -------------------------------------- | -------------------------------------------------------- |
| `404`，`Model "gpt-4o" does not exist.` | 地址与 Key 之外也要改模型；使用目录中的完整 ID                              |
| `404 model_protocol_not_offered`       | 换支持该操作的模型；Responses 选 `deepseek-flash` 或 `glm-5.3-flash` |
| 上表端点返回 `404 Not Found`                 | 按表替代，或让该请求继续使用原服务                                        |

## 4. 回滚 [#4-回滚]

一起恢复三个原值：`https://api.openai.com/v1`、`OPENAI_API_KEY` 中的原 Key、原模型 ID。移除 Praxis 专有请求字段，恢复原资源 ID。重启应用让客户端加载旧配置，再跑原有冒烟请求并保留请求 ID。

期望：原端点成功返回可用正文。配置回滚不会退还已发生的调用费用，也不会在服务之间复制会话状态。

[API 参考 →](/docs/api/compatible/openai) · [兼容指南 →](/docs/cloud/services/model/guides/openai-compatible)