自主论文agent-ML Intern

大山同学

433人浏览 · 2026-05-02 14:05:27

大山同学 · 2026-05-02 14:05:27 发布

文章目录

ML Intern 项目运行逻辑文档

ML Intern 项目运行逻辑文档

GitHub 仓库：https://github.com/huggingface/ml-intern

HuggingFace Space 在线体验：https://huggingface.co/spaces/smolagents/ml-intern

安装：git clone git@github.com:huggingface/ml-intern.git && cd ml-intern && uv sync && uv tool install -e .

1. 项目概述

ML Intern 是一个由 HuggingFace 团队开发的 自主 ML 工程助手（ML Engineering Assistant），能够自主研究、编写和交付高质量 ML 代码。它深度整合了 HuggingFace 生态系统——文档、论文、数据集和云算力，让用户通过自然语言对话即可完成从文献调研到模型训练的完整 ML 工作流。

核心定位：ML Intern 不是一个简单的聊天机器人，而是一个自主 Agent——它会主动调用工具、执行代码、提交训练任务、监控训练过程，直到任务真正完成。系统提示词明确要求：“不要只描述你打算做什么，继续调用工具直到任务可验证地完成。”

1.1 核心能力

能力领域	具体功能
文献研究	搜索论文、爬取引用图谱、阅读方法论章节、提取训练配方（数据集+方法+超参→结果）
数据集审计	检查 HF 数据集的 schema/列名/行数/分布/样本行，发现类别不平衡、缺失值等
代码开发	在沙箱中编写、测试、调试 ML 脚本，支持 CPU 和 GPU 沙箱
模型训练	提交 HF Jobs 到云 GPU（T4/A10G/A100/L40S），支持 SFT/DPO/GRPO 等方法
训练监控	集成 Trackio 训练监控，自动部署公开指标面板，设置告警规则
文档查阅	浏览 HF 文档结构、获取具体 API 文档、搜索 OpenAPI 规范
仓库管理	读写 HF Hub 仓库文件、Git 操作（创建分支/PR/合并）、上传模型
GitHub 搜索	在 GitHub 搜索 ML 示例代码、列出仓库、读取文件内容
错误恢复	OOM 自动调整 batch size + gradient checkpointing、API 错误自动查文档修复

1.2 技术架构

采用 前后端分离 架构：

前端：React + TypeScript + Vite + MUI，负责聊天界面和会话管理
后端：Python + FastAPI + LiteLLM，负责 Agent 推理循环、工具调用和会话持久化
Agent 核心：自主推理循环（agent loop），通过 LiteLLM 调用多种 LLM，并内置丰富的工具系统

1.3 主要执行逻辑

ML Intern 的核心执行流程遵循 “用户输入 → LLM 推理 → 工具调用 → 结果反馈 → 循环” 的标准 Agent 范式，但在此基础上做了重要扩展：

用户自然语言输入（如 "fine-tune LLaMA 3 on my dataset"）
  ↓
[1] LLM 接收用户消息 + 系统提示词 + 工具定义
  ↓
[2] LLM 返回工具调用（而非纯文本）——选择 research 工具
  ↓
[3] research 子 Agent 启动（独立上下文，只读工具集）
    ├─ 调用 hf_papers(search) → 搜索 HF Papers 上的相关论文
    ├─ 调用 hf_papers(citation_graph) → 爬取 Semantic Scholar 引用图谱
    ├─ 调用 hf_papers(read_paper, section=4) → 阅读论文方法论章节
    ├─ 调用 hf_papers(find_datasets) → 发现论文关联的 HF 数据集
    ├─ 调用 github_find_examples → 搜索实现代码
    └─ 返回研究摘要给主 Agent
  ↓
[4] 主 Agent 根据研究结果，调用 hf_inspect_dataset 审计数据集
  ↓
[5] 主 Agent 在沙箱中编写训练脚本（write → bash → edit 调试循环）
  ↓
[6] 主 Agent 调用 hf_jobs(operation="run") 提交云端 GPU 训练任务
  ↓
[7] 主 Agent 调用 hf_jobs(operation="logs") 监控训练进度
  ↓
[8] 训练完成 → 模型自动推送到 HF Hub（push_to_hub=True）
  ↓
[9] 主 Agent 返回结果：模型 URL + Trackio 监控面板 URL

关键执行特征：

特征	说明
多轮工具调用	不是一次 LLM 调用就结束，而是循环最多 300 轮，每轮 LLM 决定调用哪个工具
LLM 作为调度器	LLM 不直接执行操作，只决定"调用什么工具 + 传什么参数"，工具负责执行
子 Agent 委托	research 工具启动独立 LLM 推理循环，使用只读工具集，研究结果不影响主上下文
审批门控	危险操作（GPU 训练、文件上传）需用户确认，可通过 YOLO 模式自动批准
错误自愈	OOM → 调参+升级GPU；API错误 → 查文档修复；训练发散 → 降学习率

1.4 创新点分析

与主流 Agent（如 LangChain Agent、AutoGPT、OpenAI Assistants）相比，ML Intern 的核心创新在于面向 ML 工程的领域特化，而非通用 Agent 框架。具体创新点：

创新点 1：文献驱动的 ML 工作流

主流 Agent 的做法：用户描述任务 → Agent 直接生成代码 → 执行 → 报错 → 重试

ML Intern 的做法：用户描述任务 → Agent 先研究论文 → 提取已验证的训练配方 → 基于论文结果编写代码 → 执行

核心差异：ML Intern 的系统提示词明确声明"你对 HF 库的知识是过时的"，强制 Agent 在写任何 ML 代码前必须先查论文和文档。这避免了 LLM 的"知识过时幻觉"——错误 import、错误参数名、错误 Trainer 配置。

实现机制：

research 子 Agent 使用独立上下文，不会污染主 Agent 的 token 预算
子 Agent 按固定工作流执行：锚定论文 → 爬引用图谱 → 读方法论 → 提取配方 → 验证数据集 → 找代码
研究结果必须"归因"：每个发现必须关联"数据集X + 方法Y + lr=Z → 分数W（基准V）"

创新点 2：论文精准识别与引用图谱爬取

如何精准识别论文——三层识别机制：

第一层：HF Papers 搜索
  ├─ 调用 HF API: GET https://huggingface.co/api/papers/search?q={query}
  ├─ 返回：arxiv_id + 标题 + upvotes + ai_summary + ai_keywords + githubRepo
  └─ 筛选依据：upvotes（社区认可度）、ai_keywords（AI 生成关键词）
  注：有日期/引用数等筛选条件时，自动路由到 Semantic Scholar 的 _s2_bulk_search

第二层：Semantic Scholar 引用图谱
  ├─ 调用 S2 API: GET https://api.semanticscholar.org/graph/v1/paper/ARXIV:{id}/citations
  ├─ 返回：引用论文 + citationCount + influentialCitationCount + year
  └─ 筛选依据：citationCount（引用数）、influentialCitationCount（影响力引用）、year（时效性）

