更新嵌入说明

Author: Moemu

docs/develop/practice.md

@@ -162,9 +162,11 @@ if isinstance(response, ModelCompletions):
 # 如果是流式调用
 else:
     response_chunks: list[str] = []
+    response_usage = -1
+    response_status = True
     async for chunk in response:
         response_chunks.append(chunk.chunk)
-        response_usage = chunk.usage or chunk.usage
+        response_usage = chunk.usage if chunk.usage > response_usage else response_usage
         response_status = chunk.succeed if not chunk.succeed else response_status
     # 拼接流式响应
     response_text = "".join(response_chunks)
@@ -194,3 +196,38 @@ def process_message(message: str) -> str:
 
     return result
 ```
+
+### 获取文本嵌入信息
+
+```python
+from muicebot.config import get_embedding_model_config
+from muicebot.llm import load_embedding_model
+from async_lru import alru_cache
+
+# 请注意，由于 `embedding_model_config` 对于用户而言是可选的
+# 当配置文件不存在/为空时，会抛出 `FileNotFoundError`
+embedding_model = load_embedding_model(get_embedding_model_config())
+
+@alru_cache(maxsize=1024)
+async def _get_embedding(self, text: str) -> ndarray:
+    """
+    调用 OpenAI API 兼容端口获取字符串的嵌入向量，支持离线缓存
+
+    :param text: 要查询的字符串
+    """
+    logger.debug(f"正在查询文本嵌入向量: {text[:50]}...")
+
+    # 缓存未命中，调用 API
+    start_time = perf_counter()
+    try:
+        response = await embedding_model.embed([text])
+        embedding = np.array(response.embeddings[0])
+
+        end_time = perf_counter()
+        logger.debug(f"已完成查询，用时: {end_time - start_time}s")
+        return embedding
+
+    except Exception as e:
+        logger.error(f"获取嵌入向量失败: {e}")
+        raise
+```

docs/guide/embedding.md

@@ -0,0 +1,64 @@
+# 嵌入模型配置📎
+
+## 嵌入模型提供者信息
+
+类似于模型加载器，在 Muicebot 中，每一个可用于获取字符串的嵌入向量形式的嵌入模型被称为嵌入模型加载器，这些模型加载器存放于代码目录中的 `muicebot.llm.embeddings` 文件夹下，并通常以首字母大写的形式命名以便于 SDK 区分。
+
+每个嵌入模型加载器都继承于模型基类 `EmbeddingModel` 并统一使用 `EmbeddingConfig` 获取配置项，但由于 SDK 实现情况，每个嵌入模型加载器所需要的配置项和实现的功能都不尽相同。
+
+**嵌入模型的配置是可选的，当且仅当你安装了需要使用嵌入模型的插件（比如 muicebot-plugin-memory）时才需要配置**
+
+本页面列举了每一个嵌入模型加载器目前在 Muicebot 中实现的功能并给出了它们所支持的配置项。
+
+### 实现的加载器及其支持的模型
+
+我们目前实现了以下模型加载器:
+
+| 模型加载器                                                                      | 介绍                                                                            | 模型列表                                                                   |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| [Azure](https://github.com/Moemu/MuiceBot/tree/main/Muice/llm/Azure.py)         | 可调用 [GitHub Marketplace ](https://github.com/marketplace/models)中的在线模型 | [Github MarketPlace](https://github.com/marketplace?type=models)           |
+| [Dashscope](https://github.com/Moemu/MuiceBot/tree/main/Muice/llm/Dashscope.py) | 可调用阿里云百炼平台的在线模型                                                  | [官方文档](https://help.aliyun.com/zh/model-studio/getting-started/models) |
+| [Gemini](https://aistudio.google.com/)                                          | 使用 Gemini Python SDK 访问 Google Gemini 服务中的模型                          | [模型列表](https://ai.google.dev/gemini-api/docs/models?hl=zh-cn)          |
+| [Ollama](https://github.com/Moemu/MuiceBot/tree/main/Muice/llm/Ollama.py)       | 使用 Ollama Python SDK 访问 Ollama 接口，需要提前启动 Ollama 服务器                   | [模型列表](https://ollama.com/search)                                      |
+| [Openai](https://github.com/Moemu/MuiceBot/tree/main/Muice/llm/Openai.py)       | 可调用 OpenAI API 格式的接口                             | _any_                                                                      |
+
+对于不同的加载器，可能需要额外的依赖，请根据报错提示安装。
+
+## 编写配置
+
+在 `configs` 文件夹下新建 `embeddings.yml`，用于存储嵌入模型加载器的配置。
+
+**基本格式**
+
+对于不同的模型加载器，所需要的配置项都大体相似。以下示例列出了所有支持的配置项。
+
+```yaml
+default:  # 配置名称。唯一，可任取，不一定和模型加载器名称有关联
+  provider: openai  # 模型加载器名称。对应的是 `muicebot/llm/providers` 下的 `.py` 文件。
+  default: true  # 是否默认
+  model: "text-embedding-v4"  # 嵌入模型名称
+  api_key: sk-xxxxxxxxxxxxxxxxxxx  # 在线服务的 api key
+  api_secret: 0d000721Onanie  # 在线服务的 api secret(对于 Openai 来说可忽略)
+  api_host: "https://dashscope.aliyuncs.com/compatible-mode/v1"  # base_url
+```
+
+## 关于嵌入信息的统一性
+
+一般来说，我们强烈推荐**有且仅有一个长久使用的嵌入模型配置**，因为对于一段文本来说，不同嵌入模型返回的结果都大不相同，如果使用不同的模型会导致最终计算的结果失准或产生异常错误。
+
+不需要保证大语言模型和嵌入模型的模型加载器/模型类别是相同的。目前仅支持查询文本的向量嵌入
+
+## 嵌入的缓存
+
+每一次查询嵌入都会优先从本地收集缓存，目的是节省缓存查询次数和开销。缓存目录为 `get_plugin_data_dir() / embedding`
+
+为了确保在切换缓存模型时，原有的缓存与新的嵌入不会产生冲突，我们同时写入了以下 `json` 内容来确保缓存安全：
+
+```json
+{
+    "provider": "<模型提供者类名>",
+    "api_host": "<self.config.api_host>",
+    "model": "<self.config.model>",
+    "text_hash": "<文本的 sha256 内容>",
+}
+```

docs/guide/model.md

@@ -2,7 +2,7 @@
 
 ## 模型加载器信息
 
-在 Muicebot 中，每一个可用于与 LLM 进行交互的实例被称为模型加载器，这些模型加载器存放于代码目录中的 `muicebot.llm` 文件夹下，并通常以首字母大写的形式命名以便于 SDK 区分。
+在 Muicebot 中，每一个可用于与 LLM 进行交互的实例被称为模型加载器（也叫做模型服务提供者），这些模型加载器存放于代码目录中的 `muicebot.llm` 文件夹下，并通常以首字母大写的形式命名以便于 SDK 区分。
 
 每个模型加载器都继承于模型基类 `BasicModel` 并统一使用 `ModelConfig` 获取配置项，但由于 SDK 实现情况，每个模型加载器所需要的配置项和实现的功能都不尽相同。
 
@@ -22,7 +22,7 @@
 
 对于不同的加载器，可能需要额外的依赖，请根据报错提示安装。
 
-有关各个模型加载器的配置，参见 [模型加载器配置](/model/configuration.md)
+有关各个模型加载器的配置，参见 [模型加载器配置](#模型加载器配置项一览)
 
 ### 加载器功能支持列表
 
@@ -70,7 +70,7 @@
 
 ```yaml
 azure: # 配置名称。唯一，可任取，不一定和模型加载器名称有关联
