✨ 提供更多配置项 (#9)

KomoriDev · web-flow · commit e8b7ddebffc3 · 2025-02-01T17:17:24.000+08:00
diff --git a/README.md b/README.md
@@ -94,13 +94,52 @@ plugins = ["nonebot_plugin_deepseek"]
 > `enable_models` 为 [`CustomModel`](https://github.com/KomoriDev/nonebot-plugin-deepseek/blob/ee9f0b0f0568eedb3eb87423e6c1bf271787ab76/nonebot_plugin_deepseek/config.py#L34) 结构的字典，若无接入本地模型的需要则无需修改  
 > 若要接入本地模型，请参见：👉 [文档](./tutorial.md)  
 
-|                      配置项                       | 必填 |                              默认值                              |
-|           :---------------------------:           | :--: |                   :---------------------------:                  |
-|                 deepseek__api_key                 |  是  |                                无                                |
-|              deepseek__enable_models              |  否  |  [{ "name": "deepseek-chat" }, { "name": "deepseek-reasoner" }]  |
-|                  deepseek__prompt                 |  否  |                                无                                |
-|                deepseek__md_to_pic                |  否  |                               False                              |
-|           deepseek__enable_send_thinking          |  否  |                               False                              |
+|           配置项             |必填|                            默认值                            |                  说明                  |
+|:---------------------------: |:--:|                 :---------------------------:                |             :-----------:             |
+|      deepseek__api_key       | 是 |                              无                              |                API Key                |
+|   deepseek__enable_models    | 否 |[{ "name": "deepseek-chat" }, { "name": "deepseek-reasoner" }]|启用的模型 [配置说明](#enable_models-配置说明)|
+|       deepseek__prompt       | 否 |                              无                              |                模型预设                |
+|     deepseek__md_to_pic      | 否 |                             False                            |        是否启用 Markdown 转图片        |
+|deepseek__enable_send_thinking| 否 |                             False                            |             是否发送思维链             |
+
+### `enable_models` 配置说明
+
+`enable_models` 为 [`CustomModel`](https://github.com/KomoriDev/nonebot-plugin-deepseek/blob/ee9f0b0f0568eedb3eb87423e6c1bf271787ab76/nonebot_plugin_deepseek/config.py#L34) 结构的字典，用于控制不同模型的配置，包含的字段有
+
+> [!TIP]
+> 以下字段均在 [DeepSeek API 文档](https://api-docs.deepseek.com/zh-cn/) 有更详细的介绍  
+> `deepseek-reasoner` 模型不支持 `logprobs` 和 `top_logprobs` 参数
+
+- `name`: 模型名称（必填）
+- `base_url`: 接口地址（默认为：<https://api.deepseek.com>）（自建模型必填）
+- `max_tokens`: 模型生成补全的最大 token 数
+  - `deepseek-chat`: 介于 1 到 8192 间的整数，默认使用 4096
+  - `deepseek-reasoner`: 默认为 4K，最大为 8K
+- `frequency_penalty`: 用于阻止模型在生成的文本中过于频繁地重复相同的单词或短语
+- `presence_penalty`: 用于鼓励模型在生成的文本中包含各种标记
+- `stop`: 遇到这些词时停止生成token
+- `temperature`: 采样温度，不建议和 `top_p` 一起修改
+- `top_p`: 采样温度的替代方案。不建议和 `temperature` 一起修改
+- `logprobs`: 是否返回所输出 token 的对数概率
+- `top_logprobs`: 指定在每个 token 位置返回最有可能的 tokens
+
+配置示例:
+
+```bash
+deepseek__enable_models='
+[
+  {
+    "name": "deepseek-chat",
+    "max_tokens": 2048,
+    "top_p": 0.5
+  },
+  {
+    "name": "deepseek-reasoner",
+    "max_tokens": 8000
+  }
+]
+'
+```
 
 ## 🎉 使用
 
diff --git a/nonebot_plugin_deepseek/_types.py b/nonebot_plugin_deepseek/_types.py
@@ -0,0 +1,38 @@
+"""
+@author: openai
+@website: https://github.com/openai/openai-python/blob/main/src/openai/_types.py
+"""
+
+from typing_extensions import override
+from typing import Union, Literal, TypeVar
+
+_T = TypeVar("_T")
+
+
+class NotGiven:
+    """
+    A sentinel singleton class used to distinguish omitted keyword arguments
+    from those passed in with the value None (which may have different behavior).
+
+    For example:
+
+    ```py
+    def get(timeout: Union[int, NotGiven, None] = NotGiven()) -> Response: ...
+
+
+    get(timeout=1)  # 1s timeout
+    get(timeout=None)  # No timeout
+    get()  # Default timeout behavior, which may not be statically known at the method definition.
+    ```
+    """
+
+    def __bool__(self) -> Literal[False]:
+        return False
+
+    @override
+    def __repr__(self) -> str:
+        return "NOT_GIVEN"
+
+
+NotGivenOr = Union[_T, NotGiven]
+NOT_GIVEN = NotGiven()
diff --git a/nonebot_plugin_deepseek/apis/request.py b/nonebot_plugin_deepseek/apis/request.py
@@ -17,16 +17,18 @@ class API:
     @classmethod
     async def chat(cls, message: list[dict[str, str]], model: str = "deepseek-chat") -> ChatCompletions:
         """普通对话"""
+        model_config = config.get_model_config(model)
         json = {
             "messages": [{"content": config.prompt, "role": "user"}] + message if config.prompt else message,
             "model": model,
+            **model_config.to_dict(),
         }
-        logger.debug(f"使用模型 {model}")
+        logger.debug(f"使用模型 {model}，配置：{json}")
         # if model == "deepseek-chat":
         #     json.update({"tools": registry.to_json()})
         async with httpx.AsyncClient() as client:
             response = await client.post(
-                f"{config.get_model_url(model)}/chat/completions",
+                f"{model_config.base_url}/chat/completions",
                 headers={**cls._headers, "Content-Type": "application/json"},
                 json=json,
                 timeout=50,
diff --git a/nonebot_plugin_deepseek/compat.py b/nonebot_plugin_deepseek/compat.py
@@ -0,0 +1,20 @@
+from typing import Literal, overload
+
+from nonebot.compat import PYDANTIC_V2
+
+__all__ = ("model_validator",)
+
+
+if PYDANTIC_V2:
+    from pydantic import model_validator as model_validator
+else:
+    from pydantic import root_validator
+
+    @overload
+    def model_validator(*, mode: Literal["before"]): ...
+
+    @overload
+    def model_validator(*, mode: Literal["after"]): ...
+
+    def model_validator(*, mode: Literal["before", "after"]):
+        return root_validator(pre=mode == "before", allow_reuse=True)  # type: ignore
diff --git a/nonebot_plugin_deepseek/config.py b/nonebot_plugin_deepseek/config.py
@@ -1,9 +1,14 @@
 import json
 from pathlib import Path
+from typing import Any, Union, Optional
 
-from pydantic import Field, BaseModel
+from nonebot.compat import PYDANTIC_V2
 import nonebot_plugin_localstore as store
 from nonebot import logger, get_plugin_config
+from pydantic import Field, BaseModel, ConfigDict
+
+from .compat import model_validator
+from ._types import NOT_GIVEN, NotGivenOr
 
 
 class ModelConfig:
@@ -39,6 +44,86 @@ class CustomModel(BaseModel):
     """Model Name"""
     base_url: str = "https://api.deepseek.com"
     """Custom base URL for this model (optional)"""
+    max_tokens: int = Field(default=4090, gt=1, lt=8192)
+    """
+    限制一次请求中模型生成 completion 的最大 token 数
+    - `deepseek-chat`: Integer between 1 and 8192. Default is 4090.
+    - `deepseek-reasoner`: Default is 4K, maximum is 8K.
+    """
+    frequency_penalty: Union[int, float] = Field(default=0, ge=-2, le=2)
+    """
+    Discourage the model from repeating the same words or phrases too frequently within the generated text
+    """
+    presence_penalty: Union[int, float] = Field(default=0, ge=-2, le=2)
+    """Encourage the model to include a diverse range of tokens in the generated text"""
+    stop: Optional[Union[str, list[str]]] = Field(default=None)
+    """
+    Stop generating tokens when encounter these words.
+    Note that the list contains a maximum of 16 string.
+    """
+    temperature: Union[int, float] = Field(default=1, ge=0, le=2)
+    """Sampling temperature. It is not recommended to used it with top_p"""
+    top_p: Union[int, float] = Field(default=1, ge=0, le=1)
+    """Alternatives to sampling temperature. It is not recommended to used it with temperature"""
+    logprobs: NotGivenOr[Union[bool, None]] = Field(default=NOT_GIVEN)
+    """Whether to return the log probability of the output token."""
+    top_logprobs: NotGivenOr[int] = Field(default=NOT_GIVEN, le=20)
+    """Specifies that the most likely token be returned at each token position."""
+
+    if PYDANTIC_V2:
+        model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
+    else:
+
+        class Config:
+            extra = "allow"
+            arbitrary_types_allowed = True
+
+    @model_validator(mode="before")
+    @classmethod
+    def check_max_token(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            name = data.get("name")
+
+            if "max_tokens" not in data:
+                if name == "deepseek-reasoner":
+                    data["max_tokens"] = 4000
+                else:
+                    data["max_tokens"] = 4090
+
+            stop = data.get("stop")
+            if isinstance(stop, list) and len(stop) >= 16:
+                raise ValueError("字段 `stop` 最多允许设置 16 个字符")
+
+            if name == "deepseek-chat":
+                temperature = data.get("temperature")
+                top_p = data.get("top_p")
+                if temperature and top_p:
+                    logger.warning("不建议同时修改 `temperature` 和 `top_p` 字段")
+
+                top_logprobs = data.get("top_logprobs")
+                logprobs = data.get("logprobs")
+                if top_logprobs and logprobs is False:
+                    raise ValueError("指定 `top_logprobs` 参数时，`logprobs` 必须为 True")
+
+            elif name == "deepseek-reasoner":
+                max_tokens = data.get("max_tokens")
+                if max_tokens and max_tokens > 8000:
+                    logger.warning(f"模型 {name} `max_tokens` 字段最大为 8000")
+
+                unsupported_params = ["temperature", "top_p", "presence_penalty", "frequency_penalty"]
+                params_present = [param for param in unsupported_params if param in data]
+                if params_present:
+                    logger.warning(f"模型 {name} 不支持设置 {', '.join(params_present)}")
+
+                logprobs = data.get("logprobs")
+                top_logprobs = data.get("top_logprobs")
+                if logprobs or top_logprobs:
+                    raise ValueError(f"模型 {name} 不支持设置 logprobs、top_logprobs")
+
+        return data
+
+    def to_dict(self):
+        return self.model_dump(exclude_unset=True, exclude_none=True, exclude={"name", "base_url"})
 
 
 class ScopedConfig(BaseModel):
@@ -66,6 +151,13 @@ def get_model_url(self, model_name: str) -> str:
                 return model.base_url
         raise ValueError(f"Model {model_name} not enabled")
 
+    def get_model_config(self, model_name: str) -> CustomModel:
+        """Get model config"""
+        for model in self.enable_models:
+            if model.name == model_name:
+                return model
+        raise ValueError(f"Model {model_name} not enabled")
+
 
 class Config(BaseModel):
     deepseek: ScopedConfig = Field(default_factory=ScopedConfig)
diff --git a/tests/test_custom_model.py b/tests/test_custom_model.py
@@ -0,0 +1,108 @@
+import pytest
+from pydantic import ValidationError
+
+
+def test_custom_model():
+    from nonebot_plugin_deepseek.config import CustomModel
+
+    # 测试基础字段验证和默认值
+    def test_default_values():
+        model = CustomModel(name="deepseek-chat")
+        assert model.max_tokens == 4090
+        assert model.base_url == "https://api.deepseek.com"
+        assert model.temperature == 1
+
+    def test_reasoner_default_max_tokens():
+        model = CustomModel(name="deepseek-reasoner")
+        assert model.max_tokens == 4000
+
+    def test_invalid_max_tokens_range():
+        with pytest.raises(ValidationError):
+            CustomModel(name="test", max_tokens=0)  # 必须 >1
+        with pytest.raises(ValidationError):
+            CustomModel(name="test", max_tokens=8192)  # 必须 <8192
+
+    def test_field_ranges():
+        with pytest.raises(ValidationError):
+            CustomModel(name="test", frequency_penalty=3)  # 允许范围 [-2, 2]
+        with pytest.raises(ValidationError):
+            CustomModel(name="test", top_p=2)  # 允许范围 [0, 1]
+
+    # 测试 stop 字段验证
+    def test_valid_stop_values():
+        # 字符串类型
+        model = CustomModel(name="test", stop="stop_word")
+        assert model.stop == "stop_word"
+
+        # 列表类型（<=16个元素）
+        model = CustomModel(name="test", stop=["stop1", "stop2"])
+        assert model.stop == ["stop1", "stop2"]
+
+    def test_stop_list_too_long():
+        with pytest.raises(ValueError, match="最多允许设置 16 个字符"):
+            CustomModel(name="test", stop=[f"word{i}" for i in range(17)])
+
+    # 测试模型特定逻辑
+    def test_deepseek_chat_temperature_warning(caplog):
+        CustomModel(name="deepseek-chat", temperature=0.5, top_p=0.5)
+        assert "不建议同时修改" in caplog.text
+
+    def test_deepseek_reasoner_constraints():
+        # 不支持 logprobs
+        with pytest.raises(ValueError, match="不支持设置 logprobs"):
+            CustomModel(name="deepseek-reasoner", logprobs=True)
+
+        # 设置无效字段时抛出警告
+        with pytest.warns(UserWarning) as record:
+            CustomModel(name="deepseek-reasoner", temperature=0.5, presence_penalty=1)
+        assert any("不支持设置" in str(warn.message) for warn in record.list)
+
+    def test_top_logprobs_requires_logprobs():
+        # 同时启用 logprobs 和 top_logprobs
+        CustomModel(name="deepseek-chat", logprobs=True, top_logprobs=5)
+
+        # 仅设置 top_logprobs 不设置 logprobs
+        with pytest.raises(ValueError, match="logprobs 必须为 True"):
+            CustomModel(name="deepseek-chat", top_logprobs=5)
+
+        # 显式关闭 logprobs 但设置 top_logprobs
+        with pytest.raises(ValueError, match="logprobs 必须为 True"):
+            CustomModel(name="deepseek-chat", logprobs=False, top_logprobs=5)
+
+    def test_logprobs_combinations(caplog):
+        # 测试合法组合
+        model = CustomModel(name="deepseek-chat", logprobs=True)
+        assert model.logprobs is True
+        assert model.top_logprobs is None
+
+        # 测试带 top_logprobs 的合法组合
+        model = CustomModel(name="deepseek-chat", logprobs=True, top_logprobs=10)
+        assert model.top_logprobs == 10
+
+        # 测试非法组合的异常消息
+        with pytest.raises(ValueError, match="logprobs 必须为 True") as excinfo:
+            CustomModel(name="deepseek-chat", top_logprobs=5)
+        assert "logprobs 必须为 True" in str(excinfo.value)
+
+        def test_reasoner_max_tokens_warning(caplog):
+            CustomModel(name="deepseek-reasoner", max_tokens=8001)
+            assert "最大为 8000" in caplog.text
+
+    # 测试额外字段和配置
+    def test_extra_fields_allowed():
+        model = CustomModel(name="test", extra_field="value")  # type: ignore
+        assert hasattr(model, "extra_field")
+
+    # 测试验证器边界条件
+    def test_temperature_top_p_combinations():
+        # 合法组合
+        CustomModel(name="test", temperature=0)  # 允许最小值
+        CustomModel(name="test", top_p=0)  # 允许最小值
+        CustomModel(name="test", temperature=2, top_p=1)  # 允许最大值
+
+    def test_presence_penalty_boundary():
+        # 边界值测试
+        CustomModel(name="test", presence_penalty=-2)  # 最小值
+        CustomModel(name="test", presence_penalty=2)  # 最大值
+        with pytest.raises(ValidationError):
+            CustomModel(name="test", presence_penalty=-3)
