f

content/guides/openai_compatible.mdx

@@ -0,0 +1,99 @@
+---
+title: OpenAI 兼容 SDK
+sidebarTitle: OpenAI 兼容 SDK
+description: 使用 OpenAI 官方 SDK 对接海宇数科网关（协议兼容，模型为国内 ID）
+---
+
+# OpenAI SDK 兼容
+
+若您已有基于 **OpenAI 官方 SDK** 的应用，迁移到海宇数科通常只需两步：
+
+1. 将 `baseURL`（或 `base_url`）改为 `https://api.haiyushuke.com/v1`  
+2. 将 `apiKey` 改为在海宇控制台创建的 **API Key**
+
+协议兼容 **Chat Completions**（`client.chat.completions.create`），便于零学习成本切换。
+
+## 环境变量（推荐）
+
+```bash
+# Linux / macOS
+export HAIYUSHUKE_API_KEY="sk-..."
+export HAIYUSHUKE_BASE_URL="https://api.haiyushuke.com/v1"
+```
+
+```powershell
+# Windows PowerShell
+$env:HAIYUSHUKE_API_KEY="sk-..."
+$env:HAIYUSHUKE_BASE_URL="https://api.haiyushuke.com/v1"
+```
+
+## Node.js
+
+安装依赖：
+
+```bash
+npm install openai
+```
+
+```ts
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: process.env.HAIYUSHUKE_API_KEY,
+  baseURL: process.env.HAIYUSHUKE_BASE_URL ?? "https://api.haiyushuke.com/v1",
+});
+
+const completion = await client.chat.completions.create({
+  model: "deepseek-chat",
+  messages: [{ role: "user", content: "Hello" }],
+});
+
+console.log(completion.choices[0]?.message?.content);
+```
+
+## Python
+
+安装依赖：
+
+```bash
+pip install openai
+```
+
+```python
+import os
+from openai import OpenAI
+
+client = OpenAI(
+    api_key=os.environ["HAIYUSHUKE_API_KEY"],
+    base_url=os.environ.get("HAIYUSHUKE_BASE_URL", "https://api.haiyushuke.com/v1"),
+)
+
+resp = client.chat.completions.create(
+    model="deepseek-chat",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+print(resp.choices[0].message.content)
+```
+
+## 流式
+
+与 OpenAI 相同，设置 `stream=True` / `stream: true`，详见 [流式调用](/docs/guides/streaming)。
+
+## LangChain 等框架
+
+在 LangChain 中配置自定义 `baseURL` 与 API Key 即可指向海宇网关（具体类名随 LangChain 版本而异，原则与上文一致）。模型名填控制台 **模型 ID**。
+
+## 与直连 OpenAI 的差异
+
+| 项目 | 说明 |
+| --- | --- |
+| 模型名 | 使用海宇 **模型广场 ID**，非 OpenAI 原站名称（若不同） |
+| 账号与计费 | 海宇控制台余额与 **使用记录**，与 OpenAI 账单无关 |
+| 能力边界 | 以各模型在海宇侧实际上线能力为准（工具调用、多模态等） |
+| 密钥 | 必须使用 **API Key**，不能使用控制台登录 JWT |
+
+## 相关文档
+
+- [HTTP API 调用](/docs/guides/http_api)  
+- [工具接入概览](/docs/integrations/overview)  
+- [API Key 管理](/docs/guides/api_keys)