YG_FT/compute/README.md

# Compute Platform

算力平台与应用平台分开部署，本目录用于后续实现单机多 GPU 调度、文件网关和训练引擎适配。

## 目录结构

```text
compute/
  api/                 # 只允许应用平台访问的内部 Compute API
  agent/               # 单机 Agent，负责 GPU、进程、工作区管理
  engines/
    llama_factory/     # LLaMA-Factory 训练引擎适配器
  file_gateway/        # 本地磁盘上传、下载、预览、离线导入
  tests/
```

## 开发职责

- GPU 发现、状态上报、锁定和释放。
- 本地磁盘工作区管理。
- 创建、停止、查询训练/评测/推理/合并任务。
- LLaMA-Factory 命令生成、日志解析、产物收集。
- 分片上传、短时下载、离线导入。
- 通过服务间 token 接受应用平台调用。

## 运行模式

- 默认 `COMPUTE_EXECUTION_MODE=real`，Compute API 会通过 `compute.agent.process_manager.ProcessManager` 启动真实 `llamafactory-cli train` 子进程，并将日志写入 `TRAINING_LOG_ROOT`。
- 真实模式下 GPU 发现优先使用宿主机 `nvidia-smi`。如果部署环境暂时无法调用 `nvidia-smi`，可通过 `COMPUTE_GPU_COUNT`、`COMPUTE_GPU_NAME`、`COMPUTE_GPU_MEMORY_GB`、`COMPUTE_GPU_POWER_LIMIT_W` 声明兼容 GPU 清单，便于应用侧先完成节点登记和联调。
- 仅隔离联调时可设置 `COMPUTE_EXECUTION_MODE=simulator`，启用内存状态机和合成 GPU/日志数据。该模式不得作为生产运行路径。
- 服务间鉴权默认开启：设置 `COMPUTE_AUTH_ENABLED=true` 和一致的 `COMPUTE_SERVICE_TOKEN`，应用侧会通过 `X-Compute-Token` 调用 Compute API。
- 真实训练作业会登记到 `TRAINING_LOG_ROOT/compute-jobs.json`。Compute API 重启后会恢复作业索引，继续提供状态、停止和日志查询。
- 同一算力节点内按 GPU ID 做轻量锁定；已有运行中作业占用的 GPU 不允许再次提交，避免同机多 GPU 场景下误复用。

真实执行前提：

- 镜像或宿主机环境中 `llamafactory-cli` 可执行。
- `LLAMA_FACTORY_HOME` 指向 LLaMA-Factory 工作目录。
- 基座模型路径和数据集名称/目录已经在算力服务器本地可访问。
- 应用侧训练任务中的 GPU、模型、数据集配置能映射到当前节点本地路径。

## 应用侧接入

应用平台通过“算力节点”页面维护每台 GPU 服务器的 `Compute API` 和 `File Gateway` 地址。点击连接测试时，Backend API 会主动调用：

```text
GET /modelTF/v1/compute/health
GET /modelTF/compute/resources/gpus
```

连接成功后，应用侧会同步节点健康信息、能力标签和 GPU 清单到 PostgreSQL。多节点阶段仍按“每台算力服务器 = 单机多 GPU 节点”管理，每台服务器都部署 Compute API、Agent、File Gateway 契约和 LLaMA-Factory。

训练闭环：

```text
Frontend 创建/启动训练
  -> Backend API 选择 compute_nodes 节点
  -> Backend API POST /modelTF/compute/jobs 到目标 Compute API
  -> Compute API 启动 llamafactory-cli 子进程
  -> Backend Worker 定时 GET /modelTF/compute/jobs/{id}
  -> Backend API 同步 fine_tune_tasks 状态、进度、PID、日志路径和产物索引
```

## 当前接口能力

日志接口：

```text
GET /modelTF/compute/jobs/{job_id}/logs?tail_lines=200
GET /modelTF/compute/jobs/{job_id}/logs?offset=0&limit=500
```

返回 `content`、`metrics`、`total_lines`、`offset`、`limit`、`has_more`、`next_offset`，用于前端增量刷新和日志平台采集。

文件导入：

```text
POST /modelTF/compute/files/import-local
```

该接口用于应用侧调度前把算力服务器本地可访问的模型/数据集路径导入到 `YG_FT_DATA_ROOT` 内部。目标路径会校验不能逃逸出 `YG_FT_DATA_ROOT`，源路径必须已存在于算力服务器本地或挂载目录。