aiproxy/core/relay/plugin/patch/README.zh.md

Patch 插件

Patch 插件提供了强大的 JSON 请求修改功能，使用 sonic 库实现高性能 JSON 处理。它允许您基于模型类型、字段值或自定义条件自动修改 API 请求。

功能特性

• 高性能: 使用字节跳动的 sonic 库进行快速 JSON 解析和操作
• 预定义补丁: 内置常见场景的补丁（DeepSeek max_tokens 限制、GPT-5 兼容性等）
• 用户自定义补丁: 灵活的配置系统支持自定义补丁
• 条件逻辑: 基于模型类型、字段值或复杂条件应用补丁
• 多种操作: 支持设置、删除、添加和限制 JSON 字段的操作
• 嵌套字段支持: 使用点语法修改嵌套 JSON 结构
• 占位符支持: 使用 {{field_name}} 语法进行动态值替换

预定义补丁

插件包含几个内置补丁：

1. DeepSeek Max Tokens 限制

• 目的: 将 DeepSeek 模型的 max_tokens 限制为 16000
• 条件: 模型名称包含 "deepseek"
• 操作: 将 max_tokens 字段限制为最大 16000

2. GPT-5 Max Tokens 转换

• 目的: 为 GPT-5 模型将 max_tokens 转换为 max_completion_tokens
• 条件: 模型名称包含 "gpt-5" 且存在 max_tokens 字段
• 操作:
  • 将 max_completion_tokens 设置为 max_tokens 的值
  • 删除 max_tokens 字段

3. O1 模型 Max Tokens 转换

• 目的: 为 o1 模型将 max_tokens 转换为 max_completion_tokens
• 条件: 模型匹配 o1、o1-preview 或 o1-mini
• 操作: 与 GPT-5 转换相同

4. Claude Max Tokens 限制

• 目的: 将 Claude 模型的 max_tokens 限制为 8192
• 条件: 模型名称包含 "claude"
• 操作: 将 max_tokens 字段限制为最大 8192

5. 移除不支持的 Stream Options

• 目的: 为不支持的较旧 GPT 模型移除 stream_options
• 条件: 模型匹配较旧的 GPT 模式且存在 stream_options
• 操作: 删除 stream_options 字段

配置

基本用法

import (
    "github.com/labring/aiproxy/core/relay/plugin/patch"
)

// 创建插件 - 配置从模型配置中加载
plugin := patch.New()

配置

patch插件从数据库中模型的插件配置中加载配置。配置应存储在模型配置的plugin字段中，键名为"patch"。

模型配置插件配置示例：

{
  "patch": {
    "enable": true,
    "user_patches": [
      {
        "name": "custom_temperature_limit",
        "description": "为特定模型限制温度值",
        "conditions": [
          {
            "key": "model", 
            "operator": "contains",
            "value": "gpt-4"
          }
        ],
        "operations": [
          {
            "op": "limit",
            "key": "temperature", 
            "value": 1.0
          }
        ]
      }
    ]
  }
}

预定义补丁

插件包含内置的预定义补丁，这些补丁始终启用：

• DeepSeek max_tokens限制: 自动将DeepSeek模型的max_tokens限制为16000
• GPT-5兼容性: 为GPT-5模型将max_tokens转换为max_completion_tokens
• O1模型兼容性: 为o1、o1-preview和o1-mini模型进行相同转换
• Claude max_tokens限制: 将Claude模型的max_tokens限制为8192
• Stream选项清理: 为较旧的GPT模型移除不支持的stream_options

这些预定义补丁自动运行且无法禁用。

条件操作符

• equals: 精确字符串匹配
• not_equals: 不等于字符串
• contains: 字符串包含子字符串
• not_contains: 字符串不包含子字符串
• regex: 正则表达式匹配
• exists: 字段存在（非空）
• not_exists: 字段不存在（空）

操作类型

• set: 将字段设置为特定值
• delete: 从 JSON 中删除字段
• add: 仅当字段不存在时添加字段
• limit: 将数值字段限制为最大值

特殊键

• model: 引用 meta 中的实际模型名称
• original_model: 引用 meta 中的原始模型名称
• 任何其他键: 引用 JSON 字段（支持点语法）

占位符语法

使用 {{field_name}} 引用 JSON 数据中的值：

{
    Op:    patch.OpSet,
    Key:   "max_completion_tokens",
    Value: "{{max_tokens}}", // 将被替换为实际的 max_tokens 值
}

嵌套字段访问

使用点语法访问嵌套字段：

{
    Key: "parameters.max_tokens",  // 访问 parameters.max_tokens
    // ...
}

与插件系统集成

import (
    "github.com/labring/aiproxy/core/relay/plugin"
    "github.com/labring/aiproxy/core/relay/plugin/patch"
)

// 创建 patch 插件
patchPlugin := patch.New()

// 用插件包装适配器
adaptor = plugin.WrapperAdaptor(adaptor, patchPlugin)

性能考虑

• 使用 sonic 库进行高性能 JSON 处理
• 高效的条件评估，支持早期终止
• 对未更改的请求最小化内存分配
• 延迟评估补丁（仅在条件匹配时应用）

错误处理

• 优雅降级：如果补丁失败，保留原始请求
• 详细的补丁失败日志记录
• 具有适当错误检查的类型安全操作

示例

示例 1: 模型特定的 Max Tokens

{
    "name": "anthropic_max_tokens",
    "description": "为 Anthropic 模型设置适当的 max_tokens",
    "conditions": [
        {
            "key": "model",
            "operator": "contains",
            "value": "claude"
        }
    ],
    "operations": [
        {
            "op": "limit",
            "key": "max_tokens",
            "value": 4096
        }
    ]
}

示例 2: 添加默认参数

{
    "name": "add_default_temperature",
    "description": "如果未指定则添加默认温度值",
    "conditions": [
        {
            "key": "temperature",
            "operator": "not_exists",
            "value": ""
        }
    ],
    "operations": [
        {
            "op": "add",
            "key": "temperature",
            "value": 0.7
        }
    ]
}

示例 3: 复杂条件逻辑

{
    "name": "streaming_optimization",
    "description": "为特定模型优化流式处理",
    "conditions": [
        {
            "key": "stream",
            "operator": "equals",
            "value": "true"
        },
        {
            "key": "model",
            "operator": "regex",
            "value": "^gpt-4"
        }
    ],
    "operations": [
        {
            "op": "set",
            "key": "stream_options.include_usage",
            "value": true
        }
    ]
}

使用场景

1. 模型兼容性: 自动转换不同 API 之间的参数格式
2. 令牌限制: 基于模型能力限制 max_tokens
3. 参数清理: 移除特定模型不支持的参数
4. 默认值设置: 为缺失的参数添加合理默认值
5. API 版本适配: 处理不同 API 版本之间的差异

这个插件设计简洁而强大，可以轻松扩展以支持新的补丁规则和操作类型。