> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/sdk/unified-sdks · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 统一 SDK 与 AI 网关层

「统一 SDK」指一个 SDK 通吃多家供应商（Vercel AI SDK、LiteLLM、Portkey…）。它们与网关的关系有两层：

1. **把网关当「又一个 OpenAI 兼容后端」**——SDK 的 base_url 指到网关，`model` 填网关模型名（本节主体）。
2. **网关与这些 SDK 各自成层**——网关管上游聚合/密钥/计费，SDK 管客户端编排；两者可以叠加（例如 Vercel AI SDK 的 provider 指到网关，网关后面再接多家上游）。

## Vercel AI SDK（TypeScript） {#vercel-ai-sdk}

```bash
npm i ai @ai-sdk/openai-compatible @ai-sdk/anthropic
```

用 `createOpenAICompatible` 把网关当 OpenAI 兼容后端；调 Anthropic 上游则用 `createAnthropic`。

::: code-group

```ts [OpenAI 兼容 provider]
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { generateText } from "ai";

const provider = createOpenAICompatible({
  name: "gatellm",
  baseURL: "http://localhost:7890/v1",
  apiKey: "<你的访问密钥>",
});

const { text } = await generateText({
  model: provider("gpt-5.4-mini"),
  prompt: "用一句话介绍你自己",
});
console.log(text);
```

```ts [Anthropic provider]
import { createAnthropic } from "@ai-sdk/anthropic";
import { generateText } from "ai";

const anthropic = createAnthropic({
  baseURL: "http://localhost:7890/v1",   // 含 /v1，SDK 自动拼 /messages
  apiKey: "<你的访问密钥>",
});

const { text } = await generateText({
  model: anthropic("claude-haiku-4-5"),
  prompt: "用一句话介绍你自己",
});
console.log(text);
```

:::

> 注意 base_url 约定与官方 SDK 相反：`@ai-sdk/anthropic` 的 `baseURL` **含 `/v1`**（它自己拼 `/messages`），而 [官方 Anthropic SDK](/zh-CN/sdk/vendor-sdks.md#anthropic) 的 `base_url` 填到根（它自己拼 `/v1/messages`）。填错会多出或丢掉 `/v1` 段。

**流式 + 结构化输出 + 工具调用**：

```ts
import { streamText, generateObject, tool } from "ai";
import { z } from "zod";

// 流式
const { textStream } = await streamText({
  model: provider("gpt-5.4-mini"),
  prompt: "数到 5",
});
for await (const t of textStream) process.stdout.write(t);

// 结构化输出（OpenAI 兼容 provider 走 json_object 模式，prompt 需带 "json" 字样）
const { object } = await generateObject({
  model: provider("gpt-5.4-mini"),
  schema: z.object({ name: z.string(), age: z.number() }),
  prompt: "生成一个虚构人物，用 JSON 格式",
});
console.log(object);

// 工具调用
const { text } = await generateText({
  model: provider("gpt-5.4-mini"),
  prompt: "北京天气？",
  tools: {
    get_weather: tool({
      description: "查询城市天气",
      parameters: z.object({ city: z.string() }),
    }),
  },
});
```

**Next.js route handler**（`app/api/chat/route.ts`）：

```ts
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { streamText } from "ai";

const provider = createOpenAICompatible({
  name: "gatellm",
  baseURL: process.env.GATELLM_BASE_URL ?? "http://localhost:7890/v1",
  apiKey: process.env.GATELLM_API_KEY ?? "",
});

export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = await streamText({ model: provider("gpt-5.4-mini"), messages });
  return result.toTextStreamResponse();
}
```

## LiteLLM（Python） {#litellm}

LiteLLM 本身也是网关；把它当**客户端 SDK** 用时，设 `api_base` 指向网关：

```python
from litellm import completion

resp = completion(
    model="openai/gpt-5.4-mini",   # openai/ 前缀路由到 OpenAI 兼容 provider
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
    api_base="http://localhost:7890/v1",
    api_key="<你的访问密钥>",
)
print(resp.choices[0].message.content)
```

LiteLLM **proxy**（`config.yaml`）把网关当上游：

```yaml
model_list:
  - model_name: gpt-5.4-mini
    litellm_params:
      model: openai/gpt-5.4-mini
      api_base: http://localhost:7890/v1
      api_key: <你的访问密钥>
```

> `openai/` 前缀是 LiteLLM 的 provider 路由标记；`api_base` 覆盖默认 `api.openai.com`，指向你的网关。

## Portkey {#portkey}

Portkey 是带路由/缓存/回退的 AI 网关。要把网关接到 Portkey 后面，在 Portkey 后台把「Provider」配成一个 **OpenAI 自定义 provider**，其 `baseURL` 填 `http://localhost:7890/v1`、`apiKey` 填网关访问密钥即可；客户端侧仍用 Portkey 自己的 SDK，`model` 填 Portkey 里配置的虚拟模型名。接法同构，细节随 Portkey 版本变化，以 [Portkey 官方文档](https://portkey.ai/docs) 为准。

## Braintrust Gateway / Langbase {#braintrust-langbase}

两者都是「统一 API + 多模型」的服务化网关，接法同 Portkey：把网关登记为一个 OpenAI 兼容的「自定义 provider / model provider」，`baseURL` 指到 `http://localhost:7890/v1`、`apiKey` 用网关访问密钥。这一层与网关是**叠加**关系——是否值得叠加取决于你是否还需要它们的路由/评测能力。

## Semantic Kernel（Python / .NET） {#semantic-kernel}

```bash
pip install semantic-kernel
```

把网关当 OpenAI 兼容后端：

```python
import asyncio
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion

kernel = Kernel()
service = OpenAIChatCompletion(
    service_id="gatellm",
    ai_model_id="gpt-5.4-mini",
    endpoint="http://localhost:7890/v1",
    api_key="<你的访问密钥>",
)
kernel.add_service(service)

async def main():
    resp = await kernel.invoke_prompt("用一句话介绍你自己")
    print(resp)

asyncio.run(main())
```

> 参数名随 Semantic Kernel 版本变化（`endpoint` / `base_url` / `api_key`），以你安装版本的 [Semantic Kernel 官方文档](https://learn.microsoft.com/semantic-kernel/overview) 为准。本节按官方文档编写、未在本环境实跑。

## Spring AI（Java） {#spring-ai}

Spring AI 的 OpenAI starter 走 OpenAI 兼容协议，配 `application.yml`：

```yaml
spring:
  ai:
    openai:
      base-url: http://localhost:7890
      api-key: <你的访问密钥>
      chat:
        options:
          model: gpt-5.4-mini
```

> Spring AI 的 `base-url` 不带 `/v1`（它会自己拼）。Java 示例按 [Spring AI 官方文档](https://docs.spring.io/spring-ai/reference/) 编写、未在本环境实跑。

## 下一步 {#next}

- 编排框架（LangChain / LlamaIndex / CrewAI…）：看 [编排框架](/zh-CN/sdk/orchestration-frameworks.md)。
- 官方厂商 SDK 的完整能力示例：看 [官方厂商 SDK](/zh-CN/sdk/vendor-sdks.md)。