# LLM.generate()  —  vllm/entrypoints/llm.py:339
def generate(self, prompts, sampling_params, ...):
    ...
    return self._run_engine(use_tqdm=True)

# LLM._run_engine()  —  vllm/entrypoints/offline_utils.py（精简）
def _run_engine(self):
    while self.llm_engine.has_unfinished_requests():
        step_outputs = self.llm_engine.step()   # 每步产出一批新 token
        for output in step_outputs:
            if output.finished:
                outputs.append(output)
    return sorted(outputs, key=lambda x: int(x.request_id))

# LLMEngine.step()  —  vllm/v1/engine/llm_engine.py
def step(self):
    engine_core_outputs = self.engine_core.step()   # 调度 + GPU 执行 + 采样
    return self.output_processor.process_outputs(engine_core_outputs)

# EngineCore.step()  —  vllm/v1/engine/core.py
def step(self):
    scheduler_output = self.scheduler.schedule()                           # 决定这步算哪些 token
    self.executor.execute_model(scheduler_output, non_block=True)          # GPU forward（非阻塞）
    grammar_output = self.scheduler.get_grammar_bitmask(scheduler_output)  # CPU 并行推进语法状态机
    model_output = self.executor.sample_tokens(grammar_output)             # 等 GPU + 采样
    self.scheduler.update_from_output(scheduler_output, model_output)      # 更新状态、检查停止
    return engine_core_outputs

# LLM.generate() → LLM._run_engine() → LLMEngine.step()
#   → LLMEngine.engine_core.step() → [step() 之前] LLMEngine.input_processor.process_inputs()
# InputProcessor.process_inputs()  —  vllm/v1/engine/input_processor.py
def process_inputs(self, request_id, inputs, params):
    prompt_token_ids = self.tokenizer.encode(inputs.prompt)  # str → list[int]
    # 超过 max_model_len 时截断或报错
    _validate_token_ids(prompt_token_ids, self.model_config)
    return EngineCoreRequest(
        request_id=request_id,
        prompt_token_ids=prompt_token_ids,
        sampling_params=params,
        arrival_time=time.monotonic(),
    )

# 默认（字典形式）——字段名随数据一起传
{"request_id": "r1", "prompt_token_ids": [1, 2, 3], "sampling_params": {...}, ...}

# array_like=True（数组形式）——只传值，按位置对应字段
["r1", [1, 2, 3], {...}, ...]

# LLM.generate() → LLM._run_engine() → LLMEngine.add_request()
#   → EngineCoreClient.add_request() → EngineCore.add_request() → Scheduler.add_request()
# Scheduler.add_request()  —  vllm/v1/core/sched/scheduler.py
def add_request(self, req: EngineCoreRequest):
    request = Request.from_engine_core_request(req)
    request.status = RequestStatus.WAITING
    self.waiting.add(request)
    self.requests[request.request_id] = request

# LLM.generate() → LLM._run_engine() → LLMEngine.step()
#   → EngineCoreClient.step() → EngineCore.step() → Scheduler.schedule()
# Scheduler.schedule()  —  vllm/v1/core/sched/scheduler.py:396
def schedule(self):
    # Phase 1: 处理 running 队列
    for request in self.running:
        num_new_tokens = request.num_tokens - request.num_computed_tokens
        num_new_tokens = min(num_new_tokens, remaining_token_budget)
        ok = self.kv_cache_manager.allocate_slots(request, num_new_tokens)
        if not ok:
            self._preempt(request)  # KV Cache 不够，踢回 waiting
    
    # Phase 2: 从 waiting 队列准入新请求
    for request in self.waiting:
        # 查前缀缓存命中
        computed_blocks = self.kv_cache_manager.get_computed_blocks(request)
        request.num_computed_tokens = len(computed_blocks) * block_size
        
        num_new = min(remaining_prompt_tokens, remaining_token_budget)
        ok = self.kv_cache_manager.allocate_slots(request, num_new,
                                                   new_computed_blocks=computed_blocks)
        if not ok:
            break  # KV Cache 不够，后面的请求等下一步
        
        self.running.append(request)
        self.waiting.remove(request)
    
    return SchedulerOutput(num_scheduled_tokens={...}, ...)

# LLM.generate() → LLM._run_engine() → LLMEngine.step()
#   → EngineCoreClient.step() → EngineCore.step() → Executor.execute_model()
# EngineCore.step()  —  vllm/v1/engine/core.py
self.executor.execute_model(scheduler_output)
  # ↓ Executor 广播 RPC 给所有 Worker
  # Worker.execute_model()  —  vllm/v1/worker/gpu_worker.py:955
  self.model_runner.execute_model(scheduler_output)
    # ↓ 真正干活的地方
    # GPUModelRunner.execute_model()  —  vllm/v1/worker/gpu_model_runner.py:4069

# GPUModelRunner._update_states()  —  gpu_model_runner.py（精简）

input_ids: torch.Tensor   # shape [N_tokens]
positions: torch.Tensor   # shape [N_tokens]

attn_metadata = FlashAttentionMetadataBuilder.build(
    block_table=block_table_gpu,  # [num_reqs, max_blocks]
    slot_mapping=slot_mapping,    # [N_tokens]
    seq_lens=seq_lens,
    ...
)