第三层：论文内容深度阅读
  ├─ 获取 arxiv HTML: GET https://arxiv.org/html/{arxiv_id}
  ├─ 或 ar5iv: GET https://ar5iv.labs.arxiv.org/html/{arxiv_id}
  ├─ 用 BeautifulSoup 解析 LaTeX 结构，提取 Section 3/4/5（方法/实验/结果）
  └─ 关键：读方法论章节而非摘要——摘要只说"我们做了什么"，方法论才说"具体怎么做"

代码实现（agent/tools/papers_tool.py）：

_op_citation_graph：调用 Semantic Scholar Graph API，支持 direction=references|citations|both
_op_read_paper：下载 arxiv HTML → _parse_paper_html 解析 LaTeX 结构 → _find_section 按编号/名称模糊匹配章节
Semantic Scholar 请求有速率限制（有 API key 时 1 req/s for search, 10 req/s for others）+ 2 次重试 + 429 退避 60s
S2 响应缓存（最多 500 条），跨会话共享

为什么读 Section 4/5 而非摘要？ 系统提示词明确要求：“Read methodology sections (not abstracts) of the most promising papers”。因为摘要只说"我们提出了X，达到了Y"，而方法论章节才包含"数据集是什么、训练方法是什么、超参是多少"——这些才是可复现的训练配方。

创新点 3：数据集发现与审计闭环

如何发现数据集——两条路径：

路径 A：从论文发现
  ├─ hf_papers(find_datasets, arxiv_id="2310.16948")
  ├─ 内部调用：GET https://huggingface.co/api/datasets?filter=arxiv:{arxiv_id}
  └─ 返回：论文在 HF Hub 上关联的所有数据集（按 downloads/likes 排序）

路径 B：从论文方法论提取
  ├─ read_paper(section=4) → 解析论文实验章节文本
  ├─ LLM 从文本中提取数据集名称
  └─ 用 hf_inspect_dataset 逐一验证数据集是否在 HF Hub 上存在

如何下载数据集——ML Intern 不直接下载数据集，而是：

验证数据集：hf_inspect_dataset 调用 HF Datasets Server API，分两阶段并行获取：
- Phase 1（并行3个）：GET /is-valid（有效性）、GET /splits（split 结构）、GET /parquet（parquet 文件信息）
- Phase 2（并行2个，依赖 Phase 1 的 config/split）：GET /info（列名/schema）、GET /first-rows（样本行预览）
在训练脚本中引用：生成的训练脚本使用 datasets.load_dataset("org/dataset-name")，HF Jobs 执行时自动从 Hub 下载
格式验证：根据训练方法验证列名匹配（SFT 需要 messages/text，DPO 需要 prompt+chosen+rejected，GRPO 需要 prompt）

代码实现（agent/tools/dataset_tools.py）：

inspect_dataset 函数：5 个 HTTP 请求分两阶段并行（Phase 1: 3 个 + Phase 2: 2 个），15s/30s 超时
支持 gated/private 数据集（通过 hf_token 鉴权）
自动检测 config/split（如果用户未指定，取第一个 config 的第一个 split）

创新点 4：知识过时自认知 + 强制文档查阅

这是 ML Intern 最独特的设计哲学——主动承认 LLM 知识过时，并通过工具强制查阅最新文档：

系统提示词（system_prompt_v3.yaml）：
  "You do not know current APIs for TRL, Transformers, PEFT, Trackio,
   or other HF libraries. Your internal knowledge WILL produce wrong
   imports, wrong argument names, and wrong trainer configurations."

强制查阅机制：

编写 ML 代码前必须先调用 research 工具
跳过研究的唯一条件是"非代码的简单操作"
系统提示词列举了 7 种"没有研究时必犯的错误"（错误 import、错误参数、错误数据格式、超时杀任务、模型丢失、批量全挂、静默替换数据集）

对比主流 Agent：大多数通用 Agent 依赖 LLM 的内部知识生成代码，遇到错误再修。ML Intern 则是"研究先行"——先查文档再写代码，从源头避免错误。

创新点 5：沙箱优先开发 + 云端训练分离

开发路径：
  沙箱（CPU，免费）编写+测试脚本 → 确认无误 → hf_jobs 提交到云 GPU 训练

而非：
  直接在云 GPU 上试错 → 每次试错都消耗 GPU 费用

每个会话自动预加载 cpu-basic 沙箱，代码在沙箱中验证后再提交到云 GPU，避免 GPU 资源浪费。

创新点 6：训练监控闭环 + 告警驱动超参调整

训练启动 → Trackio 自动部署公开监控面板
  → 设置告警回调（on_log/on_evaluate）
  → 告警触发 → 读取告警 → 自动决策下一步
     ├─ 发散 → lr × 0.1
     ├─ 过拟合 → weight_decay × 10
     ├─ 早停 → lr × 0.5
     └─ 高准确率 → 精炼当前配置

这形成了训练 → 监控 → 调整 → 重训练的闭环，而非"训练完就结束"的一次性流程。

2. 项目目录结构

