--- # 🚀 Zhenxun LLM 服务模块 本模块是一个功能强大、高度可扩展的统一大语言模型（LLM）服务框架。它旨在将各种不同的 LLM 提供商（如 OpenAI、Gemini、智谱AI等）的 API 封装在一个统一、易于使用的接口之后，让开发者可以无缝切换和使用不同的模型，同时支持多模态输入、工具调用、智能重试和缓存等高级功能。 ## 目录 - [🚀 Zhenxun LLM 服务模块](#-zhenxun-llm-服务模块) - [目录](#目录) - [✨ 核心特性](#-核心特性) - [🧠 核心概念](#-核心概念) - [🛠️ 安装与配置](#️-安装与配置) - [服务提供商配置 (`config.yaml`)](#服务提供商配置-configyaml) - [MCP 工具配置 (`mcp_tools.json`)](#mcp-工具配置-mcp_toolsjson) - [📘 使用指南](#-使用指南) - [**等级1: 便捷函数** - 最快速的调用方式](#等级1-便捷函数---最快速的调用方式) - [**等级2: `AI` 会话类** - 管理有状态的对话](#等级2-ai-会话类---管理有状态的对话) - [**等级3: 直接模型控制** - `get_model_instance`](#等级3-直接模型控制---get_model_instance) - [🌟 功能深度剖析](#-功能深度剖析) - [精细化控制模型生成 (`LLMGenerationConfig` 与 `CommonOverrides`)](#精细化控制模型生成-llmgenerationconfig-与-commonoverrides) - [赋予模型能力：工具使用 (Function Calling)](#赋予模型能力工具使用-function-calling) - [1. 注册工具](#1-注册工具) - [函数工具注册](#函数工具注册) - [MCP工具注册](#mcp工具注册) - [2. 调用带工具的模型](#2-调用带工具的模型) - [处理多模态输入](#处理多模态输入) - [🔧 高级主题与扩展](#-高级主题与扩展) - [模型与密钥管理](#模型与密钥管理) - [缓存管理](#缓存管理) - [错误处理 (`LLMException`)](#错误处理-llmexception) - [自定义适配器 (Adapter)](#自定义适配器-adapter) - [📚 API 快速参考](#-api-快速参考) --- ## ✨ 核心特性 - **多提供商支持**: 内置对 OpenAI、Gemini、智谱AI 等多种 API 的适配器，并可通过通用 OpenAI 兼容适配器轻松接入更多服务。 - **统一的 API**: 提供从简单到高级的三层 API，满足不同场景的需求，无论是快速聊天还是复杂的分析任务。 - **强大的工具调用 (Function Calling)**: 支持标准的函数调用和实验性的 MCP (Model Context Protocol) 工具，让 LLM 能够与外部世界交互。 - **多模态能力**: 无缝集成 `UniMessage`，轻松处理文本、图片、音频、视频等混合输入，支持多模态搜索和分析。 - **文本嵌入向量化**: 提供统一的嵌入接口，支持语义搜索、相似度计算和文本聚类等应用。 - **智能重试与 Key 轮询**: 内置健壮的请求重试逻辑，当 API Key 失效或达到速率限制时，能自动轮询使用备用 Key。 - **灵活的配置系统**: 通过配置文件和代码中的 `LLMGenerationConfig`，可以精细控制模型的生成行为（如温度、最大Token等）。 - **高性能缓存机制**: 内置模型实例缓存，减少重复初始化开销，提供缓存管理和监控功能。 - **丰富的配置预设**: 提供 `CommonOverrides` 类，包含创意模式、精确模式、JSON输出等多种常用配置预设。 - **可扩展的适配器架构**: 开发者可以轻松编写自己的适配器来支持新的 LLM 服务。 ## 🧠 核心概念 - **适配器 (Adapter)**: 这是连接我们统一接口和特定 LLM 提供商 API 的“翻译官”。例如，`GeminiAdapter` 知道如何将我们的标准请求格式转换为 Google Gemini API 需要的格式，并解析其响应。 - **模型实例 (`LLMModel`)**: 这是框架中的核心操作对象，代表一个**具体配置好**的模型。例如，一个 `LLMModel` 实例可能代表使用特定 API Key、特定代理的 `Gemini/gemini-1.5-pro`。所有与模型交互的操作都通过这个类的实例进行。 - **生成配置 (`LLMGenerationConfig`)**: 这是一个数据类，用于控制模型在生成内容时的行为，例如 `temperature` (温度)、`max_tokens` (最大输出长度)、`response_format` (响应格式) 等。 - **工具 (Tool)**: 代表一个可以让 LLM 调用的函数。它可以是一个简单的 Python 函数，也可以是一个更复杂的、有状态的 MCP 服务。 - **多模态内容 (`LLMContentPart`)**: 这是处理多模态输入的基础单元，一个 `LLMMessage` 可以包含多个 `LLMContentPart`，如一个文本部分和多个图片部分。 ## 🛠️ 安装与配置 该模块作为 `zhenxun` 项目的一部分被集成，无需额外安装。核心配置主要涉及两个文件。 ### 服务提供商配置 (`config.yaml`) 核心配置位于项目 `/data/config.yaml` 文件中的 `AI` 部分。 ```yaml # /data/configs/config.yaml AI: # (可选) 全局默认模型，格式: "ProviderName/ModelName" default_model_name: Gemini/gemini-2.5-flash # (可选) 全局代理设置 proxy: http://127.0.0.1:7890 # (可选) 全局超时设置 (秒) timeout: 180 # (可选) Gemini 的安全过滤阈值 gemini_safety_threshold: BLOCK_MEDIUM_AND_ABOVE # 配置你的AI服务提供商 PROVIDERS: # 示例1: Gemini - name: Gemini api_key: - "AIzaSy_KEY_1" # 支持多个Key，会自动轮询 - "AIzaSy_KEY_2" api_base: https://generativelanguage.googleapis.com api_type: gemini models: - model_name: gemini-2.5-pro - model_name: gemini-2.5-flash - model_name: gemini-2.0-flash - model_name: embedding-001 is_embedding_model: true # 标记为嵌入模型 max_input_tokens: 2048 # 嵌入模型特有配置 # 示例2: 智谱AI - name: GLM api_key: "YOUR_ZHIPU_API_KEY" api_type: zhipu # 适配器类型 models: - model_name: glm-4-flash - model_name: glm-4-plus temperature: 0.8 # 可以为特定模型设置默认温度 # 示例3: 一个兼容OpenAI的自定义服务 - name: MyOpenAIService api_key: "sk-my-custom-key" api_base: "http://localhost:8080/v1" api_type: general_openai_compat # 使用通用OpenAI兼容适配器 models: - model_name: Llama3-8B-Instruct max_tokens: 2048 # 可以为特定模型设置默认最大Token ``` ### MCP 工具配置 (`mcp_tools.json`) 此文件位于 `/data/llm/mcp_tools.json`，用于配置通过 MCP 协议启动的外部工具服务。如果文件不存在，系统会自动创建一个包含示例的默认文件。 ```json { "mcpServers": { "baidu-map": { "command": "npx", "args": ["-y", "@baidumap/mcp-server-baidu-map"], "env": { "BAIDU_MAP_API_KEY": "" }, "description": "百度地图工具，提供地理编码、路线规划等功能。" }, "sequential-thinking": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"], "description": "顺序思维工具，用于帮助模型进行多步骤推理。" } } } ``` ## 📘 使用指南 我们提供了三层 API，以满足从简单到复杂的各种需求。 ### **等级1: 便捷函数** - 最快速的调用方式 这些函数位于 `zhenxun.services.llm` 包的顶层，为你处理了所有的底层细节。 ```python from zhenxun.services.llm import chat, search, code, pipeline_chat, embed, analyze_multimodal, search_multimodal from zhenxun.services.llm.utils import create_multimodal_message # 1. 纯文本聊天 response_text = await chat("你好，请用苏轼的风格写一首关于月亮的诗。") print(response_text) # 2. 带网络搜索的问答 search_result = await search("马斯克的Neuralink公司最近有什么新进展？") print(search_result['text']) # print(search_result['sources']) # 查看信息来源 # 3. 执行代码 code_result = await code("用Python画一个心形图案。") print(code_result['text']) # 包含代码和解释的回复 # 4. 链式调用 image_msg = create_multimodal_message(images="path/to/cat.jpg") final_poem = await pipeline_chat( message=image_msg, model_chain=["Gemini/gemini-1.5-pro", "GLM/glm-4-flash"], initial_instruction="详细描述这只猫的外观和姿态。", final_instruction="将上述描述凝练成一首可爱的短诗。" ) print(final_poem.text) # 5. 文本嵌入向量生成 texts_to_embed = ["今天天气真好", "我喜欢打篮球", "这部电影很感人"] vectors = await embed(texts_to_embed, model="Gemini/embedding-001") print(f"生成了 {len(vectors)} 个向量，每个向量维度: {len(vectors[0])}") # 6. 多模态分析便捷函数 response = await analyze_multimodal( text="请分析这张图片中的内容", images="path/to/image.jpg", model="Gemini/gemini-1.5-pro" ) print(response) # 7. 多模态搜索便捷函数 search_result = await search_multimodal( text="搜索与这张图片相关的信息", images="path/to/image.jpg", model="Gemini/gemini-1.5-pro" ) print(search_result['text']) ``` ### **等级2: `AI` 会话类** - 管理有状态的对话 当你需要进行有上下文的、连续的对话时，`AI` 类是你的最佳选择。 ```python from zhenxun.services.llm.api import AI, AIConfig # 初始化一个AI会话，可以传入自定义配置 ai_config = AIConfig(model="GLM/glm-4-flash", temperature=0.7) ai_session = AI(config=ai_config) # 更完整的AIConfig配置示例 advanced_config = AIConfig( model="GLM/glm-4-flash", default_embedding_model="Gemini/embedding-001", # 默认嵌入模型 temperature=0.7, max_tokens=2000, enable_cache=True, # 启用模型缓存 enable_code=True, # 启用代码执行功能 enable_search=True, # 启用搜索功能 timeout=180, # 请求超时时间（秒） # Gemini特定配置选项 enable_gemini_json_mode=True, # 启用Gemini JSON模式 enable_gemini_thinking=True, # 启用Gemini 思考模式 enable_gemini_safe_mode=True, # 启用Gemini 安全模式 enable_gemini_multimodal=True, # 启用Gemini 多模态优化 enable_gemini_grounding=True, # 启用Gemini 信息来源关联 ) advanced_session = AI(config=advanced_config) # 进行连续对话 await ai_session.chat("我最喜欢的城市是成都。") response = await ai_session.chat("它有什么好吃的？") # AI会知道“它”指的是成都 print(response) # 在同一个会话中，临时切换模型进行一次调用 response_gemini = await ai_session.chat( "从AI的角度分析一下成都的科技发展潜力。", model="Gemini/gemini-1.5-pro" ) print(response_gemini) # 清空历史，开始新一轮对话 ai_session.clear_history() ``` ### **等级3: 直接模型控制** - `get_model_instance` 这是最底层的 API，为你提供对模型实例的完全控制。推荐使用 `async with` 语句来优雅地管理模型实例的生命周期。 ```python from zhenxun.services.llm import get_model_instance, LLMMessage from zhenxun.services.llm.config import LLMGenerationConfig # 1. 获取模型实例 # get_model_instance 返回一个异步上下文管理器 async with await get_model_instance("Gemini/gemini-1.5-pro") as model: # 2. 准备消息列表 messages = [ LLMMessage.system("你是一个专业的营养师。"), LLMMessage.user("我今天吃了汉堡和可乐，请给我一些健康建议。") ] # 3. (可选) 定义本次调用的生成配置 gen_config = LLMGenerationConfig( temperature=0.2, # 更严谨的回复 max_tokens=300 ) # 4. 生成响应 response = await model.generate_response(messages, config=gen_config) # 5. 处理响应 print(response.text) if response.usage_info: print(f"Token 消耗: {response.usage_info['total_tokens']}") ``` ## 🌟 功能深度剖析 ### 精细化控制模型生成 (`LLMGenerationConfig` 与 `CommonOverrides`) - **`LLMGenerationConfig`**: 一个 Pydantic 模型，用于覆盖模型的默认生成参数。 - **`CommonOverrides`**: 一个包含多种常用配置预设的类，如 `creative()`, `precise()`, `gemini_json()` 等，能极大地简化配置过程。 ```python from zhenxun.services.llm.config import LLMGenerationConfig, CommonOverrides # LLMGenerationConfig 完整参数示例 comprehensive_config = LLMGenerationConfig( temperature=0.7, # 生成温度 (0.0-2.0) max_tokens=1000, # 最大输出token数 top_p=0.9, # 核采样参数 (0.0-1.0) top_k=40, # Top-K采样参数 frequency_penalty=0.0, # 频率惩罚 (-2.0-2.0) presence_penalty=0.0, # 存在惩罚 (-2.0-2.0) repetition_penalty=1.0, # 重复惩罚 (0.0-2.0) stop=["END", "\n\n"], # 停止序列 response_format={"type": "json_object"}, # 响应格式 response_mime_type="application/json", # Gemini专用MIME类型 response_schema={...}, # JSON响应模式 thinking_budget=0.8, # Gemini思考预算 (0.0-1.0) enable_code_execution=True, # 启用代码执行 safety_settings={...}, # 安全设置 response_modalities=["TEXT"], # 响应模态类型 ) # 创建一个配置，要求模型输出JSON格式 json_config = LLMGenerationConfig( temperature=0.1, response_mime_type="application/json" # Gemini特有 ) # 对于OpenAI兼容API，可以这样做 json_config_openai = LLMGenerationConfig( temperature=0.1, response_format={"type": "json_object"} ) # 使用框架提供的预设 - 基础预设 safe_config = CommonOverrides.gemini_safe() creative_config = CommonOverrides.creative() precise_config = CommonOverrides.precise() balanced_config = CommonOverrides.balanced() # 更多实用预设 concise_config = CommonOverrides.concise(max_tokens=50) # 简洁模式 detailed_config = CommonOverrides.detailed(max_tokens=3000) # 详细模式 json_config = CommonOverrides.gemini_json() # JSON输出模式 thinking_config = CommonOverrides.gemini_thinking(budget=0.8) # 思考模式 # Gemini特定高级预设 code_config = CommonOverrides.gemini_code_execution() # 代码执行模式 grounding_config = CommonOverrides.gemini_grounding() # 信息来源关联模式 multimodal_config = CommonOverrides.gemini_multimodal() # 多模态优化模式 # 在调用时传入config对象 # await model.generate_response(messages, config=json_config) ``` ### 赋予模型能力：工具使用 (Function Calling) 工具调用让 LLM 能够与外部函数、API 或服务进行交互。 #### 1. 注册工具 ##### 函数工具注册 使用 `@tool_registry.function_tool` 装饰器注册一个简单的函数工具。 ```python from zhenxun.services.llm import tool_registry @tool_registry.function_tool( name="query_stock_price", description="查询指定股票代码的当前价格。", parameters={ "stock_symbol": {"type": "string", "description": "股票代码, 例如 'AAPL' 或 'GOOG'"} }, required=["stock_symbol"] ) async def query_stock_price(stock_symbol: str) -> dict: """一个查询股票价格的伪函数""" print(f"--- 正在查询 {stock_symbol} 的价格 ---") if stock_symbol == "AAPL": return {"symbol": "AAPL", "price": 175.50, "currency": "USD"} return {"error": "未知的股票代码"} ``` ##### MCP工具注册 对于更复杂的、有状态的工具，可以使用 `@tool_registry.mcp_tool` 装饰器注册MCP工具。 ```python from contextlib import asynccontextmanager from pydantic import BaseModel from zhenxun.services.llm import tool_registry # 定义工具的配置模型 class MyToolConfig(BaseModel): api_key: str endpoint: str timeout: int = 30 # 注册MCP工具 @tool_registry.mcp_tool(name="my-custom-tool", config_model=MyToolConfig) @asynccontextmanager async def my_tool_factory(config: MyToolConfig): """MCP工具工厂函数""" # 初始化工具会话 session = MyToolSession(config) try: await session.initialize() yield session finally: await session.cleanup() ``` #### 2. 调用带工具的模型 在 `analyze` 或 `generate_response` 中使用 `use_tools` 参数。框架会自动处理整个调用流程。 ```python from zhenxun.services.llm.api import analyze from nonebot_plugin_alconna.uniseg import UniMessage response = await analyze( UniMessage("帮我查一下苹果公司的股价"), use_tools=["query_stock_price"] ) print(response.text) # 输出应为 "苹果公司(AAPL)的当前股价为175.5美元。" 或类似内容 ``` ### 处理多模态输入 本模块通过 `UniMessage` 和 `LLMContentPart` 完美支持多模态。 - **`create_multimodal_message`**: 推荐的、用于从代码中便捷地创建多模态消息的函数。 - **`unimsg_to_llm_parts`**: 框架内部使用的核心转换函数，将 `UniMessage` 的各个段（文本、图片等）转换为 `LLMContentPart` 列表。 ```python from zhenxun.services.llm import analyze from zhenxun.services.llm.utils import create_multimodal_message from pathlib import Path # 从本地文件创建消息 message = create_multimodal_message( text="请分析这张图片和这个视频。图片里是什么？视频里发生了什么？", images=[Path("path/to/your/image.jpg")], videos=[Path("path/to/your/video.mp4")] ) response = await analyze(message, model="Gemini/gemini-1.5-pro") print(response.text) ``` ## 🔧 高级主题与扩展 ### 模型与密钥管理 模块提供了一些工具函数来管理你的模型配置。 ```python from zhenxun.services.llm.manager import ( list_available_models, list_embedding_models, set_global_default_model_name, get_global_default_model_name, get_key_usage_stats, reset_key_status ) from zhenxun.services.llm import clear_model_cache, get_cache_stats # 列出所有在config.yaml中配置的可用模型 models = list_available_models() print([m['full_name'] for m in models]) # 列出所有可用的嵌入模型 embedding_models = list_embedding_models() print([m['full_name'] for m in embedding_models]) # 动态设置全局默认模型 success = set_global_default_model_name("GLM/glm-4-plus") # 获取所有Key的使用统计 stats = await get_key_usage_stats() print(stats) # 重置'Gemini'提供商的所有Key await reset_key_status("Gemini") ``` ### 缓存管理 模块提供了模型实例缓存功能，可以提高性能并减少重复初始化的开销。 ```python from zhenxun.services.llm import clear_model_cache, get_cache_stats # 获取缓存统计信息 stats = get_cache_stats() print(f"缓存大小: {stats['cache_size']}/{stats['max_cache_size']}") print(f"缓存TTL: {stats['cache_ttl']}秒") print(f"已缓存模型: {stats['cached_models']}") # 清空模型缓存（在内存不足或需要强制重新初始化时使用） clear_model_cache() print("模型缓存已清空") ``` ### 错误处理 (`LLMException`) 所有模块内的预期错误都会被包装成 `LLMException`，方便统一处理。 ```python from zhenxun.services.llm import chat, LLMException, LLMErrorCode try: await chat("test", model="InvalidProvider/invalid_model") except LLMException as e: print(f"捕获到LLM异常: {e}") print(f"错误码: {e.code}") # 例如 LLMErrorCode.MODEL_NOT_FOUND print(f"用户友好提示: {e.user_friendly_message}") ``` ### 自定义适配器 (Adapter) 如果你想支持一个新的、非 OpenAI 兼容的 LLM 服务，可以通过实现自己的适配器来完成。 1. **创建适配器类**: 继承 `BaseAdapter` 并实现其抽象方法。 ```python # my_adapters/custom_adapter.py from zhenxun.services.llm.adapters import BaseAdapter, RequestData, ResponseData class MyCustomAdapter(BaseAdapter): @property def api_type(self) -> str: return "my_custom_api" @property def supported_api_types(self) -> list[str]: return ["my_custom_api"] # ... 实现 prepare_advanced_request, parse_response 等方法 ``` 2. **注册适配器**: 在你的插件初始化代码中注册你的适配器。 ```python from zhenxun.services.llm.adapters import register_adapter from .my_adapters.custom_adapter import MyCustomAdapter register_adapter(MyCustomAdapter()) ``` 3. **在 `config.yaml` 中使用**: ```yaml AI: PROVIDERS: - name: MyAwesomeLLM api_key: "my-secret-key" api_type: "my_custom_api" # 关键！使用你注册的 api_type # ... ``` ## 📚 API 快速参考 | 类/函数 | 主要用途 | 推荐场景 | | ------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------ | | `llm.chat()` | 进行简单的、无状态的文本对话。 | 快速实现单轮问答。 | | `llm.search()` | 执行带网络搜索的问答。 | 需要最新信息或回答事实性问题时。 | | `llm.code()` | 请求模型执行代码。 | 计算、数据处理、代码生成等。 | | `llm.pipeline_chat()` | 将多个模型串联，处理复杂任务流。 | 需要多模型协作完成的任务，如“图生文再润色”。 | | `llm.analyze()` | 处理复杂的多模态输入 (`UniMessage`) 和工具调用。 | 插件中处理用户命令，需要解析图片、at、回复等复杂消息时。 | | `llm.AI` (类) | 管理一个有状态的、连续的对话会话。 | 需要实现上下文关联的连续对话机器人。 | | `llm.get_model_instance()` | 获取一个底层的、可直接控制的 `LLMModel` 实例。 | 需要对模型进行最精细控制的复杂或自定义场景。 | | `llm.config.LLMGenerationConfig` (类) | 定义模型生成的具体参数，如温度、最大Token等。 | 当需要微调模型输出风格或格式时。 | | `llm.tools.tool_registry` (实例) | 注册和管理可供LLM调用的函数工具。 | 当你想让LLM拥有与外部世界交互的能力时。 | | `llm.embed()` | 生成文本的嵌入向量表示。 | 语义搜索、相似度计算、文本聚类等。 | | `llm.search_multimodal()` | 执行带网络搜索的多模态问答。 | 需要基于图片、视频等多模态内容进行搜索时。 | | `llm.analyze_multimodal()` | 便捷的多模态分析函数。 | 直接分析文本、图片、视频、音频等多模态内容。 | | `llm.AIConfig` (类) | AI会话的配置类，包含模型、温度等参数。 | 配置AI会话的行为和特性。 | | `llm.clear_model_cache()` | 清空模型实例缓存。 | 内存管理或强制重新初始化模型时。 | | `llm.get_cache_stats()` | 获取模型缓存的统计信息。 | 监控缓存使用情况和性能优化。 | | `llm.list_embedding_models()` | 列出所有可用的嵌入模型。 | 选择合适的嵌入模型进行向量化任务。 | | `llm.config.CommonOverrides` (类) | 提供常用的配置预设，如创意模式、精确模式等。 | 快速应用常见的模型配置组合。 | | `llm.utils.create_multimodal_message` | 便捷地从文本、图片、音视频等数据创建 `UniMessage`。 | 在代码中以编程方式构建多模态输入时。 |