OpenRouter 平台功能

OpenRouter 平台功能

预设

3 分钟阅读

预设

管理 LLM 配置

预设 让你把 LLM 配置与代码分离。通过 OpenRouter Web 应用创建和管理预设，以控制模型服务提供商路由、模型选择、系统提示词和其他参数，然后在 OpenRouter API 请求中引用它们。

什么是预设？

预设是封装特定场景所需全部设置的命名配置。例如，你可以创建：

  • 用于生成营销文案的 "email-copywriter" 预设
  • 用于对客户咨询分类的 "inbound-classifier" 预设
  • 用于分析拉取请求的 "code-reviewer" 预设

每个预设可以管理：

  • 模型服务提供商路由偏好（按价格、延迟等排序）
  • 模型选择（特定模型，或带回退的模型数组）
  • 系统提示词
  • 生成参数（temperature、top_p 等）
  • 模型服务提供商的纳入/排除规则
  • 工具，包括 OpenRouter 服务端工具，例如 Web 搜索、Advisor 和 子智能体

快速开始

  1. 创建预设。例如，选择一个模型，并将模型服务提供商路由限制为少数几个提供商。

    创建新预设

  2. 向该预设发出 API 请求：

    {
  "model": "@preset/ravenel-bridge",
  "messages": [
    {
      "role": "user",
      "content": "你觉得金门大桥怎么样？是不是很美？"
    }
  ]
}

优势

关注点分离

预设帮助你在应用代码与 LLM 配置之间保持清晰分离。这让代码更语义化、更易于维护。

快速迭代

无需部署代码变更即可更新 LLM 配置：

  • 切换到新的模型版本
  • 调整系统提示词
  • 修改参数
  • 更改模型服务提供商偏好

使用预设

在 API 请求中使用预设有三种方式。

  1. 直接引用模型

你可以像引用模型一样引用预设，将请求发送到 @preset/preset-slug

{
  "model": "@preset/email-copywriter",
  "messages": [
    {
      "role": "user",
      "content": "写一封关于我们新功能的营销邮件"
    }
  ]
}
  1. preset 字段
{
  "model": "openai/gpt-4",
  "preset": "email-copywriter",
  "messages": [
    {
      "role": "user",
      "content": "写一封关于我们新功能的营销邮件"
    }
  ]
}
  1. 模型与预设组合
{
  "model": "openai/gpt-4@preset/email-copywriter",
  "messages": [
    {
      "role": "user",
      "content": "写一封关于我们新功能的营销邮件"
    }
  ]
}

预设中的工具

预设可以存储 tools 数组，格式与你在请求中发送的完全相同。这包括：

  • OpenRouter 服务端工具，例如 openrouter:web_search、openrouter:advisor 和 openrouter:subagent。Advisor 和子智能体工具可以出现多次，每个命名实例一条，因此单个预设可以定义一整套命名工作者（参见 子智能体 和 Advisor 文档）。
  • 函数工具及其他自定义工具定义，会原样存储并转发。

例如，预设可以将设计助手与一组命名子智能体打包在一起（一个负责创意构思，一个生成图像和效果图，一个负责前端设计）：

{
  "tools": [
    {
      "type": "openrouter:subagent",
      "parameters": {
        "name": "ideator",
        "model": "anthropic/claude-fable-5",
        "instructions": "你负责头脑风暴创意方向、命名和文案。返回若干风格各异的方案。"
      }
    },
    {
      "type": "openrouter:subagent",
      "parameters": {
        "name": "mockup artist",
        "instructions": "你为所给概念生成图像和 UI 效果图。",
        "tools": [
          {
            "type": "openrouter:image_generation",
            "parameters": { "model": "openai/gpt-5.4-image-2" }
          }
        ]
      }
    },
    {
      "type": "openrouter:subagent",
      "parameters": {
        "name": "frontend designer",
        "model": "moonshotai/kimi-k3",
        "instructions": "你将已批准的效果图转化为干净、响应式的前端代码。"
      }
    }
  ]
}

任何引用 @preset/{slug} 的客户端都会在服务端应用这些工具，无需 SDK 或编排代码；之后你可以增删或调优工具，而无需改动客户端。

预设工具如何与请求工具合并