ml-intern-main/
├── backend/                  # FastAPI 后端服务
│   ├── main.py               # 应用入口，FastAPI 实例与生命周期管理
│   ├── routes/
│   │   ├── agent.py          # Agent API 路由（REST + SSE 端点）
│   │   └── auth.py           # HF OAuth 认证路由
│   ├── session_manager.py    # 多会话管理器
│   ├── models.py             # 请求/响应 Pydantic 模型
│   ├── dependencies.py       # FastAPI 依赖注入（认证等）
│   ├── user_quotas.py        # 用户配额管理
│   └── kpis_scheduler.py     # KPI 定时聚合调度
│
├── agent/                    # Agent 核心逻辑
│   ├── main.py               # CLI 交互入口
│   ├── config.py             # 配置管理（模型、MCP 服务器、权限等）
│   ├── core/
│   │   ├── agent_loop.py     # 核心 Agent 推理循环
│   │   ├── session.py        # 会话状态管理
│   │   ├── tools.py          # 工具路由器（ToolRouter）
│   │   ├── approval_policy.py# 工具审批策略
│   │   ├── cost_estimation.py# 工具调用成本估算
│   │   ├── model_switcher.py # 模型切换
│   │   ├── effort_probe.py   # 推理努力级别探测
│   │   ├── prompt_caching.py # Prompt 缓存优化
│   │   ├── doom_loop.py      # 死循环检测
│   │   ├── llm_params.py     # LLM 参数解析
│   │   ├── session_persistence.py  # 会话持久化
│   │   ├── session_uploader.py     # 会话上传到 HF
│   │   ├── telemetry.py      # 遥测与心跳保存
│   │   └── redact.py         # 敏感信息脱敏
│   ├── tools/                # 内置工具实现
│   │   ├── research_tool.py  # 研究子 Agent（独立上下文，文献爬取）
│   │   ├── sandbox_tool.py   # 沙箱执行工具（bash/read/write/edit）
│   │   ├── jobs_tool.py      # HF Jobs 管理（提交/查看/取消训练任务）
│   │   ├── dataset_tools.py  # 数据集检查
│   │   ├── docs_tools.py     # HF 文档搜索 + OpenAPI 搜索
│   │   ├── papers_tool.py    # 论文搜索/阅读/引用图谱/数据集发现
│   │   ├── web_search_tool.py# 网页搜索
│   │   ├── plan_tool.py      # 任务规划
│   │   ├── hf_repo_files_tool.py  # HF 仓库文件操作
│   │   ├── hf_repo_git_tool.py    # HF 仓库 Git 操作
│   │   ├── github_*.py       # GitHub 搜索与读取
│   │   ├── notify_tool.py    # 通知工具
│   │   ├── trackio_seed.py   # Trackio 监控面板自动部署
│   │   └── ...
│   ├── context_manager/
│   │   └── manager.py        # 上下文管理（压缩/摘要）
│   ├── messaging/
│   │   ├── gateway.py        # 通知网关（Slack 等）
│   │   ├── slack.py          # Slack 通知提供商
│   │   └── models.py         # 通知数据模型
│   ├── prompts/              # 系统提示词 YAML（v1/v2/v3）
│   └── utils/                # 终端显示、启动动画等工具
│
├── frontend/                 # React 前端
│   ├── src/
│   │   ├── App.tsx           # 应用根组件
│   │   ├── components/
│   │   │   ├── Layout/AppLayout.tsx      # 主布局（侧栏+聊天+代码面板）
│   │   │   ├── Chat/                    # 聊天消息组件（消息列表/输入框/工具调用展示）
│   │   │   ├── SessionChat.tsx          # 单会话聊天容器
│   │   │   ├── SessionSidebar/          # 会话侧边栏
│   │   │   ├── CodePanel/              # 代码/工具输出面板
│   │   │   ├── WelcomeScreen/          # 欢迎页
│   │   │   ├── YoloControl.tsx         # 自动审批开关
│   │   │   ├── ClaudeCapDialog.tsx     # Claude 配额对话框
│   │   │   └── JobsUpgradeDialog.tsx   # Jobs 升级对话框
│   │   ├── hooks/
│   │   │   ├── useAgentChat.ts         # 核心 Hook：对接 AI SDK + SSE 传输
│   │   │   ├── useAuth.ts             # 认证 Hook
│   │   │   └── useUserQuota.ts        # 用户配额 Hook
│   │   ├── lib/
│   │   │   ├── sse-chat-transport.ts   # SSE 传输层实现
│   │   │   ├── chat-message-store.ts   # 消息本地存储
│   │   │   └── research-store.ts       # 研究子 Agent 状态
│   │   ├── store/                      # Zustand 状态管理
│   │   ├── types/                      # TypeScript 类型定义
│   │   └── utils/                      # API 调用、日志等工具
│   └── vite.config.ts       # Vite 配置（代理 /api → 后端）
│
├── configs/
│   ├── cli_agent_config.json      # CLI 模式配置
│   └── frontend_agent_config.json # Web 模式配置
│
└── pyproject.toml            # Python 项目依赖

3. 功能详解

3.1 文献研究（Research Sub-Agent）

ML Intern 最独特的能力是其研究子 Agent——一个独立运行在单独上下文中的轻量 Agent，专门执行文献调研。主 Agent 调用 research 工具时，子 Agent 启动自己的推理循环，使用只读工具集（论文搜索、文档浏览、GitHub 代码搜索等），研究完成后返回摘要给主 Agent。

为什么需要独立上下文？ 研究工作会消耗大量 token（爬取多篇论文、阅读大量方法论），如果共享主上下文，会迅速填满上下文窗口。独立上下文让研究工作不影响主 Agent 的推理能力。

研究子 Agent 的默认工作流（来自系统提示词）：

1. 搜索锚定论文 → 识别领域里程碑论文（高引用、近期、或两者兼有）
2. 爬取引用图谱 → 沿下游方向（引用该论文的后续工作），优先近期+高引用
3. 阅读方法论章节 → 用 read_paper 读 Section 3/4/5（非摘要），提取：
   - 精确数据集（名称/来源/规模/预处理）
   - 训练方法与配置（优化器/学习率/调度/epochs/batch size）
   - 这些选择产生的结果（基准分数/指标/对比）
4. 将结果归因到配方 → "数据集X + 方法Y + lr=Z → 分数W（基准V）"
5. 验证数据集 → 用 hf_inspect_dataset 确认数据集存在且格式匹配
6. 查找代码 → 用 github_find_examples + github_read_file 找实现示例

可用只读工具：read, bash, explore_hf_docs, fetch_hf_docs, find_hf_api, hf_papers, github_find_examples, github_list_repos, github_read_file, web_search, hf_inspect_dataset, hf_repo_files

代码实现：agent/tools/research_tool.py

子 Agent 使用独立的上下文预算：警告阈值 170k tokens，硬上限 190k tokens
超过警告阈值时通知子 Agent 收尾，超过硬上限时强制停止并返回已有内容

3.2 沙箱代码执行（Sandbox）

ML Intern 为每个会话自动预加载一个 cpu-basic 沙箱（基于 HF Spaces），提供安全的代码执行环境。

沙箱工具集（5 个工具）：

工具	功能
`sandbox_create`	创建/替换沙箱（用于需要 GPU 或非默认硬件时）
`bash`	在沙箱中执行 shell 命令
`read`	从沙箱读取文件
`write`	向沙箱写入文件
`edit`	编辑沙箱中的文件（基于 old_str → new_str 的精确替换）

开发流程（沙箱优先策略，来自系统提示词）：

编写脚本 → pip install → 用 bash/read/write/edit 小规模测试
  → 修复错误 → 通过 hf_jobs 大规模启动

GPU 沙箱：需要 CUDA/bf16/模型加载时，创建 t4-small 或更高级 GPU 沙箱测试 GPU 代码路径。

沙箱创建与运行机制

沙箱本质上是一个 HuggingFace Space（私有），通过复制模板 Space 创建，内嵌一个 FastAPI 服务端，Agent 通过 HTTPS API 远程操控。

创建流程（Sandbox.create()，agent/tools/sandbox_client.py:555）：

1. 生成唯一名称：{owner}/sandbox-{8位hex}
2. 生成控制面令牌：sandbox_api_token = secrets.token_urlsafe(32)
3. 调用 HfApi.duplicate_space(from_id="burtenshaw/sandbox", to_id=space_id, hardware=...)
   → 复制模板 Space 到用户命名空间下
4. 调用 HfApi.request_space_hardware(space_id, hardware=...)
   → 请求目标硬件规格（确保不会静默继承模板的 GPU 硬件）
5. 注入 Secrets：HfApi.add_space_secret("SANDBOX_API_TOKEN", sandbox_api_token)
   → 还注入 HF_TOKEN（使沙箱能访问 gated 数据集/模型）
6. 上传 sandbox_server.py + Dockerfile（触发 Space 重建）
7. 轮询等待 Space 进入 RUNNING 状态（超时 600s，每 5s 检查一次）
8. 返回 Sandbox 实例（已连接）

沙箱内部架构：

