# 使用 OpenAI SDK

使用官方 OpenAI Python SDK 调用 Genesis 的 OpenAI 兼容接口。本页提供 Chat Completions、Responses、模型查询和 Embeddings 的最小调用方式；各接口的完整参数和返回字段请参阅对应接口页。

## 前提条件

- 已准备 Genesis 访问令牌。
- 已从[获取可用模型](../../api/genesis-model-api/getting-started/available-models.md)取得目标模型 ID。
- 已安装 Python 和官方 OpenAI Python SDK。

```bash
pip install openai
```

## 配置客户端

将控制台「使用」页提供的完整 Base URL 配置为 `base_url`，并将 Genesis 访问令牌配置为 `api_key`：

```bash
export GENESIS_BASE_URL='<Genesis Base URL copied from the console>'
export GENESIS_ACCESS_TOKEN="<ACCESS_TOKEN>"
```

```python
import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GENESIS_ACCESS_TOKEN"],
    base_url=os.environ["GENESIS_BASE_URL"],
)
```

`GENESIS_BASE_URL` 使用控制台复制的完整值。不要在 `base_url` 后手动追加 `/chat/completions`、`/responses` 或其他具体接口路径。

## 发送 Chat Completions 请求

```python
completion = client.chat.completions.create(
    model="<CHAT_MODEL_ID>",
    messages=[
        {"role": "user", "content": "用一句话解释数据血缘。"},
    ],
)

print(completion.choices[0].message.content)
```

调用成功后，从 `choices[0].message.content` 读取文本。文本、多模态输入和流式响应的差异见[Chat Completions](../../api/genesis-model-api/openai-compatible/chat-completions/index.md)。

## 发送 Responses 请求

```python
response = client.responses.create(
    model="<RESPONSES_MODEL_ID>",
    input="写一句关于数据库可靠性的短句。",
)

for item in response.output:
    if item.type != "message":
        continue
    for content in item.content:
        if content.type == "output_text":
            print(content.text)
```

Responses 的结果位于 `output[]`，不是 Chat Completions 的 `choices[]`。状态、流式输出、会话和工具能力的适用范围见[Responses API](../../api/genesis-model-api/openai-compatible/responses-api.md)。

## 查询可用模型

```python
models = client.models.list()

for model in models.data:
    print(model.id)
```

返回列表反映当前凭据可调用的模型范围。调用前仍应确认模型是否支持目标接口和所需能力。

## 创建 Embeddings

使用 OpenAI SDK 调用 Embeddings 时，显式传入 `encoding_format="float"`：

```python
embedding_response = client.embeddings.create(
    model="<EMBEDDING_MODEL_ID>",
    input=["MatrixOne 是面向智能时代的数据库。"],
    encoding_format="float",
)

vector = embedding_response.data[0].embedding
print(len(vector))
```

当前服务对 SDK 默认的 Base64 向量形式不具备稳定兼容性。显式请求浮点向量后，从 `data[].embedding` 读取向量数组。有关输入结构、维度和批处理的说明见[Embeddings](../../api/genesis-model-api/retrieval-vector/embeddings.md)。

## 使用 SDK 时的注意事项

| 项目 | 配置或处理方式 |
| --- | --- |
| 认证 | `api_key` 使用 Genesis 访问令牌，由 SDK 发送 `Authorization: Bearer <ACCESS_TOKEN>`。 |
| Base URL | `base_url` 使用控制台提供的完整 Genesis Base URL。 |
| 模型 | 每次调用使用当前凭证可访问、且支持目标接口的模型 ID。 |
| Chat Completions 流式输出 | 通过该接口的 `stream` 参数处理增量事件；不要将其事件格式用于 Responses。 |
| Responses | 按 `output[]` 中项目和内容块的类型读取结果。 |
| Embeddings | 显式设置 `encoding_format="float"`，并按 `data[].index` 对齐批量输入。 |
| Rerank | 本页不承诺 OpenAI SDK 的 Rerank 调用方式；请使用[Rerank](../../api/genesis-model-api/retrieval-vector/rerank.md)中的 HTTP 接口。 |

## 常见问题

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| `401` 或认证错误 | `api_key`、访问令牌状态和 Base URL | 确认访问令牌有效，并使用控制台提供的完整 Base URL。 |
| `404` 或接口路径不正确 | `base_url` 是否被手动追加了接口路径或重复版本段 | 将 `base_url` 恢复为控制台复制的完整 Base URL。 |
| Embeddings 返回异常 | 是否省略 `encoding_format="float"` | 显式请求浮点向量，并从 `data[].embedding` 读取结果。 |
| 模型不可用 | 模型 ID 与当前凭据范围 | 使用 `client.models.list()` 或[获取可用模型](../../api/genesis-model-api/getting-started/available-models.md)重新选择模型。 |
| 读取不到 Responses 文本 | 是否按 Chat Completions 的 `choices[]` 处理响应 | 遍历 `output[]`，按项目和内容块类型读取 `output_text`。 |

## 下一步

- [调用 Chat Completions](../../api/genesis-model-api/openai-compatible/chat-completions/index.md)
- [调用 Responses API](../../api/genesis-model-api/openai-compatible/responses-api.md)
- [创建 Embeddings](../../api/genesis-model-api/retrieval-vector/embeddings.md)
- [管理 Genesis 访问凭据](../../../guides/genesis/api-keys.md)