Completers¶

底层的 SamplingClient 只处理 token ID。两个轻量封装类在这个基础上做了抽象，让你按训练循环实际需要的方式工作：

TokenCompleter 接收 ModelInput，返回包含 token 和 logprob 的 TokensWithLogprobs，适合 RL rollout、在线奖励收集和 token 级分析。
MessageCompleter 接收带有 role 和 content 的消息列表，返回结构化消息，适合评测、LLM as a judge、多轮对话和生产推理。它通过 renderer 完成消息与 token 之间的转换。

共同行为¶

两类 completer 都接收 SamplingClient 和 SamplingParams，在遇到配置的停止序列时结束生成，也都支持获取 token 的 logprob。选择哪一种，取决于流程需要直接处理 token，还是处理结构化消息。

Pattern¶

from mint.completers import TinkerTokenCompleter, TinkerMessageCompleter
from mint.renderers import get_renderer

service_client = mint.ServiceClient()
sampling_client = service_client.create_sampling_client(base_model="Qwen/Qwen3-0.6B")
tokenizer = sampling_client.get_tokenizer()
renderer = get_renderer("qwen3", tokenizer)

# 示例 1：TokenCompleter 跑 RL rollout
token_completer = TinkerTokenCompleter(sampling_client=sampling_client)

prompt_ids = tokenizer.encode("法国的首都是")
prompt = mint.types.ModelInput.from_ints(prompt_ids)
sampling_params = mint.types.SamplingParams(
    max_tokens=16,
    temperature=0.7,
    stop=renderer.get_stop_sequences(),
)

token_result = token_completer.complete(
    prompt=prompt,
    sampling_params=sampling_params,
)
print(f"Tokens: {token_result.tokens}")
print(f"Logprobs: {token_result.logprobs}")

# 示例 2：MessageCompleter 用于评估
message_completer = TinkerMessageCompleter(
    sampling_client=sampling_client,
    renderer=renderer,
)

messages = [
    {"role": "system", "content": "你是一名数学辅导老师。"},
    {"role": "user", "content": "7 * 8 是多少？"},
]

message_result = message_completer.complete(
    messages=messages,
    sampling_params=mint.types.SamplingParams(max_tokens=32, temperature=0.0),
)
print(f"Response: {message_result}")  # {"role": "assistant", "content": "..."}

完整源码：https://github.com/MindLab-Research/mint-quickstart/blob/main/concepts/completers.py

API Surface¶

类	输入	输出	用途
`TinkerTokenCompleter`	`ModelInput`（token）	`TokensWithLogprobs`	RL 循环、token 级分析
`TinkerMessageCompleter`	`list[Message]`（role / content）	`Message`（role / content）	评估、LLM-as-judge、聊天

通用参数：

sampling_client — 底层 SamplingClient 实例。
renderer（仅 MessageCompleter）— 处理 message → token 和 token → message 的转换。
sampling_params — SamplingParams(max_tokens, temperature, top_p, stop, ...)。

返回类型：

TokensWithLogprobs — namedtuple：(tokens: list[int], logprobs: list[float])。
Message — 字典：{"role": str, "content": str}。

Caveats & Pitfalls¶

Stop sequence：每次都传 stop=renderer.get_stop_sequences()，防止模型越过预期的 message 边界继续生成。缺少 stop token 时，模型可能一直写到超出回复范围。
MessageCompleter 必须带 renderer：没传 renderer 的 MessageCompleter 在第一次 .complete() 时就会失败。初始化时务必用对应模型家族的 renderer。
Logprob 的开销：请求 logprob 会增加少量计算。大规模 RL 中可以批量生成，或只为关键轨迹获取 logprob。
异步变体：用 complete_async() 并发生成。先收集各次调用返回的 future，再调用 .result() 等待结果，让请求并行执行。
Sampler 失同步：保存并重新加载模型权重之后，要重建 SamplingClient 和 completer。旧的 completer 不会报错，但仍在用旧权重采样。