┌─────────────────────────────────────────────┐
│ HF Space (私有)                              │
│  硬件：cpu-basic / t4-small / a100-large 等  │
│                                              │
│  ┌────────────────────────────────────────┐  │
│  │ Docker 容器                             │  │
│  │ 基于: ghcr.io/astral-sh/uv:python3.12  │  │
│  │ 预装: bash, git, git-lfs, wget, curl,  │  │
│  │       procps, htop, vim, nano, jq,     │  │
│  │       tmux, build-essential,           │  │
│  │       fastapi, uvicorn                 │  │
│  │ 工作目录: /app                          │  │
│  │                                        │  │
│  │ sandbox_server.py (FastAPI)            │  │
│  │   POST /api/bash   → 执行 shell 命令   │  │
│  │   POST /api/read   → 读取文件          │  │
│  │   POST /api/write  → 写入文件（含验证） │  │
│  │   POST /api/edit   → 精确替换编辑      │  │
│  │   POST /api/kill   → 杀死所有进程      │  │
│  │   GET  /api/health → 健康检查          │  │
│  │                                        │  │
│  │ 鉴权: X-Sandbox-Authorization Bearer   │  │
│  │ 输出截断: 25KB (head 25% + tail 75%)   │  │
│  │   溢出部分存入 /tmp/bash_output_*.txt  │  │
│  └────────────────────────────────────────┘  │
└─────────────────────────────────────────────┘
         ↑ HTTPS API 调用
         │
┌────────┴────────┐
│ Sandbox 客户端   │
│ (Agent 进程内)   │
│ base_url:        │
│  https://{slug}.hf.space/api/  │
│ 鉴权头:          │
│  Authorization: Bearer {hf_token}           │
│  X-Sandbox-Authorization: Bearer {api_token}│
└──────────────────┘

关键实现细节：

bash 命令执行（sandbox_client.py:376）：subprocess.Popen(shell=True, start_new_session=True) → 支持超时杀死进程组（os.killpg + SIGKILL）
write 文件验证（sandbox_client.py:438）：写入 .py 文件时自动检查常见错误（缺少 push_to_hub/hub_model_id、无效 kwarg、弃用 API）
edit 精确替换：基于 old_str → new_str 的字符串替换，支持 replace_all 模式
输出截断：bash 输出超过 25KB 时截断（保留头部 25% + 尾部 75%），溢出全文存入 /tmp/ 供 read 工具分段查看
孤儿沙箱清理：创建新沙箱前，删除超过 1 小时未修改的 sandbox-{8hex} 命名 Space，避免资源泄漏
创建串行化：同一 owner 的沙箱创建通过 asyncio.Lock 串行化，避免 HF API 并发问题
取消支持：创建过程中通过 threading.Event 检查取消信号，取消时删除已创建的 Space

代码实现：

agent/tools/sandbox_tool.py：工具入口，Session 绑定 Sandbox 实例
agent/tools/sandbox_client.py：Sandbox 客户端类（create/connect/bash/read/write/edit/delete）
沙箱预热：异步创建 cpu-basic，操作工具等待预热完成
会话结束/页面关闭：通过 sendBeacon 调用 /api/session/{id}/sandbox/teardown 清理

3.3 HF Jobs 云端训练

ML Intern 可以直接提交训练任务到 HuggingFace 云 GPU 集群。

支持的硬件规格：

规格	配置	适用场景
`cpu-basic`	2vCPU/16GB	CPU 预处理
`cpu-upgrade`	8vCPU/32GB	CPU 密集计算
`t4-small`	4vCPU/15GB/GPU 16GB	小模型推理/测试
`t4-medium`	8vCPU/30GB/GPU 16GB	中等模型推理
`a10g-small`	4vCPU/15GB/GPU 24GB	小 GPU 任务
`a10g-large`	12vCPU/46GB/GPU 24GB	中等 GPU 任务
`a10g-largex2`	24vCPU/92GB/GPU 48GB	1-3B 参数训练
`a10g-largex4`	48vCPU/184GB/GPU 96GB	多 GPU 中等模型
`a100-large`	12vCPU/142GB/GPU 80GB	7-13B 参数训练
`a100x4`	48vCPU/568GB/GPU 320GB	30B+ 参数训练
`a100x8`	96vCPU/1136GB/GPU 640GB	70B+ 参数训练
`l4x1`	8vCPU/30GB/GPU 24GB	L4 单卡任务
`l4x4`	48vCPU/186GB/GPU 96GB	L4 多卡任务
`l40sx1`	8vCPU/62GB/GPU 48GB	L40S 单卡任务
`l40sx4`	48vCPU/382GB/GPU 192GB	30B+ 参数训练
`l40sx8`	192vCPU/1534GB/GPU 384GB	大模型训练
`inf2x6`	( Inferentia 专用 )	AWS Inferentia 推理

Jobs 操作：

run / uv：提交即时训练任务
ps：查看运行中的任务
logs：获取任务日志
inspect：查看任务详情
cancel：取消任务
scheduled run/ps/inspect/delete/suspend/resume：管理定时调度任务

预飞检查（提交训练任务前，系统提示词要求 Agent 输出）：

- 参考实现：[基于哪个示例]
- 数据集格式已验证：[通过 hf_inspect_dataset/hub_repo_details 确认的列名]
- push_to_hub=True 且 hub_model_id 已设置
- timeout：[值]（基于：[模型规模] 在 [硬件] 上）
- Trackio 监控已包含并部署到公开 Space

常见错误防护（来自系统提示词）：

默认超时杀任务：训练默认 30min 超时，训练需数小时 → 必须根据模型规模设置合理超时
模型丢失：Job 存储是临时的 → 必须设置 push_to_hub=True + hub_model_id，否则训练完模型永久丢失
批量任务全挂：先提交 1 个验证成功，再提交其余，避免同时失败

代码实现：agent/tools/jobs_tool.py

3.4 论文搜索与阅读（hf_papers）

hf_papers 工具提供 11 种学术文献操作：

操作	功能
`trending`	获取 HF 每日热门论文
`search`	搜索论文（默认 HF，有筛选条件时路由到 S2）
`paper_details`	论文元数据、摘要、AI 摘要、GitHub 链接
`read_paper`	阅读论文指定章节（无 section 返回 TOC；有 section 返回全文）
`citation_graph`	获取论文引用图谱（上游引用 + 下游引用，含影响力和意图标记）
`snippet_search`	跨 12M+ 论文全文段落语义搜索
`recommend`	发现相似论文（单论文或正/负样本）
`find_datasets`	发现论文关联的 HF 数据集
`find_models`	发现论文关联的 HF 模型
`find_collections`	发现包含论文的 HF 合集
`find_all_resources`	并行获取数据集+模型+合集

3.5 数据集审计（hf_inspect_dataset）

在任何 ML 工作之前，Agent 会先审计数据集——绝不假设知道数据长什么样：

检查 schema/列名
各 split 的行数
关键列的值分布
样本行预览
发现问题：类别不平衡、缺失值、异常格式、离群值、重复行等

数据格式要求（来自系统提示词）：

训练方法	必需列
SFT	`messages` / `text` / `prompt`+`completion`
DPO	`prompt` + `chosen` + `rejected`
GRPO	`prompt`

3.6 训练监控（Trackio）

ML Intern 集成了 Trackio 训练监控，自动为每次训练部署公开指标面板。

配置方式（在 TrainingArguments/SFTConfig/DPOConfig/GRPOConfig 中设置）：

report_to="trackio"
run_name="sft_qwen3-4b_lr2e-5_bs128"         # 描述性运行名
project="descriptive-project-name"              # 项目名，分组相关运行
trackio_space_id="<username>/mlintern-<8-char-id>"  # 创建公开面板 Space

