docs/FAQ.md

# 简明 FAQ

> 归档状态（2026-08-30）：当前代码中的`ACK_*`和`environment_type=ack`是兼容接口名称。历史CPU执行环境为腾讯CVM单节点k3s，但CVM、云硬盘和相关运行面现已释放；本文中专指阿里云ACK/ACR的回答同样属于历史部署说明。

## ATIF 是什么

ATIF 是 Agent Trajectory Interchange Format，即智能体轨迹交换格式。它把 user/agent 消息、tool call、tool observation、token/cost 等记录成统一 JSON。Harbor 的 Qwen Code adapter输出 ATIF v1.6，rLLM 将其转换成训练 Episode。ATIF 负责“发生了什么”，训练 token/logprob 仍由 rLLM gateway 记录。

## ACK 注册怎么做

个人实名认证后开通 ACK、ACR、VPC/交换机/NAT；创建北京 ACK 基础版和 ACR 个人版；给 RAM 用户配置 RAM + Kubernetes RBAC；下载公网 kubeconfig。Mac 使用 Docker 推送基础镜像并执行 `make ack-prepare`；AutoDL 不安装 Docker、Git 或 uv。

## adapter 直接接受预构建 docker_image 是什么意思

任务在 `task.toml [environment]` 写入完整镜像引用，例如：

```toml
[environment]
docker_image = "registry.cn-hangzhou.aliyuncs.com/team/task@sha256:..."
```

provider 可直接拉取这个已经构建好的最终环境，不必现场解释 `environment/Dockerfile`。它必须已经包含正确仓库版本和任务依赖；不是随便一个 Ubuntu/Qwen 镜像。当前 ACK adapter 同时支持 Dockerfile 构建和预构建镜像。

## Docker 构建是在 GPU 服务器还是 ACK

构建计算在 ACK 的独立 `buildkitd` Pod 中。AutoDL 上的 Harbor ACK adapter 运行 `buildctl`，经本机 `127.0.0.1` 和 `kubectl port-forward` 把 Dockerfile/context 发给 BuildKit；AutoDL 不需要 Docker daemon，但需要 `kubectl` 和 `buildctl`。

## 为什么 BuildKit 地址不能写 ClusterIP DNS

Harbor 位于 ACK 外，不能直接解析或路由到 ClusterIP。AutoDL 方案不创建 BuildKit LoadBalancer，而是使用公网 ACK API 上的 `kubectl port-forward` 将 ClusterIP 映射到 AutoDL `127.0.0.1:1234`，同时保留 mTLS。

## BuildKit 是否等于完全安全的 Sandbox

不是。本项目在 ACK 使用 privileged rootful BuildKit，以避开托管节点禁用 user namespace 导致的 rootlesskit 启动失败。它不挂载宿主机 Docker socket，但 BuildKit Pod 本身具有高权限，并执行不可信 Dockerfile。正式训练必须使用独立 CPU Builder 节点池、PVC 配额、依赖源白名单和 ACR 最小推送权限；不要与业务工作负载混部。

## staleness 是什么

异步训练时，一条 rollout 由权重版本 N 生成，但被消费时训练器可能已更新到 N+k；k 就是该样本的策略陈旧度。越大越偏离当前策略，off-policy 风险越高。`staleness_threshold` 控制允许积压/派发的额度，不等价于秒数。首轮保留 0.5，并监控 `async/staleness_mean|max`。

## 额外监控要改 Harbor 或 W&B 吗

reward、advantage、过滤率和 staleness 不需要改 Harbor，开启 rLLM 的 W&B logger 即可。Pod pending/OOM、镜像构建、gateway 队列等应先接 ACK Prometheus、Kubernetes Events、vLLM metrics 和 Harbor 日志。只有需要统一实时面板时，才给 rLLM runtime 增加少量 metrics hook。

## 在哪固定 Qwen Code 版本

Harbor CLI：`--ak version=0.16.2`。rLLM：`rllm.remote_runtime.harbor.agent_kwargs.version=0.16.2`；本项目由 `train_harbor_ack.py` 从 `QWEN_CODE_VERSION` 写入。不要使用 `@latest` 做训练对比。

