InferenceConfig 类使用指南
1. 概述
InferenceConfig 是推理框架中统一的配置入口类，用于替代原有的 runner_settings 字典。它采用了结构化的 dataclass 设计，提供了类型安全检查、嵌套配置管理以及自动化的验证逻辑，使得模型推理的参数配置更加清晰、易维护。
2. 配置类结构
InferenceConfig 聚合了多个维度的子配置类，每个类负责特定的功能领域，主要通过yaml文件配置，可参考各模型config目录下的示例yaml进行配置：
2.1 DataConfig (数据配置)
管理输入数据相关的参数。
dataset: 数据集名称（默认 "default"）。dataset_path: 数据集路径（默认 ""），非"default"数据集时必须指定。input_truncated_len: 最大输入序列长度（默认 256），如果prompt超过这一长度会被截断。temperature: 采样温度（默认 0.0）。设置为 0 时使用 greedy decoding；值越大，采样随机性越强。top_p: 采样参数-top_p（默认 1.0）。top_k: 采样参数-top_k（默认 0）。seed: 采样参数-seed（默认 None）。
2.2 ModelConfig (模型配置)
管理模型运行时的特有行为。
model_name: 模型名称（默认 "model"）。model_path: 模型权重路径（默认 ""）。output_path: 保存输出、日志、分析数据、图缓存等的目录（不指定时默认和所执行的yaml配置统一目录）。dtype: 计算使用的数据类型（默认 "bfloat16"）。with_ckpt: 是否加载权重检查点（默认 True）。next_n: 投机采样步骤数，即 MTP 模块数量（默认 0）。exe_mode: 执行模式，可选 eager, ge_graph, npugraph_ex（默认 "eager"）。enable_static_kernel: 指定npugraph_ex是否开启静态kernel（默认 False）。enable_cache_compile: 是否启用缓存编译（默认 False）。force_eplb: 是否为 MoE 模型开启强制的专家负载均衡（默认 False）。enable_profiler: 是否启用性能分析器（默认 False）。enable_weight_nz: 是否启用权重 NZ 格式（默认 True）。platform_version：指定运行推理的平台，支持配置为 A2、A3 或 950。不传入时使用torch.npu.get_device_name()获取设备名，如果获取失败，则指定为A3。不建议传入此参数。custom_params：存放模型特有特性的字典（默认{}）。
2.3 ParallelConfig (并行配置)
定义分布式推理时的并行维度和 Rank 信息。
world_size: 总进程数（默认 1）。global_rank: 不支持yaml配置。全局 Rank ID，可在脚本中获取环境变量后传入。local_rank: 不支持yaml配置。节点内 Rank ID，可在脚本中获取环境变量后传入。attn_tp_size: Attention 层TP并行数（默认 1）。attn_dp_size: 不支持配置。Attention 层DP并行数，推导方式：world_size // attn_tp_size。cp_prefill_dp_size: 不支持配置。CP prefill 阶段内部使用的DP并行数，推导方式：world_size // (attn_tp_size * cp_size)。embed_tp_size: Embedding 层TP并行数（默认 1）。embed_dp_size: 不支持配置。Embedding 层DP并行数，推导方式：world_size // embed_tp_size。moe_tp_size: MoE 层TP并行数，只有MoE模型支持（默认 1）。moe_ep_size: 不支持配置。MoE 层专家并行度，推导方式：world_size // moe_tp_size。lmhead_tp_size: LM Head 层TP并行数（默认 1）。dense_tp_size: dense层TP并行数（默认 1）。o_proj_tp_size: attention output 映射层TP并行数（默认 1）。cp_size: context并行度（默认 1）。当前仅支持cp_size = 1（不开启 CP）或cp_size == world_size配置。shared_tp_size: 共享专家层TP并行数（默认1）。
2.4 SchedulerConfig (调度配置)
控制请求调度器的策略。
batch_size: 全局总 Batch Size（默认 1），batch_size 必须为 attn_dp_size 的整数倍。max_new_tokens: 最大生成 token 数（默认 32）。max_prefill_tokens: 单次 prefill batch 的最大 prompt token 预算（默认 0）。 当设置为 0 时，框架默认按input_truncated_len * batch_size_per_dp_rank计算预算。 在 executor-core 支持的模型中，prefill 默认采用 packed sequence 方式执行，该参数用于限制 packed 后单批次的 token 总量。batch_size_per_dp_rank: 不支持配置。每个 Rank 的 Batch Size。推导方式：batch_size // attn_dp_size。mem_fraction_static: 静态内存分配比例（默认 0.85），用于控制推理阶段可用于静态占用的设备内存比例。block_size: 单个 KV Cache block 可容纳的 token 数（默认 128），用于控制 Paged Attention 的 block 粒度。cp_mini_batch: CP prefill 场景下单次调度的请求数上限（默认 -1，表示不额外限制）。当parallel_config.cp_size > 1时可用于将 prefill 请求拆成更小的 mini-batch；DeepSeek-V4 当前 CP 路径要求设置为 1。num_reserved_decode_tokens: （仅 PD decode 端）每个在途请求保留的 KV token 数（默认 64），由DecodePreallocQueue.pop_preallocated用于准入控制。prealloc/transfer/running 流水线中的每条请求都会按此值预留近期 decode 步所需的 KV block 余量；若新请求的接纳会令 KV 池超出该余量，则不再准入。值越小吞吐越高，但突发负载下 retraction 抖动也越多。
3. 日志配置
在线/离线主入口（executor/online/server.py、executor/model_runner.py、executor/offline/infer.py::main()）启动时统一调用 executor/utils/logging_config.py::setup_logging() 完成根日志器配置，保证所有模块共享一致的格式与级别。
- 日志格式：
2026-04-25 19:35:12.345 - INFO - module:lineno - message，时间精度到毫秒。 - 级别控制：通过环境变量
CANN_RECIPES_LOG_LEVEL指定，默认INFO，支持DEBUG/INFO/WARNING/ERROR/CRITICAL。 - 库代码规范：所有库模块统一使用
logger = logging.getLogger(__name__)，不要在库代码中调用logging.basicConfig，避免覆盖根配置。 - 第三方降噪：
paramiko/httpx/httpcore/urllib3自动降级到WARNING，避免 INFO 级别的握手 / 连接日志淹没业务输出。
4. 基本用法
4.1 从字典创建
通常与 YAML 解析器配合使用：
import yaml
from executor.core.config import InferenceConfig
# 读取 YAML 配置文件
with open("config.yaml", "r") as f:
yaml_data = yaml.safe_load(f)
# 构造配置对象，需要传入 rank 信息
config = InferenceConfig.from_dict(
yaml_data,
global_rank=0,
local_rank=0
)
# 访问配置（注意：所有配置均需通过子配置对象访问）
print(config.model_config.model_name)
print(config.model_config.exe_mode)
print(config.parallel_config.attn_tp_size)
print(config.scheduler_config.max_new_tokens)
print(config.scheduler_config.batch_size)