告警系统：在每个决策点调用 trackio.alert(title, text, level)：

ERROR：停止并改变方法（发散、NaN、OOM）
WARN：调整超参（过拟合、早停、KL 飙升、奖励坍塌、收敛慢）
INFO：里程碑（训练完成、目标达成、检查点保存）

超参调整驱动（基于告警自动决策）：

发散        → lr × 0.1
过拟合      → weight_decay × 10 或减少容量
早停        → lr × 0.5 或调整调度
高准确率    → 在当前配置附近精炼

代码实现：agent/tools/trackio_seed.py 自动部署 Trackio 面板

3.7 HF 文档与 API 搜索

工具	功能
`explore_hf_docs`	浏览 HF 文档的目录结构
`fetch_hf_docs`	获取具体文档页面内容
`find_hf_api`	搜索 HF OpenAPI 规范，查找准确的 API 端点和参数

系统提示词特别强调：你对 HF 库的知识是过时的。内部的 API 知识会产生错误的 import、错误的参数名、错误的 Trainer 配置。在编写任何 ML 代码前，必须先查阅文档。

3.8 HF 仓库管理

工具	操作	说明
`hf_repo_files`	`list` / `upload` / `download` / `delete`	文件级操作
`hf_repo_git`	`create_repo` / `delete_branch` / `create_pr` / `merge_pr` 等	Git 级操作

3.9 任务规划（plan_tool）

当任务有 3+ 步骤时，Agent 自动使用 plan_tool 跟踪进度：

同一时间只一个任务 in_progress
完成后立即标记 completed
频繁更新，让用户看到进展

3.10 通知推送（notify + Slack）

Agent 可将状态更新推送到 Slack 渠道：

需要审批时通知
遇到错误时通知
完成轮次时通知

4. 使用案例

案例来源说明：以下案例均基于项目源码中的系统提示词（agent/prompts/system_prompt_v3.yaml）、工具实现代码、README 文档和配置文件推导而来，是 Agent 在收到对应用户输入时必然执行的逻辑路径（由系统提示词的强制性规则决定），而非凭空编造。每个案例标注了推导依据。

案例 1：微调 LLaMA 模型

推导依据：系统提示词 v3 的 “default workflow for any ML task” + README.md 的 headless 示例 + jobs_tool.py 的硬件规格 + sandbox_tool.py 的沙箱优先策略

用户输入：

fine-tune LLaMA 3 8B on my dataset "myorg/chat-data" using SFT

Agent 执行流程：

