使用 OpenAI SDK¶

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

前提条件¶

已准备 Genesis 访问令牌。
已从获取可用模型取得目标模型 ID。
已安装 Python 和官方 OpenAI Python SDK。

pip install openai

配置客户端¶

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

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

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 请求¶

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。

发送 Responses 请求¶

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。

查询可用模型¶

models = client.models.list()

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

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

创建 Embeddings¶

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

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。

使用 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中的 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()` 或获取可用模型重新选择模型。
读取不到 Responses 文本	是否按 Chat Completions 的 `choices[]` 处理响应	遍历 `output[]`，按项目和内容块类型读取 `output_text`。

下一步¶

最后更新于 2026 年 8 月 14 日