当引用预设的请求同时也发送自己的 tools 时，两个数组合并取并集，请求中的工具会覆盖预设中身份相同的工具（与请求字段覆盖预设配置的其他位置一致）。身份按工具种类判定：

  • openrouter:advisor 和 openrouter:subagent 条目以类型加上 parameters.name 为键，因此请求可以覆盖某一个命名实例，同时保留预设中的其他实例。
  • 函数工具以函数名为键。
  • 其他 OpenRouter 服务端工具（例如 openrouter:web_search）是单例，以类型为键。

预设工具保持相对顺序；仅存在于请求中的工具会追加在其后。

从 API 请求创建预设

除控制台外，你还可以直接从已在使用的任意推理请求体创建（或更新）预设。 当你想把已知可用的请求捕获为可复用配置、而不必在界面中重新输入时，这很有用。

每种推理接口都有自己的端点。发送与对应推理路由相同的 JSON 请求体即可。 OpenRouter 只会持久化与预设配置重叠的字段 （例如 model、temperature、provider、top_p、system、 tools）。 messages、input、prompt 和 stream 等瞬时字段会被静默忽略。

端点为：

  • POST /api/v1/presets/{slug}/chat/completions，Chat Completions 接口
  • POST /api/v1/presets/{slug}/messages，Anthropic Messages 接口
  • POST /api/v1/presets/{slug}/responses，Responses 接口

路径参数 {slug} 是预设的 URL 安全标识符。 如果该 slug 的预设在工作区中已存在，会创建新版本并将其指定为当前活动版本。 如果不存在，则创建新预设。

从 Chat Completions 请求

复用你本来会 POST /api/v1/chat/completions 的请求体：

curl https://openrouter.ai/api/v1/presets/email-copywriter/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "temperature": 0.7,
    "provider": { "sort": "price" },
    "messages": [
      { "role": "system", "content": "你是一名乐于助人的助手。" },
      { "role": "user", "content": "写一封营销邮件。" }
    ]
  }'

messages 数组不会用于预设存储；只有配置字段（model、temperature、provider）以及提取出的系统提示词会被持久化。

从 Anthropic Messages 请求

curl https://openrouter.ai/api/v1/presets/code-reviewer/messages \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-4.6-sonnet",
    "max_tokens": 1024,
    "system": "你是一名资深代码审查员。",
    "messages": [
      { "role": "user", "content": "审查这个 PR。" }
    ]
  }'

顶层 system 字段会成为预设的系统提示词。

从 Responses 请求

curl https://openrouter.ai/api/v1/presets/inbound-classifier/responses \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "instructions": "对收到的消息进行分类。",
    "input": "你好，我需要退款。"
  }'

instructions 字段会成为预设的系统提示词。

响应形态

三个端点都会返回结果预设及其指定版本：

{
  "data": {
    "id": "650e8400-e29b-41d4-a716-446655440001",
    "name": "email-copywriter",
    "slug": "email-copywriter",
    "status": "active",
    "designated_version_id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2026-04-20T10:00:00Z",
    "updated_at": "2026-04-20T10:00:00Z",
    "designated_version": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "version": 1,
      "system_prompt": "你是一名乐于助人的助手。",
      "config": {
        "model": "openai/gpt-4o",
        "temperature": 0.7,
        "provider": { "sort": "price" }
      },
      "created_at": "2026-04-20T10:00:00Z",
      "updated_at": "2026-04-20T10:00:00Z"
    }
  }
}

创建后，该预设可通过 使用预设 中展示的三种引用方式，用于后续推理请求。

建议工作流

  1. 针对 /chat/completions（或 /messages / /responses）构建并测试请求，直到产出你想要的输出。
  2. 将同一请求体 POST 到对应的 /api/v1/presets/{slug}/... 端点以捕获配置。
  3. 在生产代码中，将推理调用改为引用 @preset/{slug}，而不再重复配置。

这样你可以在代码中迭代提示词和参数，然后将可用配置提升为预设，无需手工转录。

其他说明

  1. 如果使用的是组织账户，所有成员都可以访问组织预设。这是在团队间共享最佳实践的好方法。
  2. 系统会保留版本历史，便于了解所做变更并回滚。不过通过 API 访问预设时，始终使用最新版本。
  3. 如果在请求中提供参数，它们优先于预设的值。二者为浅合并，即请求级字段覆盖匹配的预设字段，但请求中不存在的预设字段会被保留。
上一页SCIM 组映射下一页 自定义分类器