1. research("Literature crawl for SFT fine-tuning. Start from LLaMA 3 paper.
    Crawl citation graph for recent downstream papers. Read methodology sections.
    Extract training recipes + datasets. Find working code with current TRL/Transformers APIs.")

2. hf_inspect_dataset("myorg/chat-data")
   → 确认列名：messages, 格式匹配 SFT 要求

3. explore_hf_docs("trl/SFTTrainer") + fetch_hf_docs
   → 获取当前 SFTConfig 参数

4. github_find_examples("trl sft trainer llama")
   → 找到参考实现脚本

5. write("train_sft.py", <脚本内容>)   # 在沙箱中写脚本
6. bash("pip install transformers trl datasets")  # 安装依赖
7. bash("python train_sft.py --dry-run")  # 小规模测试

8. sandbox_create(hardware="a100-large")  # 创建 GPU 沙箱测试

9. hf_jobs(operation="run", script="train_sft.py",
           hardware="a100-large", timeout=14400,  # 4小时
           ...)

10. [等待训练完成] → hf_jobs(operation="logs") → 检查训练日志

11. 输出：训练完成，模型已推送到 Hub，Trackio 面板 URL

案例 2：研究最新 RLHF 方法并实现 DPO 训练

推导依据：系统提示词 v3 的 “Start from the literature” + papers_tool.py 的 citation_graph/read_paper 操作 + dataset_tools.py 的格式验证

用户输入：

Research the latest RLHF methods and implement DPO training for my reward model

Agent 执行流程：

1. research("Literature crawl for RLHF/DPO. Start from DPO paper (Rafailov 2023).
    Crawl citation graph → find downstream improvements (RDPO, IPO, etc).
    Read methodology sections → extract training recipes.
    Find datasets used for preference data.")

2. hf_papers(operation="citation_graph", paper_id="2310.16948")
   → 获取 DPO 论文引用图谱

3. hf_papers(operation="read_paper", paper_id="...", section=4)
   → 阅读下游论文实验章节

4. hf_inspect_dataset("myorg/preference-data")
   → 确认列名：prompt, chosen, rejected（DPO 格式要求）

5. write("train_dpo.py", ...)  # 编写 DPO 训练脚本
6. [沙箱测试] → [修复错误] → [提交 hf_jobs]
7. [监控 Trackio] → [根据告警调整超参]

案例 3：无头模式自动超参搜索

推导依据：README.md 的 headless 模式示例 + 系统提示词 v3 的 “Autonomous / headless mode” 强制规则（“NEVER respond with only text”、“HYPERPARAMETER TUNING: write a sweep script”）

用户输入（CLI 无头模式）：

ml-intern "Find the best SFT recipe for Qwen3-4B on the Alpaca dataset.
Run a hyperparameter sweep over learning rate and batch size."

Agent 自主执行（无需人工干预）：

1. 文献调研 → 找到 SFT 最佳实践
2. 数据集审计 → 确认 Alpaca 格式
3. 编写超参搜索脚本（而非逐个手调）：
   - 学习率网格：[1e-5, 2e-5, 5e-5]
   - batch size 网格：[16, 32, 64]
4. 先提交 1 个验证成功
5. 再提交其余 8 个组合
6. 持续监控 → 根据 Trackio 告警调整
7. 输出最佳配置 + 模型 Hub URL

案例 4：阅读论文并复现结果

推导依据：papers_tool.py 的全部 11 个操作定义 + 系统提示词 v3 的 “1. Find the landmark paper(s)” 工作流

用户输入：

Read the GRPO paper and reproduce their training setup for my model

Agent 执行流程：

1. hf_papers(operation="search", query="GRPO group relative policy optimization")
2. hf_papers(operation="read_paper", paper_id="...", section=3)  # 方法论
3. hf_papers(operation="read_paper", paper_id="...", section=5)  # 结果
4. hf_papers(operation="find_datasets", paper_id="...")  # 发现使用的数据集
5. github_find_examples("trl grpo trainer")  # 找实现代码
6. fetch_hf_docs("trl/GRPOTrainer")  # 查当前 API
7. [编写脚本 → 测试 → 提交训练]

案例 5：数据集审计与格式转换

推导依据：dataset_tools.py 的 inspect_dataset 实现 + 系统提示词 v3 的 “Data audit” 和 “Dataset format requirements by training method” 规则

用户输入：

I want to fine-tune with DPO but my dataset only has prompt/response pairs

Agent 执行流程：

1. hf_inspect_dataset("myorg/my-dataset")
   → 发现列名：prompt, response（缺少 chosen/rejected）
2. 编写转换脚本：将 prompt/response 对转为 DPO 格式
3. 在沙箱中执行转换
4. 上传新数据集到 HF Hub
5. 验证新格式匹配 DPO 要求

5. 启动流程

5.1 后端启动

入口文件：backend/main.py

app = FastAPI(title="HF Agent", lifespan=lifespan)

启动时的生命周期（lifespan）按以下顺序执行：

加载 .env 环境变量：在导入路由模块前调用 load_dotenv()
启动会话管理器：await session_manager.start()
- 初始化持久化存储（persistence_store）
- 启动通知网关（messaging_gateway）
启动 KPI 定时聚合调度器：kpis_scheduler.start()
注册路由：app.include_router(agent_router) + app.include_router(auth_router)
配置 CORS 中间件：允许 localhost:5173/3000 跨域
挂载静态文件：生产模式下从 static/ 目录提供前端构建产物

关闭时执行：

停止 KPI 调度器
将所有活跃会话刷盘保存并上传
关闭会话管理器

启动命令：

cd backend && uv run uvicorn main:app --host ::1 --port 7860

5.2 前端启动

入口文件：frontend/src/main.tsx → App.tsx

App.tsx 调用 useAuth() 进行非阻塞认证检查
渲染 AppLayout 主布局组件
AppLayout 挂载时执行 LLM 健康检查 (/api/health/llm)
无会话时显示 WelcomeScreen，有会话时渲染聊天界面

启动命令：

cd frontend && npm ci && npm run dev

Vite 开发服务器将 /api 和 /auth 请求代理到 http://localhost:7860。

6. 核心运行逻辑

6.1 请求处理总流程

用户输入
  ↓
前端 useAgentChat Hook
  ↓
SSEChatTransport.sendMessages()  →  POST /api/chat/{session_id}
  ↓
后端 routes/agent.py 路由处理
  ↓
SessionManager 获取/创建 AgentSession
  ↓
process_submission() 进入 Agent 推理循环
  ↓
agent_loop: LLM 调用 → 工具调用 → LLM 调用 → ... → turn_complete
  ↓
事件通过 EventBroadcaster → SSE 流式推送给前端
  ↓
前端 SSE 解析 → 更新 UI 消息列表

6.2 会话管理（SessionManager）

文件：backend/session_manager.py

SessionManager 管理多个并发的 Agent 会话：

属性/限制	值	说明
`MAX_SESSIONS`	200	全局最大并发会话数
`MAX_SESSIONS_PER_USER`	10	每用户最大会话数
`DEFAULT_YOLO_COST_CAP_USD`	5.0	自动审批默认费用上限

会话创建流程（_create_session_sync）：

创建 ToolRouter（注册所有内置工具 + MCP 工具）
深拷贝 Config（使每个会话的模型选择独立）
创建 Session 实例（包含事件队列、上下文管理器、审批状态等）

EventBroadcaster：从 Agent 事件队列读取事件，扇出（fan-out）给所有 SSE 订阅者。

6.3 Agent 推理循环（agent_loop）

文件：agent/core/agent_loop.py

这是整个应用的核心——submission_loop / process_submission 函数实现了一个多轮推理循环：

┌─────────────────────────────────────┐
│         Agent 推理循环              │
│                                     │
│  1. 接收用户输入 / 审批响应          │
│  2. 上下文压缩检查（如需压缩则摘要） │
│  3. 调用 LLM（流式）                │
│  4. 解析 LLM 响应：                 │
│     - 纯文本 → 发送 assistant_chunk │
│     - 工具调用 → 审批决策            │
│       ├─ 无需审批 → 直接执行工具     │
│       ├─ 自动审批（YOLO）→ 执行工具  │
│       └─ 需人工审批 → 发送           │
│          approval_required 事件      │
│  5. 执行工具 → 返回结果             │
│  6. 将工具结果加入上下文             │
│  7. 死循环检测（doom_loop）          │
│  8. 回到步骤 3，直到无更多工具调用   │
│  9. 发送 turn_complete 事件          │
└─────────────────────────────────────┘

关键机制：

LLM 调用（_call_llm_streaming）：通过 litellm.acompletion 流式调用，支持重试（最多 3 次），区分速率限制错误和瞬态错误
上下文压缩（_compact_and_notify）：当上下文使用率超过阈值时，调用 LLM 生成对话摘要以节省 token
审批决策（_approval_decision）：根据工具类型、YOLO 模式、成本上限综合判断是否需要人工审批
思考状态回放：对 Anthropic 模型保留 thinking_blocks / reasoning_content，支持扩展思考
努力级别探测：通过 effort_probe 探测模型支持的最高推理努力级别，失败时自动降级
死循环检测（doom_loop）：检测重复的工具调用模式，注入纠正提示词

6.4 工具系统（ToolRouter）

文件：agent/core/tools.py

ToolRouter 统一管理内置工具和 MCP（Model Context Protocol）外部工具：

内置工具列表（按重要性排序）：

工具名	功能	对应文件
`research`	研究子 Agent（委托给只读工具）	`research_tool.py`
`explore_hf_docs`	浏览 HF 文档结构	`docs_tools.py`
`hf_docs_fetch`	获取 HF 文档内容	`docs_tools.py`
`hf_papers`	论文搜索与阅读	`papers_tool.py`
`web_search`	网页搜索	`web_search_tool.py`
`hf_inspect_dataset`	数据集检查	`dataset_tools.py`
`plan_tool`	任务规划	`plan_tool.py`
`notify`	发送通知	`notify_tool.py`
`hf_jobs`	HF Jobs 管理	`jobs_tool.py`
`hf_repo_files`	HF 仓库文件操作	`hf_repo_files_tool.py`
`hf_repo_git`	HF 仓库 Git 操作	`hf_repo_git_tool.py`
`github_find_examples`	GitHub 搜索示例	`github_find_examples.py`
`github_list_repos`	GitHub 列出仓库	`github_list_repos.py`
`github_read_file`	GitHub 读取文件	`github_read_file.py`
`bash` / `read` / `write` / `edit`	沙箱操作	`sandbox_tool.py`
`sandbox_create`	创建 GPU 沙箱	`sandbox_tool.py`

MCP 工具：默认配置连接 hf-mcp-server（https://huggingface.co/mcp?login），提供额外的 HF Hub 能力。

工具调用流程：

LLM 返回 tool_calls，包含工具名和参数
ToolRouter.call_tool() 查找对应 ToolSpec
内置工具 → 直接调用 handler(arguments)
MCP 工具 → 通过 mcp_client.call_tool() 远程调用
返回 (output_string, success_bool)

6.5 YOLO 模式详解

重要澄清：YOLO 模式不是一种 AI 模型，而是一个自动审批策略开关。名称取自 “You Only Live Once”（你只活一次），含义是"信任 Agent 的判断，不再逐个审批工具调用"。

YOLO 模式的本质：当开启后，Agent 的工具调用不再需要用户逐一确认，而是自动批准执行。这适合用户信任 Agent 判断、希望全自动运行的场景（如无头模式 CLI）。

两种启用方式（agent/core/agent_loop.py:233）：

def _effective_yolo_enabled(session, config):
    return (config and config.yolo_mode) or _session_auto_approval_enabled(session)

启用方式	来源	设置位置
`config.yolo_mode = True`	配置文件	`configs/cli_agent_config.json` 或 CLI `--yolo` 参数
`session.auto_approval_enabled = True`	会话级开关	前端 YoloControl 按钮，可实时切换

费用上限机制（仅 Web 会话级 YOLO）：

session.auto_approval_cost_cap_usd  →  费用上限（默认 $5.00）
session.auto_approval_estimated_spend_usd  →  已花费金额

每次工具调用前：
  ├─ 估算成本（CostEstimate）
  ├─ 计算剩余预算 = cap - spent - reserved
  ├─ 估算成本 > 剩余预算 → 阻止自动审批，返回用户确认
  └─ 估算成本 ≤ 剩余预算 → 自动审批，累加 spent

YOLO 模式的安全边界——以下操作永远不可自动审批：

操作	原因
`hf_jobs` 调度任务（scheduled run）	定时任务具有持续性/无限性，风险不可控
成本超预算的 `sandbox_create` / `hf_jobs run`	防止意外高额费用

代码实现（agent/core/agent_loop.py）：

_effective_yolo_enabled()：综合判断配置级和会话级 YOLO 是否开启
_remaining_budget_after_reservations()：计算扣除预留后的剩余预算
_approval_decision()：最终审批决策函数，综合 YOLO 状态 + 预算 + 操作类型

6.6 审批策略

文件：agent/core/agent_loop.py 中的 _approval_decision 函数

审批决策逻辑（与 YOLO 模式配合）：

基础审批需求（_base_needs_approval）：
  ├─ 参数格式错误 → 跳过审批（后续会报验证错误）
  ├─ sandbox_create 且非 CPU 默认硬件 → 需审批
  ├─ hf_jobs 调度任务（scheduled） → 必须人工审批
  ├─ hf_jobs 即时运行 + CPU 任务 → 取决于 config.confirm_cpu_jobs
  ├─ hf_private_repos 上传文件 → 取决于 config.auto_file_upload
  ├─ hf_repo_files upload/delete → 需审批
  ├─ hf_repo_git 破坏性操作（delete_branch/merge_pr/create_repo/update_repo） → 需审批
  └─ 其他 → 无需审批

最终审批决策（_approval_decision）：
  ├─ 调度任务 → 强制需审批（YOLO 也不可绕过）
  ├─ YOLO 未开启 → 按基础需求决定
  ├─ YOLO 已开启：
  │   ├─ 有预算目标的工具（sandbox_create / hf_jobs run）→ 估算成本
  │   │   ├─ 成本超预算 → 阻止自动审批，返回用户确认
  │   │   └─ 成本在预算内 → 自动审批，累加已花费
  │   └─ 其他工具 → 自动审批
  └─ 返回 ApprovalDecision(requires_approval, auto_approved, estimated_cost_usd, remaining_cap_usd)

6.7 上下文管理（ContextManager）

文件：agent/context_manager/manager.py

上下文管理器负责：

维护对话历史消息列表
计算 token 使用量
当使用率超过阈值（约 170k tokens）时，调用 LLM 生成摘要压缩上下文
支持从浏览器缓存消息恢复会话（使用 _RESTORE_PROMPT 生成第一人称自述笔记，保留工具调用轨迹、文件路径、关键决策和后续计划）

6.8 系统提示词设计

文件：agent/prompts/system_prompt_v3.yaml

系统提示词是 ML Intern 智能行为的核心驱动，包含：

身份定义：ML 工程助手，完全自主——研究、验证、实现、交付，不请求不必要确认
知识过时警告：明确声明对 HF 库的 API 知识过时，必须先查文档再写代码
默认工作流：找论文 → 爬引用 → 读方法论 → 提取配方 → 验证数据集
常见错误防护：列举 Agent 在无研究时必犯的错误（错误 import、错误参数、错误数据格式、超时杀任务、模型丢失、批量全挂、静默替换数据集）
代码编写规范：训练前必查文档、验证数据集、验证模型；必须设置 logging；数据格式要求
Trackio 集成：监控配置、告警规则、超参调整驱动
错误恢复策略：OOM 调 batch size + gradient checkpointing → 升级 GPU；禁止改变用户请求的方法
无头模式规则：每轮必须包含工具调用；持续工作直到时间用完；超参搜索用脚本而非手调
Hub Kernel 优先：用 kernels 库的预编译注意力内核，而非 pip install flash-attn 编译

7. 前端运行逻辑

7.1 整体架构

App.tsx
  └─ AppLayout.tsx
       ├─ SessionSidebar（左侧会话列表）
       ├─ SessionChat × N（中间聊天区域，每会话一个实例）
       └─ CodePanel（右侧代码/输出面板）

UI 特性：

多会话标签式管理（最多 10 个/用户）
工具调用展示（名称 + 参数 + 输出 + 状态）
审批交互（批准/拒绝/编辑脚本）
YOLO 模式开关 + 费用上限设置
Research 子 Agent 步骤展示
Trackio/Jobs URL 跳转
暗色/亮色主题切换
响应式布局（桌面/移动端）

7.2 SSE 通信机制

文件：frontend/src/lib/sse-chat-transport.ts

前端通过 SSEChatTransport（实现 Vercel AI SDK 的 ChatTransport 接口）与后端通信：

发送消息：sendMessages() → POST /api/chat/{session_id}
SSE 解析：createSSEParserStream() 将 SSE 文本流解析为 AgentEvent 对象
事件转换：createEventToChunkStream() 将 AgentEvent 转为 UIMessageChunk

后端事件类型 → 前端处理：

事件类型	处理方式
`processing`	标记处理中，创建消息步骤
`assistant_chunk`	流式追加文本内容
`assistant_stream_end`	结束文本部分
`tool_call`	显示工具调用（名称+参数）
`tool_output`	显示工具执行结果
`approval_required`	显示审批请求，等待用户决策
`tool_state_change`	更新工具状态（running/rejected/cancelled/billing_required）
`turn_complete`	标记当前轮次完成
`error`	显示错误信息
`compacted`	通知上下文已压缩
`plan_update`	更新任务计划面板
`tool_log`	工具日志（研究子 Agent 步骤）

7.3 核心 Hook：useAgentChat

文件：frontend/src/hooks/useAgentChat.ts

每个会话实例化一个 useAgentChat，职责：

通过 useChat（Vercel AI SDK）管理聊天状态
通过 SSEChatTransport 与后端通信
通过 SideChannelCallbacks 处理非聊天事件（审批、计划更新、工具日志等）
管理 Research 子 Agent 的状态（步骤/统计/标签）
断线重连：页面刷新后通过 reconnectToStream() 订阅正在进行的事件流

7.4 状态管理

使用 Zustand 进行状态管理：

Store	职责
`agentStore`	Agent 全局状态（连接、错误、工具输出、Research Agent、Job URL、Trackio 面板）
`sessionStore`	会话列表、活跃会话、过期标记
`layoutStore`	布局状态（侧栏开关、右面板开关/宽度、主题模式）

8. 认证流程

文件：backend/routes/auth.py

采用 OAuth 2.0 授权码模式，以 Hugging Face 作为身份提供商：

1. 用户点击登录 → GET /auth/login
2. 重定向到 HF OAuth 授权页
3. 用户授权 → HF 回调 /auth/callback?code=xxx&state=yyy
4. 后端用 code 换取 access_token
5. 将 access_token 设为 HttpOnly Cookie（7 天有效期）
6. 重定向回前端首页

OAuth 权限范围：openid profile read-repos write-repos contribute-repos manage-repos inference-api jobs write-discussions

开发模式下（未设置 OAUTH_CLIENT_ID）自动跳过认证。

9. 模型切换与配额

9.1 可用模型

模型	层级	提供商	说明
Kimi K2.6	免费	HuggingFace	推荐免费选项
Claude Opus 4.6	付费	Anthropic	推荐付费选项
GPT-5.5	付费	OpenAI	HF 组织成员可用
MiniMax M2.7	免费	HuggingFace	免费备选
GLM 5.1	免费	HuggingFace	免费备选
DeepSeek V4 Pro	免费	HuggingFace	免费备选

9.2 配额限制

付费模型（Claude、GPT-5.5）仅对 HF 组织成员开放
普通用户选择付费模型时，自动降级为免费模型
付费模型有每日使用配额，在首次提交消息时扣减

9.3 推理努力级别

默认 max——宁可多花 token 思考，也不交付错误的 ML 配方。首次使用新模型时自动探测支持的最高级别并缓存。

10. 通知系统

文件：agent/messaging/gateway.py

NotificationGateway 支持将 Agent 事件推送到外部渠道（当前支持 Slack）：

异步队列 + Worker 协程处理通知发送
支持重试（延迟 1s → 2s → 4s）
区分可重试错误和不可重试错误
自动事件类型：approval_required、error、turn_complete

Slack 配置：

SLACK_BOT_TOKEN=xoxb-...
SLACK_CHANNEL_ID=C...

11. 会话持久化与轨迹共享

每个会话的事件轨迹自动保存到本地 session_logs/ 目录
支持上传到 HuggingFace 数据集（smolagents/ml-intern-sessions）
用户个人轨迹上传到私有数据集 {hf_user}/ml-intern-sessions
轨迹格式为 Claude Code JSONL，HF Agent Trace Viewer 可直接渲染
心跳机制：长运行轮次每 60 秒自动保存一次，防止 OOM 丢失数据
服务关闭时对所有活跃会话执行最终刷盘

轨迹共享（CLI 命令）：

/share-traces            # 查看当前可见性 + 数据集 URL
/share-traces public     # 发布（任何人可查看）
/share-traces private    # 锁回私有

12. CLI 模式

文件：agent/main.py

除了 Web 界面，项目还支持 CLI 交互模式：

ml-intern                    # 交互模式
ml-intern "fine-tune llama on my dataset"  # 无头模式（自动审批）
ml-intern --model anthropic/claude-opus-4-6 "your prompt"  # 指定模型
ml-intern --max-iterations 100 "your prompt"  # 限制迭代次数

CLI 模式的核心逻辑与 Web 模式相同（共用 agent_loop），区别在于：

使用 prompt_toolkit 进行终端输入
使用 rich 库进行终端美化输出（包含 shimmer 动画思考指示器）
支持命令行斜杠命令：
- /model — 列出/切换模型
- /effort — 调整推理努力级别
- /yolo — 切换自动审批模式
- /share-traces — 管理轨迹共享
HF Token 通过交互式提示获取并保存到 ~/.cache/huggingface/token

无头模式特殊规则（来自系统提示词）：

每轮响应必须包含至少一个工具调用（纯文本响应会永久终止循环）
持续工作直到时间用完，不问"要继续吗？"
工作流是循环而非清单：研究 → 实现 → 训练 → 评估 → 保存 → 改进 → 回到研究
超参调整用搜索脚本而非逐个手调

13. 安全与错误恢复

13.1 错误恢复策略

错误类型	恢复策略	禁止操作
OOM	减 batch size + 增 gradient_accumulation_steps → 开 gradient_checkpointing → 升级 GPU	禁止切换训练方法（如 SFT→LoRA）、禁止减 max_length
API/import 错误	查文档获取正确 API	禁止猜测参数
速率限制	自动重试（30s → 60s 退避）	—
训练发散	lr × 0.1	禁止静默切换数据集/模型
工具重复失败	停止并尝试不同方法	禁止重试相同操作

13.2 Hub Kernel 策略

禁止 pip install flash-attn 编译安装（耗时数小时且常失败），改用 HF Hub 预编译内核：

AutoModelForCausalLM.from_pretrained(..., attn_implementation="kernels-community/flash-attn2")
# 或 TRL CLI: --attn_implementation kernels-community/flash-attn2

14. 关键代码索引

功能	文件	关键函数/类
后端入口	`backend/main.py:66`	`app = FastAPI(lifespan=lifespan)`
Agent 路由	`backend/routes/agent.py:43`	`router = APIRouter(prefix="/api")`
会话管理	`backend/session_manager.py:122`	`class SessionManager`
事件广播	`backend/session_manager.py:44`	`class EventBroadcaster`
Agent 循环	`agent/core/agent_loop.py`	`submission_loop` / `process_submission`
LLM 流式调用	`agent/core/agent_loop.py:728`	`_call_llm_streaming`
审批决策	`agent/core/agent_loop.py:262`	`_approval_decision`
工具路由	`agent/core/tools.py:128`	`class ToolRouter`
研究子 Agent	`agent/tools/research_tool.py`	`research_handler`
沙箱工具	`agent/tools/sandbox_tool.py`	`get_sandbox_tools`
Jobs 工具	`agent/tools/jobs_tool.py`	`hf_jobs_handler`
会话状态	`agent/core/session.py:72`	`class Session`
配置管理	`agent/config.py:23`	`class Config` / `load_config`
上下文管理	`agent/context_manager/manager.py`	`class ContextManager`
系统提示词	`agent/prompts/system_prompt_v3.yaml`	V3 版提示词
SSE 传输	`frontend/src/lib/sse-chat-transport.ts:331`	`class SSEChatTransport`
聊天 Hook	`frontend/src/hooks/useAgentChat.ts:32`	`useAgentChat`
主布局	`frontend/src/components/Layout/AppLayout.tsx:32`	`AppLayout`
OAuth 认证	`backend/routes/auth.py:17`	`router = APIRouter(prefix="/auth")`
通知网关	`agent/messaging/gateway.py:24`	`class NotificationGateway`
死循环检测	`agent/core/doom_loop.py`	`check_for_doom_loop`
Trackio 部署	`agent/tools/trackio_seed.py`	`ensure_trackio_dashboard`
前端配置	`configs/frontend_agent_config.json`	MCP 服务器 + 模型配置

AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

2026年温州GEO优化趋势：哪家服务商更受青睐？

在2026年的温州GEO优化市场中，方舟永道凭借其自研的GEO系统和丰富的实战经验，成为众多B2B企业的首选服务商。无论是企业级AI数字资产重构、核心商业场景逆向解析、高权重信源矩阵自动化投喂、动态GRO防守还是流量钩子植入，方舟永道都提供了全面且高效的解决方案。相比之下，其他服务商虽然也在努力追赶，但在深度业务理解、定制化能力和整体覆盖面上仍存在差距。因此，对于希望在AI时代获得竞争优势的企业来