# GPUModelRunner.execute_model()  —  vllm/v1/worker/gpu_model_runner.py:4069（精简）
with set_forward_context(attn_metadata, self.vllm_config):
    hidden_states = self.model(
        input_ids=input_ids,   # [N_tokens]
        positions=positions,   # [N_tokens]
    )

# GPUModelRunner.execute_model()  —  gpu_model_runner.py（精简）
# 只对每个请求"最后一个 token"的 hidden state 计算 logits
logits = self.model.compute_logits(hidden_states[logits_indices])
# logits: [N_req, vocab_size]

self._execute_model_state = ExecuteModelState(logits=logits, ...)
return None   # 注意这里返回 None！

# EngineCore.step()  —  vllm/v1/engine/core.py
def step(self):
    scheduler_output = self.scheduler.schedule()
    
    self.executor.execute_model(scheduler_output, non_block=True)   # GPU forward（非阻塞）
    grammar_output = self.scheduler.get_grammar_bitmask(scheduler_output)  # CPU 并行
    model_output = self.executor.sample_tokens(grammar_output)      # 等 GPU + 采样
    ...

# LLM.generate() → LLM._run_engine() → LLMEngine.step()
#   → EngineCoreClient.step() → EngineCore.step() → Executor.sample_tokens() → Sampler.forward()
# EngineCore.step()（精简）
self.executor.execute_model(scheduler_output, non_block=True)  # GPU forward
grammar_output = self.scheduler.get_grammar_bitmask(...)       # CPU 并行
model_output = self.executor.sample_tokens(grammar_output)     # ← 这里触发采样

if needs_logprobs:
    raw_logprobs = F.log_softmax(logits.float(), dim=-1)

# 白名单：只允许特定 token
logits[~allowed_token_ids_mask] = float('-inf')
# 黑名单：bad_words 列表
logits = apply_bad_words(logits, bad_words_token_ids)
# min_tokens：未到最小长度时屏蔽 EOS
if not_yet_min_tokens:
    logits[:, eos_token_id] = float('-inf')
# logit_bias：用户直接调整某些 token 的分数
logits += logit_bias
# 重复惩罚 / 频率惩罚 / 存在惩罚
logits = apply_all_penalties(logits, prompt_ids, output_ids, penalties)

# Sampler.forward()  —  vllm/v1/sample/sampler.py
if all_greedy:
    # 快速路径：所有请求都是 greedy，直接 argmax
    sampled = logits.argmax(dim=-1, keepdim=True)   # [N_req, 1]

elif all_random:
    # 随机采样路径
    logits = apply_temperature(logits, temperatures)  # logits /= T
    logits = apply_min_p(logits, min_p)               # 过滤极低概率 token
    sampled = top_k_top_p_sampler(logits, top_k, top_p)

else:
    # 混合：按请求分别处理，用 torch.where 合并
    greedy = logits.argmax(dim=-1)
    random = top_k_top_p_sampler(logits, ...)
    sampled = torch.where(is_greedy_mask, greedy, random)

# LLM.generate() → LLM._run_engine() → LLMEngine.step()
#   → EngineCoreClient.step() → EngineCore.step() → Scheduler.update_from_output()
# EngineCore.step()（精简）
model_output = self.executor.sample_tokens(grammar_output)
self.scheduler.update_from_output(scheduler_output, model_output)  # ← 这里

# Scheduler.update_from_output()  —  vllm/v1/core/sched/scheduler.py:1501
for req_id, new_token_id in model_output.sampled_token_ids.items():
    request = self.requests[req_id]
    
    # 追加新 token
    request.output_token_ids.append(new_token_id)
    request.num_computed_tokens += num_scheduled_tokens[req_id]
    
    # 检查停止条件
    is_eos = (new_token_id == tokenizer.eos_token_id)
    is_max = (len(request.output_token_ids) >= sampling_params.max_tokens)
    is_stop = _check_stop_strings(request, new_token_id)
    
    if is_eos or is_max or is_stop:
        request.status = RequestStatus.FINISHED_STOPPED
        self.kv_cache_manager.free(request)   # 释放 KV 块
    
    # 完整的 KV 块写入前缀缓存（供后续请求复用）
    self.kv_cache_manager.cache_blocks(request)

# LLM.generate() → LLM._run_engine() → LLMEngine.step()
#   → OutputProcessor.process_outputs() → IncrementalDetokenizer.update()
# LLMEngine.step()（精简）
engine_core_outputs = self.engine_core.step()
return self.output_processor.process_outputs(engine_core_outputs)  # ← 这里解码

# vllm/v1/engine/detokenizer.py（精简）
class IncrementalDetokenizer:
    def update(self, request, new_token_id):
        # 用双 token 解码
        new_text = self.tokenizer.decode(
            [self.prev_token_id, new_token_id],
            skip_special_tokens=True,
        )
        # 去掉上一次已经输出的部分，只返回新增字符
        delta = new_text[len(self.prev_decoded_text):]
        self.prev_decoded_text = new_text
        self.prev_token_id = new_token_id
        return delta