上周刷 GitHub Trending 的时候注意到一个项目——HuggingFace 出的 ml-intern，一天涨了 1200 多颗星。名字起得挺有意思，"ML 实习生"，定位是帮你读论文、找数据集、训模型、提交代码的 AI Agent。

我花了一个周末把它跑通了，写下这篇实测记录。

ml-intern 能干啥

ml-intern 是一个命令行工具。你给它一句话描述任务，它会自己去做：

• 查 HuggingFace 上的文档和论文
• 搜 GitHub 上的相关代码
• 找合适的数据集
• 写训练脚本
• 提交训练任务到 HuggingFace 云计算
• 把模型传到 HuggingFace Hub

整个过程不需要你手动写代码。它也支持交互模式，你可以一步步指导它。

安装

前提：Python 3.10+，装了 uv。没装 uv 的话先 pip install uv。

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

装完之后，终端里就有了 ml-intern 命令。

配置 API Key

在项目根目录建一个 .env 文件：

# 底层大模型选 Anthropic 或 OpenAI，填一个就行
ANTHROPIC_API_KEY=sk-ant-xxxx
# OPENAI_API_KEY=sk-xxxx

# HuggingFace Token（必填）
HF_TOKEN=hf_xxxx

# GitHub Token（可选，用来搜代码）
GITHUB_TOKEN=ghp_xxxx

踩坑提醒： HF_TOKEN 需要有 write 权限。去 huggingface.co/settings/tokens 生成时，记得勾 "Write" scope，不然后面传模型会报 403。这个错误信息不太明显，排查了半小时才发现。

不填 HF_TOKEN 的话，第一次启动时会提示你手动粘贴。

两种使用方式

交互模式

直接敲 ml-intern，进入对话界面：

$ ml-intern
> 帮我找一个中文情感分析的数据集，用 BERT 微调，训练 3 个 epoch

Agent 会一步步执行。涉及云计算资源的操作（比如提交训练任务）会先问你要不要批准。

单次模式

一行命令搞定，适合写到脚本里：

ml-intern "fine-tune llama-3.2-1b on imdb sentiment dataset, push to my hub"

加 --model 切换底层模型：

ml-intern --model openai/gpt-5.5 "your prompt"
ml-intern --model anthropic/claude-opus-4-6 "your prompt"

--max-iterations 控制最大迭代次数，默认 300。简单任务设成 30 就够了，省 token：

ml-intern --max-iterations 30 "search for latest text classification papers"

内置工具一览

ml-intern 不是只会调 API 的壳子。它内置了一套 ML 工作流的工具链：

文档和研究

直接查 transformers、datasets、accelerate 等库的文档；从 HuggingFace Papers 和 arXiv 搜论文。

资源管理

数据集搜索和下载、模型搜索和加载、训练任务提交到 HuggingFace Spaces 或 Endpoints。

代码执行

GitHub 代码搜索、本地沙箱执行（隔离环境跑代码，不会弄乱你的机器）。

MCP 服务器扩展

可以接入外部 MCP 服务器。在 configs/cli_agent_config.json 里配：

{
  "model_name": "anthropic/claude-sonnet-4-5-20250929",
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-filesystem"]
    }
  }
}

配完重启就生效。MCP 工具会自动注册到 Agent 的工具列表里。

实测：从零到模型上线

我给它一个完整任务：

用 distilbert-base-uncased 在 ag_news 数据集上微调一个新闻分类模型，
训练 2 个 epoch，batch size 16，学习率 2e-5。
训完推到我的 HuggingFace Hub。

它实际跑了这些步骤：

1. 查了 HuggingFace 文档，确认 distilbert-base-uncased 的 tokenizer 配置
2. 检查了 ag_news 数据集结构（4 个类别：World、Sports、Business、Sci/Tech）
3. 写了一份训练脚本，用 Trainer API
4. 先在本地沙箱跑了数据预处理代码，确认没问题
5. 提交训练任务
6. 训练完成后把模型推到 Hub

全程 12 分钟。其中 LLM 调用大约 2 分钟，剩下是训练时间。

最终准确率 94.2%，ag_news 上这个数字在正常范围内。

踩坑记录

上下文窗口爆了

ml-intern 有自动压缩机制——消息历史到 170k token 时触发压缩。但如果你的任务涉及大量代码输出，一两轮就可能接近上限。

我的做法：用 --max-iterations 30 限制迭代次数，或者把复杂任务拆成几个小任务分别跑。

Doom Loop 问题

有次让它调试一个报错，它陷入了死循环——改代码，报错，改回去，又报错。项目内置了 Doom Loop Detector，检测到重复的工具调用模式后会注入纠正提示，让 Agent 换个思路。

这个检测机制大部分时候有效。但偶尔会误判：正常的多次文件读写有时也被标记成循环。碰到这种情况，手动中断后换个提示词重新跑就行。

headless 模式的账单风险

涉及云计算（训练任务、Spaces）的操作在交互模式下需要手动批准。但 headless 模式下自动批准所有操作。

如果你用 headless 模式跑任务，注意你的 HuggingFace 账户余额。我有一次忘了设 --max-iterations，Agent 跑了 40 多轮，提交了好几个训练任务，费用不少。

自定义工具

在 agent/core/tools.py 里加：

from agent.core.tool_router import ToolSpec

async def query_internal_db(query: str) -> str:
    """查询内部数据库"""
    result = await db.execute(query)
    return str(result)

def create_builtin_tools() -> list[ToolSpec]:
    return [
        ToolSpec(
            name="query_db",
            description="查询内部 PostgreSQL 数据库",
            parameters={
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "SQL 查询语句"
                    }
                },
                "required": ["query"]
            },
            handler=query_internal_db
        ),
        # ... 保留其他内置工具
    ]

工具定义用的是标准 JSON Schema，跟 OpenAI function calling 格式一样，迁移成本低。

和 Claude Code 的区别

定位不同。Claude Code 是通用编程 Agent，什么代码都能写。ml-intern 专门针对 ML 工作流——内置了论文搜索、数据集查找、模型上传、训练任务提交这些 HuggingFace 生态的工具，Claude Code 做不到这些，除非你自己接 MCP。

如果你日常就是训模型、跑实验，ml-intern 比通用 Agent 更顺手。如果你写 Web 应用或者系统工具，Claude Code 更合适。

两者不冲突。你可以在 Claude Code 里通过 MCP 接 HuggingFace，也可以在 ml-intern 里通过 MCP 接其他服务。

适合谁用

ML 研究员和工程师，日常要找论文、跑实验的，用起来会省不少时间。想快速验证一个想法，不想从头写训练脚本的，也合适。

不太适合的情况：需要精细控制训练每个环节的项目（还是自己写代码靠谱），以及预算紧张的个人用户（底层 LLM 调用加云训练，费用累积不少）。

项目地址：https://github.com/huggingface/ml-intern