huggingface/ml-intern
GitHub: huggingface/ml-intern
一个基于 LLM 的自主 ML 工程智能体，能够端到端完成从论文研读、模型训练到发布的全流程任务。
Stars: 1509 | Forks: 157
# ML 实习生
一个能够使用 Hugging Face 生态系统自主研究、编写和发布高质量机器学习相关代码的 ML 实习生——可以深度访问文档、论文、数据集和云计算资源。
## 快速开始
### 安装
```
git clone git@github.com:huggingface/ml-intern.git
cd ml-intern
uv sync
uv tool install -e .
```
#### 搞定。现在 `ml-intern` 可以在任何目录下运行：
```
ml-intern
```
在项目根目录下创建一个 `.env` 文件（或者在 shell 中导出这些变量）：
```
ANTHROPIC_API_KEY=
# if using anthropic models
HF_TOKEN=
GITHUB_TOKEN=
```
如果没有设置 `HF_TOKEN`，CLI 会在首次启动时提示你粘贴一个。要获取 GITHUB_TOKEN，请遵循[此处](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)的教程。
### 使用方法
**交互模式**（启动一个聊天会话）：
```
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"
ml-intern --no-stream "your prompt"
```
## 架构
### 组件概览
```
┌─────────────────────────────────────────────────────────────┐
│ User/CLI │
└────────────┬─────────────────────────────────────┬──────────┘
│ Operations │ Events
↓ (user_input, exec_approval, ↑
submission_queue interrupt, compact, ...) event_queue
│ │
↓ │
┌────────────────────────────────────────────────────┐ │
│ submission_loop (agent_loop.py) │ │
│ ┌──────────────────────────────────────────────┐ │ │
│ │ 1. Receive Operation from queue │ │ │
│ │ 2. Route to handler (run_agent/compact/...) │ │ │
│ └──────────────────────────────────────────────┘ │ │
│ ↓ │ │
│ ┌──────────────────────────────────────────────┐ │ │
│ │ Handlers.run_agent() │ ├──┤
│ │ │ │ │
│ │ ┌────────────────────────────────────────┐ │ │ │
│ │ │ Agentic Loop (max 300 iterations) │ │ │ │
│ │ │ │ │ │ │
│ │ │ ┌──────────────────────────────────┐ │ │ │ │
│ │ │ │ Session │ │ │ │ │
│ │ │ │ ┌────────────────────────────┐ │ │ │ │ │
│ │ │ │ │ ContextManager │ │ │ │ │ │
│ │ │ │ │ • Message history │ │ │ │ │ │
│ │ │ │ │ (litellm.Message[]) │ │ │ │ │ │
│ │ │ │ │ • Auto-compaction (170k) │ │ │ │ │ │
│ │ │ │ │ • Session upload to HF │ │ │ │ │ │
│ │ │ │ └────────────────────────────┘ │ │ │ │ │
│ │ │ │ │ │ │ │ │
│ │ │ │ ┌────────────────────────────┐ │ │ │ │ │
│ │ │ │ │ ToolRouter │ │ │ │ │ │
│ │ │ │ │ ├─ HF docs & research │ │ │ │ │ │
│ │ │ │ │ ├─ HF repos, datasets, │ │ │ │ │ │
│ │ │ │ │ │ jobs, papers │ │ │ │ │ │
│ │ │ │ │ ├─ GitHub code search │ │ │ │ │ │
│ │ │ │ │ ├─ Sandbox & local tools │ │ │ │ │ │
│ │ │ │ │ ├─ Planning │ │ │ │ │ │
│ │ │ │ │ └─ MCP server tools │ │ │ │ │ │
│ │ │ │ └────────────────────────────┘ │ │ │ │ │
│ │ │ └──────────────────────────────────┘ │ │ │ │
│ │ │ │ │ │ │
│ │ │ ┌──────────────────────────────────┐ │ │ │ │
│ │ │ │ Doom Loop Detector │ │ │ │ │
│ │ │ │ • Detects repeated tool patterns │ │ │ │ │
│ │ │ │ • Injects corrective prompts │ │ │ │ │
│ │ │ └──────────────────────────────────┘ │ │ │ │
│ │ │ │ │ │ │
│ │ │ Loop: │ │ │ │
│ │ │ 1. LLM call (litellm.acompletion) │ │ │ │
│ │ │ ↓ │ │ │ │
│ │ │ 2. Parse tool_calls[] │ │ │ │
│ │ │ ↓ │ │ │ │
│ │ │ 3. Approval check │ │ │ │
│ │ │ (jobs, sandbox, destructive ops) │ │ │ │
│ │ │ ↓ │ │ │ │
│ │ │ 4. Execute via ToolRouter │ │ │ │
│ │ │ ↓ │ │ │ │
│ │ │ 5. Add results to ContextManager │ │ │ │
│ │ │ ↓ │ │ │ │
│ │ │ 6. Repeat if tool_calls exist │ │ │ │
│ │ └────────────────────────────────────────┘ │ │ │
│ └──────────────────────────────────────────────┘ │ │
└────────────────────────────────────────────────────┴──┘
```
### 智能体循环流程
```
User Message
↓
[Add to ContextManager]
↓
╔═══════════════════════════════════════════╗
║ Iteration Loop (max 300) ║
║ ║
║ Get messages + tool specs ║
║ ↓ ║
║ litellm.acompletion() ║
║ ↓ ║
║ Has tool_calls? ──No──> Done ║
║ │ ║
║ Yes ║
║ ↓ ║
║ Add assistant msg (with tool_calls) ║
║ ↓ ║
║ Doom loop check ║
║ ↓ ║
║ For each tool_call: ║
║ • Needs approval? ──Yes──> Wait for ║
║ │ user confirm ║
║ No ║
║ ↓ ║
║ • ToolRouter.execute_tool() ║
║ • Add result to ContextManager ║
║ ↓ ║
║ Continue loop ─────────────────┐ ║
║ ↑ │ ║
║ └───────────────────────┘ ║
╚═══════════════════════════════════════════╝
```
## 事件
智能体通过 `event_queue` 发出以下事件：
- `processing` - 开始处理用户输入
- `ready` - 智能体已准备好接收输入
- `assistant_chunk` - 流式 token 块
- `assistant_message` - 完整的 LLM 响应文本
- `assistant_stream_end` - token 流结束
- `tool_call` - 正在调用工具及其参数
- `tool_output` - 工具执行结果
- `tool_log` - 工具的信息日志消息
- `tool_state_change` - 工具执行状态转换
- `approval_required` - 请求用户批准敏感操作
- `turn_complete` - 智能体处理完成
- `error` - 处理过程中发生错误
- `interrupted` - 智能体被中断
- `compacted` - 上下文已被压缩
- `undo_complete` - 撤销操作已完成
- `shutdown` - 智能体正在关闭
## 开发
### 添加内置工具
编辑 `agent/core/tools.py`：
```
def create_builtin_tools() -> list[ToolSpec]:
return [
ToolSpec(
name="your_tool",
description="What your tool does",
parameters={
"type": "object",
"properties": {
"param": {"type": "string", "description": "Parameter description"}
},
"required": ["param"]
},
handler=your_async_handler
),
# ... existing tools
]
```
### 添加 MCP 服务器
编辑 `configs/main_agent_config.json`：
```
{
"model_name": "anthropic/claude-sonnet-4-5-20250929",
"mcpServers": {
"your-server-name": {
"transport": "http",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer ${YOUR_TOKEN}"
}
}
}
}
```
注意：像 `${YOUR_TOKEN}` 这样的环境变量会自动从 `.env` 中替换。标签：AI代理, AI研究员, AI编程助手, AI自动化, Anthropic Claude, Apex, DLL 劫持, DNS解析, GitHub自动化, Hugging Face, MLOps, Python, PyTorch, Smolagents, 人工智能, 大语言模型, 开源项目, 数据科学, 文献阅读, 无后门, 机器学习, 模型微调, 模型训练, 模型部署, 深度学习, 用户模式Hook绕过, 研发效能, 自主代理, 自动化编程, 计算机视觉, 资源验证, 逆向工具