## 如何预装 Node/Qwen Code

用 `docker/qwen-code-overlay.Dockerfile` 在每个任务最终镜像上增加 Node/NVM/Qwen 层，然后推送到 ACR。本项目补丁 `harbor-qwen-skip-preinstalled.patch` 会在版本一致时跳过网络安装；未预装时，ACK 改从可访问的 `nodejs.org` 安装固定 Node.js 22.17.0，再从 npm 安装固定 Qwen Code。Docker/Daytona 仍使用 Harbor 原始 NVM 路径。ACK 设置 `APPLY_QWEN_PREINSTALL_PATCH=1`。

## 如何允许访问 gateway 和依赖源

gateway 使用 AutoDL 6006/6008 映射的 HTTPS 公网入口并启用 Token。`CANARY_MODEL_BASE_URL` 以 `/v1` 结尾；`RLLM_GATEWAY_PUBLIC_URL` 只填写公网 origin，不带 `/v1`，因为 rLLM 会自动追加 `/sessions/<id>/v1`。依赖源在 ACK 层通过 NAT、安全组、NetworkPolicy/代理放行；优先把 Docker、npm、PyPI、apt、Git/Hugging Face 依赖镜像到 ACR 或国内代理。ACK adapter 当前不声明 Harbor hostname allowlist 能力，因此不能仅靠 Harbor 的 allow-host 参数完成白名单隔离。

## 参考源码

- [rLLM Harbor SWE 示例](https://github.com/rllm-org/rllm/tree/main/examples/harbor_swe)
- [rLLM Harbor trial helper](https://github.com/rllm-org/rllm/blob/main/rllm/integrations/harbor/trial_helper.py)
- [Harbor ACK adapter](https://github.com/harbor-framework/harbor/blob/main/src/harbor/environments/ack.py)
- [Harbor Qwen Code adapter](https://github.com/harbor-framework/harbor/blob/main/src/harbor/agents/installed/qwen_code.py)
- [Harbor 任务与网络配置](https://www.harborframework.com/docs/tasks)
- [Qwen Code](https://github.com/QwenLM/qwen-code)

## 当前PPO和GRPO是什么关系

两者复用冻结数据、任务镜像、Agent、ACK sandbox、rollout和Harbor terminal reward。GRPO使用group-relative advantage且不需要critic；已实现并完成40步的完整PPO增加critic/value、GAE、critic optimizer和相应checkpoint。现有GRPO虽然使用PPO-style clipped policy loss，但不能因此称为完整PPO。

## 为什么PPO trainer使用4张GPU但总共需要5张

8B PPO需要同时容纳actor、critic/value及训练状态。实测colocated vLLM会与长序列反向传播争抢单rank显存，因此当前已验证拓扑为4×80GB trainer FSDP加1×80GB独立TP=1 vLLM，共5卡；训练边界为40K。增加trainer卡数但同时复制vLLM不能解决单rank显存竞争。

## 为什么当前Verified27不是40K

checkpoint评测入口启动一个40K vLLM，以便先运行test38；但Verified27复用历史模型选择协议，Agent侧`RUN_PROFILE`实际为32768 context。因此test38是40K、Verified27是32K。历史约64K SFT为10/27，当前正式32K SFT为4/27；这提示上下文可能重要，但历史结果不是单一offline-v3作业，必须用当前配置仅改变context后才能做因果归因。

## 为什么没有独立的PPO preflight、resume和KL命令

网络、数据、镜像、GPU和ACK门禁复用现有preflight；没有必要复制一套PPO命令。checkpoint恢复和非零KL是PPO验收阶段，通过同一个`ppo-smoke`入口更换参数完成，避免多个Make目标产生配置漂移。

## PPO是不是Klear-AgentForge论文复现

不是。Klear公开方案使用revised GRPO。项目PPO使用同一SFT checkpoint和本项目freeze/verifier，是独立对照实验，报告时必须明确算法、数据manifest和critic配置。