文档

文档

即插即用的 OpenAI SDK 兼容层

使用任何支持 OpenAI Chat Completions 协议的 SDK 连接 ModelRiver。只需改两行代码：base URL 和 API key，即可获得路由、故障转移与可观测性。

ModelRiver 提供 OpenAI 兼容适配层，让你可以使用任何支持 OpenAI Chat Completions 协议的 SDK 进行连接。这意味着你可以把 ModelRiver 当作 OpenAI API 的直接替代，同时保留 ModelRiver 的全部能力：智能路由、故障转移、结构化输出、成本追踪等。

支持的 SDK

SDK语言连接方式
OpenAI SDKPython设置 base_url + api_key
OpenAI SDKNode.js设置 baseURL + apiKey
LangChainPythonChatOpenAI(openai_api_base=…)
LlamaIndexPythonOpenAI(api_base=…)
Vercel AIJS/TScreateOpenAI({ baseURL: … })

任何其他遵循 OpenAI REST 结构的 SDK 或 HTTP 客户端也都可以使用。

快速开始

Python（OpenAI SDK）

PYTHON
1from openai import OpenAI
2 
3client = OpenAI(
4 base_url="https://api.modelriver.com/v1",
5 api_key="mr_live_YOUR_API_KEY"
6)
7 
8response = client.chat.completions.create(
9 model="my_workflow", # ← 你的 ModelRiver 工作流名称
10 messages=[
11 {"role": "system", "content": "You are a helpful assistant."},
12 {"role": "user", "content": "What is ModelRiver?"}
13 ],
14 temperature=0.7,
15 max_tokens=500
16)
17 
18print(response.choices[0].message.content)

Python（LangChain）

PYTHON
1from langchain_openai import ChatOpenAI
2 
3llm = ChatOpenAI(
4 openai_api_base="https://api.modelriver.com/v1",
5 openai_api_key="mr_live_YOUR_API_KEY",
6 model="my_workflow"
7)
8 
9response = llm.invoke("What is ModelRiver?")
10print(response.content)

Python（LlamaIndex）

PYTHON
1from llama_index.llms.openai import OpenAI
2 
3llm = OpenAI(
4 api_base="https://api.modelriver.com/v1",
5 api_key="mr_live_YOUR_API_KEY",
6 model="my_workflow"
7)
8 
9response = llm.complete("What is ModelRiver?")
10print(response.text)

Node.js（OpenAI SDK）

JAVASCRIPT
1import OpenAI from "openai";
2 
3const client = new OpenAI({
4 baseURL: "https://api.modelriver.com/v1",
5 apiKey: "mr_live_YOUR_API_KEY",
6});
7 
8const completion = await client.chat.completions.create({
9 model: "my_workflow",
10 messages: [{ role: "user", content: "What is ModelRiver?" }],
11 temperature: 0.7,
12});
13 
14console.log(completion.choices[0].message.content);

Vercel AI SDK（Next.js）

TYPESCRIPT
1import { createOpenAI } from "@ai-sdk/openai";
2import { generateText } from "ai";
3 
4const modelriver = createOpenAI({
5 baseURL: "https://api.modelriver.com/v1",
6 apiKey: "mr_live_YOUR_API_KEY",
7});
8 
9const { text } = await generateText({
10 model: modelriver("my_workflow"),
11 prompt: "What is ModelRiver?",
12});

端点

POST /api/v1/chat/completions

主端点。接受 OpenAI chat completion 请求，并通过 ModelRiver 工作流引擎进行转换执行。

请求头：

Authorization: Bearer mr_live_YOUR_API_KEY
Content-Type: application/json

请求体：

JSON
1{
2 "model": "my_workflow",
3 "messages": [{"role": "user", "content": "Hello"}],
4 "temperature": 0.7,
5 "max_tokens": 500,
6 "top_p": 0.9,
7 "stream": false
8}
字段必填说明
model✅工作流名称（充当模型别名）
messages✅{role, content} 消息对象数组
temperature❌采样温度（0–2），透传给供应商
max_tokens❌响应的最大 token 数
top_p❌Nucleus sampling 参数
stream❌true 启用 SSE，默认 false
tools❌用于函数调用的工具定义数组
tool_choice❌模型如何使用工具（auto、none 等）
n❌必须为 1（仅支持单次 completion）

响应（非流式）：

JSON
1{
2 "id": "chatcmpl-abc123",
3 "object": "chat.completion",
4 "created": 1700000000,
5 "model": "my_workflow",
6 "choices": [{
7 "index": 0,
8 "message": {"role": "assistant", "content": "…"},
9 "finish_reason": "stop"
10 }],
11 "usage": {
12 "prompt_tokens": 10,
13 "completion_tokens": 50,
14 "total_tokens": 60
15 },
16 "system_fingerprint": "mr-v1"
17}

GET /api/v1/models

以 OpenAI 模型对象格式返回你项目中的工作流。

GET /api/v1/provider-models（旧版）

按供应商分组返回原始 ModelRiver 模型列表，用于向后兼容。

model 与工作流的映射关系

你在 OpenAI 请求里填写的 model 字段，会直接映射到 ModelRiver 中的工作流名称。当你发送 "model": "my_workflow" 时：

  1. ModelRiver 会查找同名工作流
  2. 按工作流配置选择供应商、模型、结构化输出、回退链路与缓存字段
  3. 将实际请求路由到底层供应商
  4. 再把结果以 OpenAI 兼容格式返回给你

什么时候选择这种方式

  • 你已有大量基于 OpenAI SDK 的代码
  • 你希望最小化迁移成本
  • 你想保留现有客户端接口，但增加工作流、故障转移与观测能力

下一步