OpenAI SDK 集成 — Markdown 源文

> **AI Agents**: 索引 `/api/llms.txt` | 英文全文 `/api/llms-full-en.txt` | 中文全文 `/api/llms-full-zh.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# OpenAI SDK 集成

SupaNexus 可作为 OpenAI API 的 **即插即用替代**。只需修改 `base_url`（或 `baseURL`）和 `api_key`。

## 配置对照

| OpenAI 默认 | SupaNexus 值 |
|-------------|----------|
| `https://api.openai.com/v1` | `<BASE_URL>/v1` |
| OpenAI API Key | SupaNexus 项目 API Key |

> 表中 `<BASE_URL>` 取值见 [接入点](./endpoints.md)。

## Python

```python
from openai import OpenAI

client = OpenAI(
    base_url="<BASE_URL>/v1",
    api_key="whale-project-api-key",
)

# 非流式
response = client.chat.completions.create(
    model="deepseek/deepseek-chat",
    messages=[{"role": "user", "content": "你好！"}],
)
print(response.choices[0].message.content)

# 流式
with client.chat.completions.stream(
    model="deepseek/deepseek-chat",
    messages=[{"role": "user", "content": "你好！"}],
) as stream:
    for event in stream:
        if event.type == "content.delta":
            print(event.delta, end="", flush=True)
```

### 环境变量

```bash
export OPENAI_API_KEY="whale-project-api-key"
export OPENAI_BASE_URL="<BASE_URL>/v1"
```

许多读取 `OPENAI_*` 的工具可零代码切换。

## Node.js / TypeScript

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "<BASE_URL>/v1",
  apiKey: process.env.SNX_API_KEY,
});

const response = await client.chat.completions.create({
  model: "deepseek/deepseek-chat",
  messages: [{ role: "user", content: "你好！" }],
});

console.log(response.choices[0]?.message?.content);
```

## LangChain

```python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="<BASE_URL>/v1",
    api_key="whale-project-api-key",
    model="deepseek/deepseek-chat",
)
```

## 与 OpenAI 的差异

| 主题 | SupaNexus 行为 |
|------|------------|
| 模型 id | 使用 `GET /v1/models` 返回的 `id`（如 `vendor/model`），非 OpenAI 模型名 |
| Embeddings / Images | 路由已注册但返回 **501** — 尚未可用 |
| 额外响应头 | Chat 上有 `X-SNX-Trace-ID`、`X-SNX-Model`、`X-SNX-Provider` |
| 计费 | 按组织/项目计量；用量见控制台 |

## 路线图（尚未可用）

以下端点已注册但返回 HTTP **501**：

- `POST /v1/embeddings`
- `POST /v1/images/generations`

正式发布前请勿在生产集成中使用。

## 相关

- [快速开始](./quickstart.md)
- [模型](./models.md)
- [流式响应](./streaming.md)