-  loader: Azure # 模型加载器名称。对应的是 `muicebot/llm` 下的 `.py` 文件。通常模型加载器的首字母都是大写
+  provider: Azure # 模型加载器名称。对应的是 `muicebot/llm` 下的 `.py` 文件。通常模型加载器的首字母都是大写
   model_name: DeepSeek-R1 # 模型名称（可选，默认为 DeepSeek-R1）
   template: Muice # 人设提示词 Jinja2 模板名称（不用带文件后缀）
   api_key: ghp_xxxxxxxxxxxxxxxxx # GitHub Token（若配置了环境变量，此项不填）
@@ -81,13 +81,13 @@ azure: # 配置名称。唯一，可任取，不一定和模型加载器名称
 
 以上给出了 Azure 模型加载器的一个示例配置，您可以在接下来的 [模型加载器配置项一览](#模型加载器配置项一览) 一节中获取这些模型加载器分别支持的配置。
 
-如果你不知道这些配置中哪些是必须的，那么你可以先填写一个 `loader` 配置，模型加载器初始化时会抛出错误并提示您
+如果你不知道这些配置中哪些是必须的，那么你可以先填写一个 `provider` 配置，模型加载器初始化时会抛出错误并提示您
 
 我们支持多个模型配置，并可在聊天中通过指令动态切换，例如：
 
 ```yaml
 dashscope:
-  loader: Dashscope # 使用 dashscope 加载器
+  provider: Dashscope # 使用 dashscope 加载器
   default: true # 默认配置文件
   template: Muice # 人设提示词 Jinja2 模板名称（不用带文件后缀）
   multimodal: true # 是否启用多模态（可选，注意：使用的模型必须是多模态的）
@@ -100,7 +100,7 @@ dashscope:
   repetition_penalty: 1.2
 
 azure:
-  loader: Azure # 使用 azure 加载器
+  provider: Azure # 使用 azure 加载器
   model_name: DeepSeek-R1 # 模型名称（可选，默认为 DeepSeek-R1）
   template: Muice # 人设提示词 Jinja2 模板名称（不用带文件后缀）
   token: ghp_xxxxxxxxxxxxxxxxx # GitHub Token（若配置了环境变量，此项不填）
@@ -121,7 +121,7 @@ azure:
 下面的配置项是每一个模型加载器都共有的，并且发挥着重要的功能：
 
 ```yaml
-loader: Openai # 模型加载器名称，这些模型加载器位于插件目录下的 llm 文件夹中，并初始化同名文件的同名类，如果不存在则报错。注意，每个模型加载器因为兼容问题，开头首字母都是大写的
+provider: openai # 模型加载器名称，这些模型加载器位于插件目录下的 llm/providers 文件夹中，并初始化同名文件的同名类，如果不存在则报错。
 multimodal: true # 多模态支持。设置为 true 将处理多模态事件。如果调用的模型不是多模态模型忽略这些多模态消息
 
 template: Muice # 人设提示词 Jinja2 模板，模板文件需要存放在 `./templates` 文件夹下。Muice为内嵌模板。默认值为空或全局默认值
@@ -139,7 +139,7 @@ template_mode: system # 模板嵌入模式: `system` 为嵌入到系统提示; `
 ### Azure (Github Models)
 
 ```yaml
-loader: Azure # 使用 Azure 加载器（必填）
+provider: Azure # 使用 Azure 加载器（必填）
 model_name: DeepSeek-R1 # 模型名称（必填）
 api_key: <your-github-token-goes-here> # GitHub Token 或 Azure Key（必填）
 template: Muice # 使用的模板名称（可选，无默认值）
@@ -156,7 +156,7 @@ function_call: false # 是否启用工具调用（可选。需要编写 function
 ### Dashscope (阿里百炼大模型平台)
 
 ```yaml
-loader: Dashscope # 使用 Dashscope 加载器（必须）
+provider: Dashscope # 使用 Dashscope 加载器（必须）
 model_name: qwen-max # 模型名称（必须）
 template: Muice # 使用的模板名称（可选，无默认值）
 multimodal: false # 是否启用多模态（可选。注意：使用的模型必须是多模态的）
@@ -174,7 +174,7 @@ content_security: false # 内容安全（可选。需要开通内容审核服务
 ### Gemini (Google)
 
 ```yaml
-loader: Gemini # 使用 Dashscope 加载器（必须）
+provider: Gemini # 使用 Dashscope 加载器（必须）
 model_name: gemini-2.0-flash # 模型名称（必须）
 template: Muice # 使用的模板名称（可选，无默认值）
 multimodal: false # 是否启用多模态（可选。注意：使用的模型必须是多模态的）
@@ -195,7 +195,7 @@ content_security: false # 内容安全（可选。默认为中级及以上）
 ### Ollama
 
 ```yaml
-loader: Ollama # 使用 Ollama 加载器（必填）
+provider: Ollama # 使用 Ollama 加载器（必填）
 model_name: deepseek-r1 # ollama 模型名称（必填）
 template: Muice # 使用的模板名称（可选，无默认值）
 api_host: http://localhost:11434 # ollama 客户端端口（可选）
@@ -213,7 +213,7 @@ function_call: false # 是否启用工具调用（可选。需要编写 function
 ### Openai (支持 DeepSeek 官方 API 调用)
 
 ```yaml
-loader: Openai # 使用 openai 加载器（必填）
+provider: Openai # 使用 openai 加载器（必填）
 model_name: text-davinci-003 # 模型名称（必填）
 template: Muice # 使用的模板名称（可选，无默认值）
 api_key: xxxxxx # API 密钥（必须）