Completers

Completer 在 sampling client 之上提供两层抽象。TokenCompleter 操作 token ID 和原始 ModelInput 对象 —— 给在 token 级别上跑的 RL 循环用。MessageCompleter 操作带 role 和 content 的 message 字典 —— 给 evaluator、LLM-as-judge 模式、聊天应用用。

Concept

Sampling client 返回的是原始 token ID。大部分训练和评估流程都需要更上层的抽象：

• TokenCompleter — 输入：ModelInput（token）。输出：TokensWithLogprobs（token + logprob）。用在 RL rollout、在线 reward 收集、token 级分析里。
• MessageCompleter — 输入：list[Message]（role + content）。输出：Message（结构化回复）。用在 evaluator、LLM judge、多轮交互、生产推理里。

两类 completer 都会处理：

• Stop token — 触到 stop sequence 自动停止生成。
• 采样参数 — temperature、top-p、max-tokens 等标准 LLM 采样旋钮。
• Logprob — RL 和 importance weighting 时，可以连同 token 一起拿到 logprob。

Pattern

import mint
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

通用参数：

• 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()，防止 model 越界生成。缺 stop token 时 model 可能会写过预期的 message 边界。
• MessageCompleter 必须带 renderer：没传 renderer 的 MessageCompleter 在第一次 .complete() 时就会失败。初始化时务必用对应 model 家族的 renderer。
• Logprob 的开销：请求 logprob 会带一点算力开销。大规模 RL 里可以考虑批量 complete 或只在重要 trajectory 上取 logprob。
• 异步变体：用 complete_async() 做并发 complete。调 .result() 之前先收齐 future，吞吐才能拉满。
• Sampler 失同步：保存 + 重载 model weights 之后，要重新建 SamplingClient 和 Completer。旧 completer 不会报错，但仍然在用旧 weights 采样。