相关源文件

以下文件被用作生成此 wiki 页面的上下文： - [nanovllm/models/qwen3.py](https://github.com/geeeekexplorer/nano-vllm/blob/main/nanovllm/models/qwen3.py) - [nanovllm/engine/llm_engine.py](https://github.com/geeeekexplorer/nano-vllm/blob/main/nanovllm/engine/llm_engine.py) - [nanovllm/llm.py](https://github.com/geeeekexplorer/nano-vllm/blob/main/nanovllm/llm.py) - [nanovllm/__init__.py](https://github.com/geeeekexplorer/nano-vllm/blob/main/nanovllm/__init__.py) - [nanovllm/config.py](https://github.com/geeeekexplorer/nano-vllm/blob/main/nanovllm/config.py)

# LLM 类 `nano-vllm` 中的 `LLM` 类是用户与大型语言模型交互和运行推理的主要高级接口。它旨在抽象化模型加载、张量并行、请求调度和批量执行的复杂性，为从提示生成文本提供了一个简单直观的 API。该类是 `LLMEngine` 类的直接子类，继承了其所有核心功能。`LLM` 类本身作为一个便捷的包装器，暴露了典型用户工作流所需的基本方法，例如添加请求和生成补全。底层的引擎负责管理模型生命周期、高效处理请求以及在启用张量并行时与多个进程协调等复杂细节。 ## 类层次结构和初始化 `LLM` 类是一个清晰的继承结构的一部分，旨在将面向用户的逻辑与核心引擎实现分离开来。 ```mermaid classDiagram class LLM { <> } class LLMEngine { <> -model_runner: ModelRunner -scheduler: Scheduler -tokenizer: AutoTokenizer -config: Config +__init__#40;model, **kwargs#41; +add_request#40;prompt, sampling_params#41; +step#40;#41; +generate#40;prompts, sampling_params#41; +is_finished#40;#41; } class Config { <> +model: str +max_num_batched_tokens: int +tensor_parallel_size: int +... } LLM --|> LLMEngine : inherits from LLMEngine --> Config : uses ``` 如图所示，`LLM` 继承自 `LLMEngine` ([`nanovllm/llm.py`](https://github.com/geeeekexplorer/nano-vllm/blob/main/nanovllm/llm.py))。`LLMEngine` 的 `__init__` 方法负责设置整个推理环境。此过程包括： 1. **配置**: 它使用提供的模型路径和其他关键字参数实例化一个 `Config` 对象 ([`nanovllm/config.py`](https://github.com/geeeekexplorer/nano-vllm/blob/main/nanovllm/config.py))。此配置包含引擎所需的所有必要参数，例如 `max_num_seqs`、`gpu_memory_utilization` 和 `tensor_parallel_size`。 2. **张量并行**: 如果 `config.tensor_parallel_size` 大于 1，引擎将使用 `multiprocessing` ([`nanovllm/engine/llm_engine.py`](https://github.com/geeeekexplorer/nano-vllm/blob/main/nanovllm/engine/llm_engine.py)) 生成多个工作进程。每个进程运行一个 `ModelRunner` 来处理模型的分片。 3. **组件初始化**: 它初始化主 `ModelRunner` (用于 rank 0)、一个用于管理传入请求的 `Scheduler`，以及一个来自 Hugging Face `transformers` 库的 `AutoTokenizer`。以下流程图说明了 `LLMEngine` 构造函数中的初始化序列。 ```mermaid graph TB A[用户实例化LLM#35;40#59;模型, ...#35;41#59;] --> B{LLM.__init__调用LLMEngine.__init__}; B --> C[创建配置对象]; C --> D{检查tensor_parallel_size #35;62#59; 1?}; D -- Yes --> E[为ModelRunner生成工作进程]; E --> F[初始化主ModelRunner #35;40#59;rank 0#35;41#59;]; D -- No --> F; F --> G[初始化调度器]; G --> H[初始化AutoTokenizer]; H --> I[引擎就绪]; ``` ## 核心功能和工作流 `LLM` 类的主要用例是根据一个或多个提示生成文本。这是通过 `generate` 方法实现的，该方法从头到尾编排一个完整的推理工作流。 ### `generate` 方法 `generate` 方法是一个高级抽象，它处理一组提示的整个生命周期。它接受一个提示列表（可以是字符串或 token ID）以及每个提示对应的 `SamplingParams`。 `generate` 方法内部的工作流如下： 1. **添加请求**: 它遍历提供的提示并为每个提示调用 `add_request`。`add_request` 方法对提示进行分词（如果它是字符串）并创建一个 `Sequence` 对象，然后将其添加到 `Scheduler` 的队列中。 2. **推理循环**: 它进入一个 `while` 循环，只要调度器中存在未完成的序列，该循环就会继续。在每次迭代中，它调用 `step` 方法。 3. **步骤执行**: `step` 方法是核心执行单元。它向 `Scheduler` 请求一批要运行的序列，将这批序列转发给 `ModelRunner` 进行推理，然后处理返回的 token ID，更新每个序列的状态。 4. **收集结果**: 一旦一个序列完成（例如，它生成了一个 EOS token），其最终的 token ID 就会被收集起来。 5. **解码并返回**: 循环结束后，所有收集到的 token ID 使用分词器解码回字符串，并返回生成的文本的最终列表。此过程在下方的序列图中进行了可视化。 ```mermaid sequenceDiagram participant User participant LLM as LLM.generate() participant Scheduler participant ModelRunner participant Tokenizer User->>LLM: generate#40;prompts, params#41; loop for each prompt LLM->>Tokenizer: encode#40;prompt#41; Tokenizer-->>LLM: token_ids LLM->>Scheduler: add#40;Sequence#40;token_ids, params#41;#41; end loop while not finished LLM->>Scheduler: schedule#40;#41; Scheduler-->>LLM: batch_of_sequences LLM->>ModelRunner: run#40;batch#41; ModelRunner-->>LLM: output_token_ids LLM->>Scheduler: postprocess#40;batch, output_token_ids#41; end LLM->>Tokenizer: decode#40;final_token_ids#41; Tokenizer-->>LLM: generated_text LLM-->>User: #91;generated_text, ...#93; ``` ### 关键方法 | 方法 | 描述 | 参数 | 返回值 | | :--- | :--- | :--- | :--- | | `__init__(model, **kwargs)` | 初始化 LLM 引擎，加载模型、分词器并设置并行进程。 | `model` (str): 模型目录的路径。
`**kwargs`: 配置覆盖项 (例如, `tensor_parallel_size`)。 | `LLM` 实例 | | `add_request(prompt, params)` | 将单个生成请求添加到调度器的队列中。 | `prompt` (str 或 list[int]): 输入提示。
`params` (SamplingParams): 采样参数。 | None | | `step()` | 执行一步推理：调度一个批次，运行它，并更新序列状态。 | None | `outputs` (list): 已完成的序列。
`num_tokens` (int): 已处理的 token 数量。 | | `generate(prompts, params)` | 为提示列表生成补全的高级方法。 | `prompts` (list): 输入提示列表。
`params` (SamplingParams 或 list): 采样参数。 | `list[dict]`: 一个字典列表，每个字典包含生成的 `text` 和 `token_ids`。 | | `is_finished()` | 检查所有已调度的请求是否已完成。 | None | `bool`: 如果完成则为 `True`，否则为 `False`。 | ## 使用示例 `LLM` 类旨在易于使用。它直接从 `nanovllm` 包中导出，以便于访问 ([`nanovllm/__init__.py`](https://github.com/geeeekexplorer/nano-vllm/blob/main/nanovllm/__init__.py))。 ```python from nanovllm import LLM, SamplingParams # 1. Initialize the LLM engine # This will load the model, tokenizer, and start worker processes if needed. llm = LLM( model="/path/to/your/qwen3/model", tensor_parallel_size=2, # Use 2 GPUs max_num_seqs=256 ) # 2. Define the sampling parameters sampling_params = SamplingParams( temperature=0.8, top_p=0.95, max_tokens=150 ) # 3. Define the prompts prompts = [ "Hello, my name is", "The capital of France is", "In a world where", ] # 4. Generate the completions # The `generate` method handles the entire process. outputs = llm.generate(prompts, sampling_params) # 5. Print the results for i, output in enumerate(outputs): print(f"Prompt {i+1}: {prompts[i]}") print(f"Generated: {output['text']}\n") ``` ## 结论 `LLM` 类为使用 `nano-vllm` 运行大型语言模型推理提供了一个强大而简单的接口。通过继承 `LLMEngine`，它封装了一个用于并行执行、内存管理和请求调度的复杂系统。用户可以利用 `generate` 方法获得简化的体验，或者与 `add_request` 和 `step` 等更低级别的方法交互，以对推理过程进行更细粒度的控制。这种设计使 `nano-vllm` 既适用于简单的用例，也适用于更复杂的、由应用程序驱动的场景。