# https://github.com/LazyAGI/LazyLLM 项目说明书

生成时间：2026-06-18 13:38:33 UTC

## 目录

- [Overview & System Architecture](#page-1)
- [RAG: Document Loading, Stores, and Retrieval](#page-2)
- [Multi-Agent Systems: ReAct, ReWOO, Plan-and-Solve, Function Calling, MCP & Memory](#page-3)
- [Model Deployment, Online Suppliers & Fine-tuning](#page-4)

<a id='page-1'></a>

## Overview & System Architecture

### 相关页面

相关主题：[RAG: Document Loading, Stores, and Retrieval](#page-2), [Multi-Agent Systems: ReAct, ReWOO, Plan-and-Solve, Function Calling, MCP & Memory](#page-3), [Model Deployment, Online Suppliers & Fine-tuning](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/LazyAGI/LazyLLM/blob/main/README.md)
- [lazyllm/prompt_templates/prompts_actor/README.md](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/prompt_templates/prompts_actor/README.md)
- [lazyllm/tools/agent/AGENTS.md](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/AGENTS.md)
- [lazyllm/tools/agent/reactAgent.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/reactAgent.py)
- [lazyllm/tools/agent/toolsManager.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/toolsManager.py)
- [lazyllm/tools/agent/skill_manager.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/skill_manager.py)
- [lazyllm/tools/agent/skill_hub.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/skill_hub.py)
- [lazyllm/tools/agent/file_tool.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/file_tool.py)
- [lazyllm/cli/main.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/cli/main.py)
- [lazyllm/cli/review.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/cli/review.py)
- [lazyllm/cli/README.md](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/cli/README.md)
- [lazyllm/components/utils/downloader/model_mapping.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/components/utils/downloader/model_mapping.py)
</details>

# Overview & System Architecture

## 1. 系统定位与设计目标

LazyLLM 是一个面向多智能体（Multi-Agent）应用的开发与部署框架，核心定位是"用搭积木的方式构建 AI 应用"。项目的设计目标涵盖四个维度：便捷的 AI 应用组装流程、一键部署复杂应用、跨平台兼容（裸机、Slurm 集群、公有云等）以及对不同模型与框架（在线服务、本地推理、微调框架、向量库、关系库）提供统一的开发者体验 [README.md](README.md)。

在 v0.7.1 版本中，Agent 模块、文档解析服务与启动系统经历了重大重构，并新增了 Elasticsearch、OceanBase 等存储后端以及 SiliconFlow、MiniMax 等在线模型提供方，同时引入了综合缓存系统以提升性能 [README.md](README.md)。这些演进都围绕"在不破坏向后兼容性的前提下扩展生态"这一目标展开。

## 2. 核心架构

LazyLLM 的架构以 `Module` 为最小可调度单元，以 `Flow` 为数据流编排机制，以 `ActionModule` 提供训练/部署的副作用通道。下图展示了一个典型的应用从配置到运行的纵向分层：

```mermaid
graph TD
    A[用户入口: WebModule / CLI / Engine] --> B[Module 抽象层]
    B --> C[Flow 编排: Pipeline / Parallel / IFS / Loop]
    C --> D[子 Module: TrainableModule / OnlineChatModule / UrlModule / ServerModule]
    D --> E[ActionModule: 训练或部署副作用]
    E --> F[资源层: 本地推理框架 / 在线 API / 向量库 / 关系库]
    B -.工具注册.-> G[toolsManager / ModuleTool]
    B -.技能加载.-> H[skill_manager / skill_hub]
```

- **Module 抽象层**：所有可调用对象都被包装为 `Module`，提供统一的 `start()` / `wait()` / `update()` 接口。
- **Flow 编排层**：`Pipeline`、`Parallel`、`Diverter`、`Warp`、`IFS`、`Loop` 等预定义 Flow 负责在 Module 之间搬运数据 [README.md](README.md)。
- **ActionModule 副作用通道**：当某个子 Module 需要训练或部署时，`ActionModule` 接管其生命周期管理 [README.md](README.md)。
- **资源层**：屏蔽底层推理框架（vllm/lightllm）、在线 API、向量库的差异，对上层提供统一调用语义 [README.md](README.md)。

## 3. 关键模块体系

下表汇总了 README 中列出的核心 Module 类型及其能力差异（是否支持训练/部署/包装/服务化）：

| Module 类型 | 主要职责 | 训练 | 部署 | 包装 | 服务化 |
|---|---|---|---|---|---|
| TrainableModule | 可训练模型基类，所有支持的模型均为其子类 | ✅ | ✅ | ✅ | ✅ |
| OnlineChatModule | 在线聊天模型的微调与推理 | ✅ | ✅ | ✅ | ✅ |
| OnlineEmbeddingModule | 在线 Embedding 推理 | ❌ | ✅ | ✅ | ✅ |
| ServerModule | 将函数/Flow/Module 包装为 API | ❌ | ✅ | ✅ | ✅ |
| WebModule | 启动多轮对话 Web 界面 | ❌ | ✅ | ❌ | ✅ |
| UrlModule | 包装任意 URL 访问外部服务 | ❌ | ❌ | ✅ | ✅ |
| ActionModule | 训练/部署 TrainableModule 子模块 | ✅ | ✅ | — | — |

资料来源：[README.md](README.md)

## 4. Agent 与工具/技能生态

Agent 子系统是 LazyLLM 0.7.x 重点重构的对象。`ReactAgent` 基于 `FunctionCall` + `Loop` 组合实现 ReAct 范式：LLM 输出 `tool_calls` 时进入下一轮迭代，返回字符串时触发 Loop 终止条件 [reactAgent.py](lazyllm/tools/agent/reactAgent.py)。历史消息通过 `locals['_lazyllm_agent']['workspace']` 隔离存储，避免并发请求间的状态泄漏 [AGENTS.md](lazyllm/tools/agent/AGENTS.md)。

工具与技能侧的双层结构：

- **Tools（工具）**：通过 `ModuleTool` 继承或 `@register('tool')` 装饰器注册，`toolsManager` 解析 docstring + 类型注解生成 Pydantic schema [toolsManager.py](lazyllm/tools/agent/toolsManager.py)。例如 `write_file` 内置工具支持 `overwrite|append` 模式与目录创建 [file_tool.py](lazyllm/tools/agent/file_tool.py)。
- **Skills（技能）**：通过 `skill_hub` 从 GitHub `owner/repo[/path]` 安装，调用 Git Trees API 递归列出文件并下载到本地 [skill_hub.py](lazyllm/tools/agent/skill_hub.py)。`skill_manager` 强制要求在使用 `read_reference` / `run_script` 前必须先 `get_skill` 获取 SKILL.md 内容 [skill_manager.py](lazyllm/tools/agent/skill_manager.py)。

社区反馈 #1035 反映 `OnlineModule(type='image_editing')` 当前接口不支持图文交错内容，这属于在线多模态模块层面的待完善项。

## 5. 部署与 CLI 接口

CLI 入口在 [main.py](lazyllm/cli/main.py) 中路由到 `install` / `deploy` / `run` / `skills` / `review` / `review-local` 六个子命令。其中：

- `lazyllm deploy <model>` 支持按模型启动推理服务，README 中以 vLLM 为例说明 `--tp`（张量并行）等参数；可通过 `LAZYLLM_VLLM_SKIP_CHECK_KW=True` 绕过参数白名单校验 [cli/README.md](lazyllm/cli/README.md)。
- `lazyllm review` 与 `lazyllm review-local` 提供 PR 级与本地 git 仓库的 AI 代码审查，支持 `--base main` 与 `--no-uncommitted` 等参数 [review.py](lazyllm/cli/review.py)。

模型侧的 prompt 模板与对话协议（如 `chatglm3`、`glm-4`、`internlm2`、`deepseek-r1` 的 `tool_start_token` / `stop_words`）由 [model_mapping.py](lazyllm/components/utils/downloader/model_mapping.py) 统一维护。

## 6. Prompt 模板与数据来源

内置的 prompt 模板主要来自两个开源数据集：[awesome-chatgpt-prompts-zh](https://github.com/PlexPt/awesome-chatgpt-prompts-zh)（MIT 协议，124 条中文 prompt）和 [prompts.chat](https://github.com/f/prompts.chat)（CC0-1.0 协议，1192 条英文 prompt）。这些数据仅做了字段归一化与格式微调，未对原始内容做整体改写 [prompts_actor/README.md](lazyllm/prompt_templates/prompts_actor/README.md)。

社区反馈 #655 指出部分教程文档的标题未被正确编译，这是文档构建流水线层面的常见问题，与核心架构无关，但在阅读 `Learn` / `CookBook` 系列时需要留意。

## See Also

- [Agent 体系与 ReAct 循环](Agent-System.html)
- [Flow 编排参考](Flow-Reference.html)
- [Module 体系总览](Module-Overview.html)
- [CLI 部署与代码审查](CLI-Tools.html)

---

<a id='page-2'></a>

## RAG: Document Loading, Stores, and Retrieval

### 相关页面

相关主题：[Overview & System Architecture](#page-1), [Model Deployment, Online Suppliers & Fine-tuning](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [lazyllm/tools/rag/document.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/rag/document.py)
- [lazyllm/tools/rag/doc_node.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/rag/doc_node.py)
- [lazyllm/tools/rag/retriever.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/rag/retriever.py)
- [lazyllm/tools/rag/rerank.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/rag/rerank.py)
- [lazyllm/tools/rag/similarity.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/rag/similarity.py)
- [lazyllm/tools/rag/readers/pdfReader.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/rag/readers/pdfReader.py)
- [lazyllm/tools/rag/readers/__init__.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/rag/readers/__init__.py)
- [lazyllm/tools/rag/splitter.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/rag/splitter.py)
- [README.md](https://github.com/LazyAGI/LazyLLM/blob/main/README.md)
</details>

# RAG: Document Loading, Stores, and Retrieval

## 概述

LazyLLM 的 RAG（Retrieval-Augmented Generation）模块为多模态、多知识库场景下的检索增强生成提供了端到端的基础设施。该模块围绕 **Document** 核心抽象组织数据流，覆盖从原始数据接入、向量化存储到多路召回与重排序的完整链路。RAG 模块的关键能力包括：横向扩展的 RAG 节点、宏问答（macro Q&A）跨库能力、至少一种开源知识图谱框架集成，以及对 20+ 文档类型的切分策略支持。资料来源：[README.md]()

## 整体架构

RAG 模块的核心由三层组成：文档加载层、节点与存储层、检索与重排序层。三者通过 `Document`、`Retriever`、`Reranker` 三个高阶类解耦，便于用户按需替换组件。

```mermaid
flowchart LR
    A[原始数据<br>PDF/Markdown/CSV] --> B[Readers<br>文档加载]
    B --> C[Document<br>节点组管理]
    C --> D[Splitter<br>切分策略]
    D --> E[Embedding<br>向量化]
    E --> F[Vector Store / Map Store]
    F --> G[Retriever<br>多路召回]
    G --> H[Reranker<br>重排序]
    H --> I[LLM 生成回答]
```

## 文档加载（Document Loading）

LazyLLM 的文档加载通过 `lazyllm.tools.rag.readers` 包实现，支持 PDF、Markdown、CSV、Docx 等多种格式。每个 Reader 负责将原始文件解析为统一的 `DocNode` 列表，便于后续统一处理。例如 `pdfReader.py` 提供基于 PDF 解析的节点生成能力。资料来源：[lazyllm/tools/rag/readers/pdfReader.py]()

`Document` 是用户接入数据的入口对象，典型用法如下：

```python
from lazyllm import Document, SentenceSplitter, Retriever, Reranker
import lazyllm

documents = Document(
    dataset_path="your data path",
    embed=lazyllm.OnlineEmbeddingModule(),
    manager=False,
)
```

`manager=False` 表示由用户显式管理节点组；设为 `True` 时，框架会自动管理并暴露后台管理界面。资料来源：[README.md]()

## 文档存储与节点组（Stores & Node Groups）

存储层负责把解析后的 `DocNode` 写入不同的后端。LazyLLM 通过 `create_node_group` 方法支持多种切分与存储策略并行存在：

```python
documents.create_node_group(
    name="sentences",
    transform=SentenceSplitter,
    chunk_size=1024,
    chunk_overlap=100,
)
```

每个节点组可以独立配置切分器、嵌入模型和后端存储。系统支持 `bm25_chinese` 等基于词频的稀疏检索后端以及基于 Embedding 的稠密向量库。V0.7 版本已支持 Elasticsearch 与 OceanBase 作为新的存储供应商，进一步扩展生态。资料来源：[README.md]()

## 检索与重排序（Retrieval & Re-ranking）

检索阶段由 `Retriever` 类承担，支持按节点组、相似度算法与 TopK 等参数灵活配置：

```python
prl.retriever1 = Retriever(
    documents, group_name="sentences",
    similarity="cosine", topk=3,
)
prl.retriever2 = Retriever(
    documents, "CoarseChunk", "bm25_chinese", 0.003, topk=3,
)
```

多个 `Retriever` 可以通过 `parallel().sum` 进行结果合并，召回阶段常用“向量 + BM25”双路召回以兼顾语义匹配与关键词匹配。资料来源：[README.md]()

重排序阶段由 `Reranker` 实现，常用 `ModuleReranker` 加载 `bge-reranker-large` 等模型：

```python
ppl.reranker = Reranker(
    "ModuleReranker",
    model="bge-reranker-large",
    topk=1,
) | bind(query=ppl.input)
```

最终将排序后的节点内容拼装为 prompt 上下文，交给 LLM 生成回答：

```python
ppl.formatter = (
    lambda nodes, query: dict(
        context_str="".join([node.get_content() for node in nodes]),
        query=query,
    )
) | bind(query=ppl.input)
ppl.llm = lazyllm.OnlineChatModule(stream=False).prompt(
    lazyllm.ChatPrompter(prompt, extra_keys=["context_str"])
)
```

资料来源：[README.md]()

## 关键参数对照

| 组件 | 关键参数 | 说明 |
|------|----------|------|
| `Document` | `dataset_path`, `embed`, `manager` | 数据路径、嵌入模型、是否托管节点组 |
| `create_node_group` | `name`, `transform`, `chunk_size`, `chunk_overlap` | 节点组名称、切分器、块大小与重叠 |
| `Retriever` | `group_name`, `similarity`, `topk` | 检索节点组、相似度算法、返回数量 |
| `Reranker` | `model`, `topk` | 重排模型与最终返回数量 |

## 常见使用模式与失败模式

- **多路召回合并**：通过 `parallel().sum` 聚合多个 Retriever 的结果，再交给 Reranker 统一排序，是 V0.6 起推荐的混合检索范式。资料来源：[README.md]()
- **多知识库横向扩展**：V0.6 起，RAG 模块已支持宏问答跨库能力，便于企业级多源知识整合。资料来源：[README.md]()
- **结构化数据处理**：V0.7 起支持 CSV 等相对结构化文本的处理。资料来源：[README.md]()
- **社区问题提示**：在 Issue #655 中，有用户反馈教程文档的部分标题未正确编译，提示在使用示例代码时需结合当前版本的官方文档与示例库进行对照验证。资料来源：[Issue #655](https://github.com/LazyAGI/LazyLLM/issues/655)

## See Also

- 训练与部署：[TrainableModule 与 WebModule 使用指南]()
- Agent 与 FunctionCall 机制：[lazyllm/tools/agent/AGENTS.md](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/AGENTS.md)
- 项目主文档：[README.md](https://github.com/LazyAGI/LazyLLM/blob/main/README.md)

---

<a id='page-3'></a>

## Multi-Agent Systems: ReAct, ReWOO, Plan-and-Solve, Function Calling, MCP & Memory

### 相关页面

相关主题：[Overview & System Architecture](#page-1), [RAG: Document Loading, Stores, and Retrieval](#page-2), [Model Deployment, Online Suppliers & Fine-tuning](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [lazyllm/tools/agent/__init__.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/__init__.py)
- [lazyllm/tools/agent/AGENTS.md](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/AGENTS.md)
- [lazyllm/tools/agent/reactAgent.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/reactAgent.py)
- [lazyllm/tools/agent/rewooAgent.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/rewooAgent.py)
- [lazyllm/tools/agent/planAndSolveAgent.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/planAndSolveAgent.py)
- [lazyllm/tools/agent/functionCall.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/functionCall.py)
- [lazyllm/tools/agent/toolsManager.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/toolsManager.py)
- [lazyllm/tools/agent/skill_manager.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/skill_manager.py)
- [lazyllm/tools/agent/skill_hub.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/skill_hub.py)
- [lazyllm/tools/agent/base.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/base.py)
</details>

# Multi-Agent Systems: ReAct, ReWOO, Plan-and-Solve, Function Calling & Memory

## 概述

LazyLLM 的多智能体系统位于 `lazyllm/tools/agent/` 目录，提供四类开箱即用的 Agent（`ReactAgent`、`PlanAndSolveAgent`、`ReWOOAgent`、`FunctionCallAgent`）以及统一的工具注册与记忆管理机制。所有 Agent 共享 `LazyLLMAgentBase` 基类与 `FunctionCall` 这一核心执行单元，使得不同推理范式在数据流、错误处理与工具调用上保持一致 资料来源：[lazyllm/tools/agent/__init__.py:1-30]()。在 v0.7.1 版本中，Agent 模块经历了重大重构，代码可维护性与清晰度显著提升 资料来源：[README.md](https://github.com/LazyAGI/LazyLLM/blob/main/README.md)。

## Agent 类型与适用场景

| Agent | 工作方式 | 适用场景 |
|-------|---------|----------|
| `ReactAgent` | 推理→行动→观察循环，直至给出最终答案 | 需要多步推理与工具调用的一般任务 |
| `PlanAndSolveAgent` | Planner 拆解子任务，Solver 按计划执行 | 需先规划再执行的复杂任务 |
| `ReWOOAgent` | Planner 生成蓝图，Worker 并行收集证据，Solver 综合 | 适合并行信息收集类任务 |
| `FunctionCallAgent` | 直接选择并调用工具（已弃用，推荐使用 `ReactAgent`） | 简单单次工具调用 |

资料来源：[lazyllm/tools/agent/AGENTS.md:23-32]()。

## FunctionCall 核心执行流

所有 Agent 都通过 `FunctionCall` 完成"LLM 推理 + 工具调用"的单轮执行，其内部流程如下：

```mermaid
flowchart TD
    A[input] --> B[_build_history<br/>构造历史消息]
    B --> C[LLM 推理<br/>输出 content 或 tool_calls]
    C --> D{是否存在 tool_calls?}
    D -- 是 --> E[ToolManager 执行工具]
    E --> F[返回 dict<br/>继续循环]
    D -- 否 --> G[返回 str<br/>终止循环]
```

`ReactAgent` 将 `FunctionCall` 包装在 `Loop` 内，并以 `stop_condition=lambda x: isinstance(x, str)` 控制终止：返回 `dict`（含 `tool_calls`）则继续，返回 `str`（最终答案）则停止 资料来源：[lazyllm/tools/agent/AGENTS.md:62-72]()。`ReWOOAgent` 则在 `pipeline` 中依次执行 `planner_pre_action` → `planner` → `worker_evidences` → `solver_pre_action` → `solver`，并用 `ifs` 决定是否走工具分支 资料来源：[lazyllm/tools/agent/rewooAgent.py:1-25]()。

## 工具注册与函数调用 Schema

工具通过 `register` 装饰器或 `ModuleTool` 子类注册，由 `ToolManager` 统一管理：负责将工具注册到临时组、生成 LLM 所需的 `tools_description`（OpenAI function calling 格式），并执行具体工具调用 资料来源：[lazyllm/tools/agent/toolsManager.py]()。

工具函数的 docstring 格式必须严格遵循如下规范，否则 LLM 无法正确调用：

```python
def my_tool(param1: str, param2: int = 5) -> str:
    '''简短描述（用于 description 字段）

    Args:
        param1 (str): 参数说明。
        param2 (int): 参数说明，默认 5。

    Returns:
        str: 返回值说明。
    '''
```

- 首行：工具的简短描述（映射为 `description`）
- `Args:` 块：每个参数的类型与说明（映射为 `parameters.properties`）
- 完整类型注解（映射为 `parameters.properties.type`）

资料来源：[lazyllm/tools/agent/AGENTS.md:100-120]()。

## 记忆管理与并发安全

`FunctionCall` 将对话历史写入 `locals['_lazyllm_agent']['workspace']`（而非实例变量），从而保证在并发请求下不同用户的上下文互不泄露：

```python
workspace = locals['_lazyllm_agent']['workspace']
workspace.setdefault('history', [])
workspace['history'].append({'role': 'user', 'content': input})
```

资料来源：[lazyllm/tools/agent/AGENTS.md:74-81]()。当 `ReactAgent` 达到 `max_retries` 上限且仍未成功时，会尝试从历史中调用 `_force_summarize_from_history` 强制总结作为兜底 资料来源：[lazyllm/tools/agent/reactAgent.py]()。

## Skills 与持久化扩展

`SkillManager` 提供可持久化的技能管理能力，配合 `install_skill` 可从 `agentskillhub` 或 GitHub 安装预制技能：

```python
from lazyllm.tools.agent import install_skill
install_skill('agentskillhub:username/skill-slug')
install_skill('github:owner/repo/path/to/skill')
```

资料来源：[lazyllm/tools/agent/skill_hub.py:1-15]()、`[lazyllm/tools/agent/AGENTS.md:140-155]()`。在 `ReactAgent` 中可通过 `skills=True` 或 `skills=['web_search', 'code_exec']` 等方式加载已安装技能，扩展 Agent 能力边界。

## 禁止模式与最佳实践

源码 `AGENTS.md` 明确列出以下禁止项 资料来源：[lazyllm/tools/agent/AGENTS.md:165-172]()：

- **禁止**把对话历史存储在 Agent 实例变量中（应使用 `locals['_lazyllm_agent']['workspace']`）
- **禁止**省略工具函数的 docstring 或类型注解（schema 生成依赖它们）
- **禁止**在工具函数中直接访问 `globals`（工具应是无状态纯函数）
- **禁止**在 `FunctionCall` 之外实现工具调用逻辑（应复用 `FunctionCall`）
- **禁止**重写 `__call__`（继承 `ModuleBase` 的 `__call__`，仅实现 `forward`）

社区方面，issue #1035 反馈了 `OnlineModule(type='image_editing')` 缺少图文交错输入的支持，反映出多模态工具调用仍是当前社区关注的改进方向 资料来源：[Issue #1035](https://github.com/LazyAGI/LazyLLM/issues/1035)。

## See Also

- [Module System & Flows](module-system.md)
- [RAG & Document Processing](rag-and-documents.md)
- [Model Deployment & OnlineModule](model-deployment.md)
- [CLI & Skills Management](cli-and-skills.md)

---

<a id='page-4'></a>

## Model Deployment, Online Suppliers & Fine-tuning

### 相关页面

相关主题：[Overview & System Architecture](#page-1), [RAG: Document Loading, Stores, and Retrieval](#page-2), [Multi-Agent Systems: ReAct, ReWOO, Plan-and-Solve, Function Calling, MCP & Memory](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/LazyAGI/LazyLLM/blob/main/README.md)
- [lazyllm/cli/README.md](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/cli/README.md)
- [lazyllm/cli/main.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/cli/main.py)
- [lazyllm/components/utils/downloader/model_mapping.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/components/utils/downloader/model_mapping.py)
- [lazyllm/tools/agent/skill_hub.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/skill_hub.py)
- [lazyllm/tools/agent/AGENTS.md](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/AGENTS.md)
- [lazyllm/tools/agent/file_tool.py](https://github.com/LazyAGI/LazyLLM/blob/main/lazyllm/tools/agent/file_tool.py)
</details>

# Model Deployment, Online Suppliers & Fine-tuning

## 1. 概览与设计目标

LazyLLM 在模型层面提供"统一体验、多端可选"的设计：用户既可以一键拉起本地开源模型（通过 `TrainableModule`），也可以直接调用各家云端 API（通过 `OnlineChatModule`、`OnlineEmbeddingModule`、`OnlineModule`），并在此之上对模型进行微调与部署。这种统一封装使得同一个上层 Flow 或 Agent 逻辑可以在不修改业务代码的情况下切换底层模型来源。`README.md` 中明确指出：项目为不同服务商的在线模型以及本地部署的模型提供"统一的用户体验"，并支持模型微调以"持续提升应用性能"。

整套体系包含三条主线：

| 主线 | 入口 | 主要能力 |
|------|------|----------|
| 本地训练/推理 | `TrainableModule` | 自动选择微调框架、内置微调、推理服务启动 |
| 在线 API 调用 | `OnlineChatModule` / `OnlineEmbeddingModule` / `OnlineModule` | 多供应商 Chat、Embedding、文生图、图像编辑 |
| 命令行一键部署 | `lazyllm deploy` | 单进程启动服务，参数受控 |

资料来源：[README.md]()

## 2. 部署方式与命令入口

### 2.1 CLI 部署

`lazyllm deploy` 是面向运维场景的轻量入口，其命令分发位于 [lazyllm/cli/main.py]()：`sys.argv[1]` 取值为 `install | deploy | run | skills | review | review-local`，分发到对应子命令。`deploy` 子命令的典型用法在 [lazyllm/cli/README.md]() 中给出，支持 `--port` 指定端口、`--tp` 指定张量并行度等参数。

```bash
# 启动基础服务
lazyllm deploy llama2 --port=8000
# 使用张量并行
lazyllm deploy llama2 --tp=2
```

对于 vLLM 后端，[lazyllm/cli/README.md]() 中描述了"参数限制策略"：默认仅放行经过校验的安全参数，以避免误用；当用户显式设置 `LAZYLLM_VLLM_SKIP_CHECK_KW=True` 后才会解除限制，并提示用户自行保证参数正确性。这种"白名单 + 可绕过"的设计兼顾了稳定性与灵活性。

### 2.2 模块化部署

在 Python API 层面，`README.md` 总结了若干核心 Module：

- `ServerModule`：将任意函数、Flow 或 Module 包装为 API 服务；
- `WebModule`：拉起多轮对话 Web 服务，例如 `lazyllm.WebModule(chat).start().wait()`；
- `TrainableModule`：承载可训练/可微调的本地模型；
- `UrlModule`：将任意 URL 包装为 Module 以访问外部服务。

这些 Module 通过统一的 `start()` / `wait()` 接口暴露生命周期，因此 `lazyllm deploy` 与 Python 中的 `WebModule(...).start().wait()` 在用户体验上保持一致。

资料来源：[README.md]()、[lazyllm/cli/README.md]()、[lazyllm/cli/main.py]()

## 3. 在线模型供应商与模型注册

### 3.1 Module 类型矩阵

`README.md` 给出了在线模块的能力矩阵（节选）：

| Module | 训练/微调 | 推理 | 部署 | 说明 |
|--------|-----------|------|------|------|
| `OnlineChatModule` | ✅ | ✅ | ✅ | 集成在线模型的微调与推理服务 |
| `OnlineEmbeddingModule` | ❌ | ✅ | ✅ | 集成在线 Embedding 推理服务 |
| `OnlineModule`（扩展类型） | — | ✅ | — | 涵盖文生图、图像编辑等扩展能力（社区 Issue #1035 即针对 `type='image_editing'` 提出"图文交错"内容支持请求） |

社区上下文显示，v0.7.1 起新增了 SiliconFlow、MiniMax 等在线供应商，并扩展了新的存储后端（Elasticsearch、OceanBase）。这意味着 `OnlineChatModule` / `OnlineEmbeddingModule` 在供应商层是插件式扩展的。

### 3.2 模型注册与 Prompt 适配

在线与本地模型共享一份模型注册表，集中在 [lazyllm/components/utils/downloader/model_mapping.py]()。该文件包含三块内容：

1. **Prompt 模板（`prompt_keys`）**：为 chatglm3、glm-4、internlm、internlm2、deepseek、llama、qwen 等模型族声明 `sos / soh / soa / eos / stop_words` 等会话控制符。例如 `glm-4` 注册了 `tool_start_token='✿FUNCTION✿: '`、`tool_args_token='✿ARGS✿: '`、`tool_end_token='\n'`，从而兼容其工具调用语法。
2. **模型来源（`model_provider`）**：将模型名映射到 HuggingFace 与 ModelScope 的 `owner/repo`，例如 `internlm -> (internlm, Shanghai_AI_Laboratory)`。
3. **多模态模型**：注册 `stable-diffusion-3.5-large`、`flux.1-dev`、`cogview4-6b`、`wan2_1-t2v-1_3b-diffusers` 等文生图/视频模型，以及 `pp-ocrv4_server` / `pp-ocrv5_server` 等 OCR 模型（`download_by_other=True` 表示由其它渠道拉取）。

由于这份映射同时驱动本地下载与在线供应商的 Prompt 拼装，新增模型时只需在该文件中补全条目即可。

资料来源：[lazyllm/components/utils/downloader/model_mapping.py]()、[README.md]()

## 4. 模型微调与 ActionModule

`README.md` 中列出了两类与微调相关的 Module：

- `TrainableModule`：所有受支持模型都视作 `TrainableModule`，可通过 `ActionModule` 对其子模块进行训练/微调；并能根据微调场景"自动选择最佳微调框架与模型切分策略"。
- `OnlineChatModule`：同样具备微调能力，因为它"集成了在线模型的微调与推理服务"。

这一设计让"先用在线 API 验证 POC，再切换到本地开源模型做微调"成为平滑的迁移路径，不需要重写上层 Flow 或 Agent 代码。

## 5. 部署与 Agent/Skill 的协同

部署能力与 Agent、Skill 体系是相互补全的。在 [lazyllm/tools/agent/AGENTS.md]() 中，`ReactAgent` 包装 `FunctionCall` 形成一个 `Loop`，循环条件是返回值从 `dict`（带 `tool_calls`）变为 `str`（最终答案）。`Loop` 的 `count=self._max_retries` 决定最大工具调用次数，超出后会注入 `_FORCE_SUMMARIZE_MSG` 强制收尾——这条规则与 [lazyllm/tools/agent/reactAgent.py]() 中的提示模板相对应。

部署好的模型既可以作为 Agent 内的 `llm`，也可以通过 `ToolManager` 暴露为工具（见 [lazyllm/tools/agent/file_tool.py]() 中 `read_file` / `write_file` 等通过 `@register('tool', ...)` 注册的工具）。更进一步，用户可以通过 [lazyllm/tools/agent/skill_hub.py]() 的 `install_skill` 从 GitHub 拉取远端 Skill 目录（按 SKILL.md 加载工作流），从而把外部能力以"技能"形式挂到本地部署好的模型上。

```mermaid
flowchart LR
    A[TrainableModule 本地模型] -->|ActionModule 微调| B[ServerModule API]
    C[OnlineChatModule / OnlineModule] -->|HTTP| B
    B --> D[ReactAgent + FunctionCall]
    E[Skill Hub GitHub 拉取] -->|SKILL.md| D
    F[ToolManager 注册工具] -->|tool_calls| D
    D -->|start / wait| G[WebModule 对话界面]
```

## 6. 常见问题与失败模式

- **CLI 部署参数被拒**：vLLM 默认启用参数白名单，需设置 `LAZYLLM_VLLM_SKIP_CHECK_KW=True` 才能使用未登记参数，详见 [lazyllm/cli/README.md]()。
- **在线图像编辑接口能力受限**：社区 Issue #1035 反馈 `OnlineModule(type='image_editing')` 暂不支持"图文交错"内容，这是当前已知的扩展点。
- **模型未注册**：调用一个未在 `model_mapping.py` 中登记的模型名会导致下载或 Prompt 模板缺失；新增模型必须先在 [lazyllm/components/utils/downloader/model_mapping.py]() 中补齐 `prompt_keys` 与 `source`。
- **Agent 工具调用死循环**：`ReactAgent` 达到 `max_retries` 时会强制注入停止消息；若用户未设置合理的 `max_retries`，长任务会过早截断。

## See Also

- [Agent System Overview](agents.md)
- [Flow 与 Pipeline 设计](flows.md)
- [RAG 与文档解析](rag.md)
- [CLI 工具总览](cli.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：LazyAGI/LazyLLM

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

## 1. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/LazyAGI/LazyLLM | README/documentation is current enough for a first validation pass.

## 2. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/LazyAGI/LazyLLM | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/LazyAGI/LazyLLM | no_demo; severity=medium

## 4. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/LazyAGI/LazyLLM | no_demo; severity=medium

## 5. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/LazyAGI/LazyLLM | issue_or_pr_quality=unknown

## 6. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/LazyAGI/LazyLLM | release_recency=unknown

<!-- canonical_name: LazyAGI/LazyLLM; human_manual_source: deepwiki_human_wiki -->