文档

文档

ModelRiver Docs

OpenAI SDK 兼容性

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", # ← your ModelRiver workflow name
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});

端点（Endpoints）

POST /api/v1/chat/completions

主要端点。接受 OpenAI Chat Completions 请求并通过 ModelRiver 的工作流引擎对其进行处理。

Headers:

Authorization: Bearer mr_live_YOUR_API_KEY
Content-Type: application/json

Request body:

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❌核采样参数
stream❌true 用于 SSE 流式传输，默认为 false
tools❌用于函数调用的工具定义数组
tool_choice❌模型应如何使用工具（auto, none 等）
n❌必须为 1（仅支持单个 completions）

Response (non-streaming):

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

Returns your project's workflows as OpenAI-format model objects.

JSON
1{
2 "object": "list",
3 "data": [
4 {
5 "id": "my_workflow",
6 "object": "model",
7 "created": 1700000000,
8 "owned_by": "modelriver",
9 "permission": [],
10 "root": "openai/gpt-4o-mini",
11 "modelriver_metadata": {
12 "provider": "openai",
13 "provider_model": "gpt-4o-mini",
14 "test_mode": false,
15 "request_type": "chat"
16 }
17 }
18 ]
19}

GET /api/v1/provider-models (Legacy)

返回按供应商分组的原始 ModelRiver 模型列表，以实现向后兼容。

流式传输（Streaming）

设置 "stream": true 以接收 Server-Sent Events (SSE)：

PYTHON
1stream = client.chat.completions.create(
2 model="my_workflow",
3 messages=[{"role": "user", "content": "Tell me a story"}],
4 stream=True
5)
6 
7for chunk in stream:
8 if chunk.choices[0].delta.content:
9 print(chunk.choices[0].delta.content, end="")

Each SSE event follows the OpenAI delta format:

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
 
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
 
data: [DONE]

流式传输特性：

  • 每 15 秒发送一次心跳注释（: heartbeat）以保持连接活跃。
  • 对于长时间运行的请求，超时时间为 5 分钟。
  • 在流结束时具有正确的 [DONE] 标记。

它是如何工作的：model ↔ 工作流映射

您 OpenAI 请求中的 model 字段直接映射到 ModelRiver 中的 工作流名称。当您发送 "model": "my_workflow" 时：

  1. 适配器查找您项目中名为 my_workflow 的工作流。
  2. 使用该工作流配置的供应商和模型（例如 openai/gpt-4o-mini）。
  3. 应用所有的工作流功能：故障转移、结构化输出、系统指令等。
  4. 响应被转换回 OpenAI 格式。

这意味着您可以在 ModelRiver 控制台中更改底层供应商/模型，而无需更改任何客户端代码。

函数调用（Function Calling）

ModelRiver 通过 tools 和 tool_choice 支持与 OpenAI 兼容的函数调用。工具会被直接传递给底层供应商（OpenAI，xAI，Mistral），并且 tool_calls 会以标准的 OpenAI 格式返回。

Python 代码示例

PYTHON
1response = client.chat.completions.create(
2 model="my_workflow",
3 messages=[{"role": "user", "content": "What's the weather in Paris?"}],
4 tools=[{
5 "type": "function",
6 "function": {
7 "name": "get_weather",
8 "description": "Get the current weather for a location",
9 "parameters": {
10 "type": "object",
11 "properties": {
12 "location": {"type": "string", "description": "City name"}
13 },
14 "required": ["location"]
15 }
16 }
17 }],
18 tool_choice="auto"
19)
20 
21# 检查模型是否想进行函数调用
22message = response.choices[0].message
23if message.tool_calls:
24 for tool_call in message.tool_calls:
25 print(f"Function: {tool_call.function.name}")
26 print(f"Arguments: {tool_call.function.arguments}")
27else:
28 print(message.content)

带有 tool_calls 的响应：

JSON
1{
2 "choices": [{
3 "index": 0,
4 "message": {
5 "role": "assistant",
6 "content": null,
7 "tool_calls": [{
8 "id": "call_abc123",
9 "type": "function",
10 "function": {
11 "name": "get_weather",
12 "arguments": "{\"location\": \"Paris\"}"
13 }
14 }]
15 },
16 "finish_reason": "tool_calls"
17 }]
18}

注意：函数调用支持要求底层的供应商/模型本身支持该功能（例如 OpenAI GPT-4+，xAI Grok，Mistral）。像 Google (Gemini) 和 Anthropic 等提供商使用不同的工具格式，目前还不支持通过此适配器进行调用。

不支持的参数

以下 OpenAI 协议中的参数暂不支持，使用它们会引发错误：

  • functions / function_call：旧版函数调用格式（请改用 tools）。
  • logprobs / top_logprobs：对数概率。
  • n > 1：仅支持单个模型完成（completions）。

错误格式

错误信息遵循 OpenAI 的标准错误结构（error envelope）：

JSON
1{
2 "error": {
3 "message": "Workflow 'xyz' does not exist. Create it in the console first.",
4 "type": "invalid_request_error",
5 "param": "model",
6 "code": "model_not_found"
7 }
8}

常见错误代码：

HTTP代码 (Code)含义
400invalid_request_error参数缺失或者无效
401authentication_errorAPI 密钥无效或未提供
404model_not_found指定的工作流不存在
400model_not_supported对应工作流是事件驱动型的（应当使用异步的 API 处理）
502upstream_error底层供应商返回报错
503service_unavailable特性被禁用，或者系统内部出现错误

功能特性开关（Feature Flag）

OpenAI 兼容层功能目前由 OPENAI_COMPAT_ENABLED 环境变量进行控制。要启用它，请将其设为 "true"（它默认处于启用状态）。

当它被禁用时，调用请求 POST /chat/completions 将返回：

JSON
1{
2 "error": {
3 "message": "OpenAI compatibility layer is not enabled.",
4 "type": "invalid_request_error",
5 "code": "feature_disabled"
6 }
7}

可观测性（Observability）

所有通过兼容层的请求都支持：

  • ✅ 记录在请求日志中（使用带有 compat:openai: 前缀的 seed_batch）
  • ✅ 通过遥测指标进行跟踪（modelriver.openai_compat.*）
  • ✅ 受速率限制和使用情况跟踪的约束
  • ✅ 在 ModelRiver 仪表板中可见

从直接调用 OpenAI 迁移

如果您目前主要是在使用直接调用 OpenAI API：

  1. 在 ModelRiver 后台中创建工作流（workflow）。
  2. 更改 base_url 的值为您的 ModelRiver API URL。
  3. 更改 api_key 的值为您的 ModelRiver API 密钥。
  4. 更改 model 设定为您刚刚新配的工作流名称。
  5. 就是这样：不需要进行其它更多的代码重写。