BaseSampler

BaseSampler 位于 core/base_sampler.py，为推理调用方提供生成接口，并持有具体的推理 engine。模型和 Renderer 由 ModelEngine 创建后传入；Sampler 负责选择后端和转发调用。

组件与状态

组件	职责	源码
BaseSampler	根据 `sample_backend` 选择 engine，转发生成请求	`core/base_sampler.py`
BaseEngine / HuggingFaceEngine	定义后端接口，使用模型和 Renderer 执行生成	`core/utils/inference_engine.py`
SyncSampler	将异步生成接口适配为 CLI 使用的同步迭代器	`samplers/cli_sampler.py`
`run_chat`	创建组件，读取用户输入，保存对话历史并输出回复	`samplers/cli_sampler.py`

当前 BaseSampler 直接构造 HuggingFaceEngine，后端选择不经过 BasePlugin 注册表。HuggingFaceEngine 保存模型、Renderer 和推理参数；对话历史由 run_chat 中的消息列表持有，每次请求传入完整历史。

单次生成路径

run_chat：追加 user 消息
  → SyncSampler.generate(messages)
  → BaseSampler.generate(messages, tools)
  → HuggingFaceEngine.generate(messages, tools)
      → Renderer.render_messages(..., is_generate=True)
      → input_ids / attention_mask 转为设备上的张量
      → 后台线程调用 model.generate
      → AsyncTextIteratorStreamer 异步返回文本片段
  → CLI 逐段输出，拼成 assistant 消息并加入历史

HuggingFaceEngine 用信号量限制同时进入生成过程的请求数。它将 max_new_tokens 和 streamer 传给 model.generate，streamer 跳过 prompt 和特殊 token；返回值是解码后的文本片段，不是 token ID，也不保证每个片段恰好对应一个 token。

SyncSampler 另行维护后台事件循环，逐次等待异步生成器的下一段文本，再交给同步调用方。这个适配层改变调用方式，不改变消息渲染或模型生成逻辑。

接口与当前支持范围

接口	输入与输出	当前行为
`generate(messages, tools=None)`	标准 Message 列表、可选 tools 字符串；异步产出 `str`	Hugging Face 流式生成
`batch_infer(dataset)`	Dataset；约定返回 Sample 列表	HuggingFaceEngine 抛出 `NotImplementedError`

BaseSampler 的非 HF 后端分支会抛出 ValueError。CLI 中设置 train_dataset 会进入批量推理分支，但当前 engine 尚未实现该接口。因此，已实现的用户路径是 HF 交互式对话，启动方式见推理，配置字段见推理参数。

扩展边界

新增推理后端时，实现 BaseEngine 的接口，并接入 BaseSampler 的后端选择；仅添加文件或写入新的 sample_backend 名称不会完成接入。后端需要保持异步文本流接口，并明确批量推理是否可用，SyncSampler 才能沿用现有适配方式。

改变模板和消息到模型输入的转换时，修改 Renderer；改变生成参数的传递、模型调用或输出流时，修改 engine；改变命令行输入和对话历史管理时，修改 run_chat。当前 HF 生成调用只传递 Renderer 结果中的 input_ids 和 attention_mask，扩展其他模型输入时还需要补齐 engine 向模型传参的路径。