ML Intern: Hugging Face가 공개한, 논문을 읽고 모델을 학습하며 코드를 배포하는 오픈소스 ML 엔지니어 에이전트

9bow · 5월 14, 2026, 12:30오후

ML Intern 소개

ML Intern은 Hugging Face가 공개한 오픈소스 ML 엔지니어 에이전트로, 사용자가 자연어로 의뢰한 ML 과제를 받아 자율적으로 문헌 조사, 데이터셋 탐색, 코드 작성, 학습 실행, 모델 배포까지 수행하도록 설계되어 있습니다. 단순히 LLM에 코딩을 시키는 수준이 아니라, Hugging Face 생태계의 문서(docs), 모델(repos), 데이터셋(datasets), 작업(jobs), 논문(papers)에 깊이 접근할 수 있는 도구들을 내장해 두어, "Hugging Face 안의 ML 인턴"처럼 동작하는 것이 핵심 차별점입니다. 특히, Hugging Face의 smolagents 팀이 직접 관리하는 프로젝트라는 점에서도 신뢰성을 확보하고 있습니다.

ML Intern 프로젝트는 그간 우리 PyTorchKR 커뮤니티에서도 자주 다뤄온 "자율 ML 연구·학습" 흐름의 연장선에 있습니다. 같은 Hugging Face 생태계에서 시작된 smolagents 라이브러리가 LLM 기반 에이전트의 기초 구성 요소를 제공한다면, ml-intern은 그 위에 "ML 엔지니어가 일상적으로 하는 일"이라는 명확한 응용 영역을 정의하고 그에 필요한 도구·UX·실행 인프라를 함께 묶어 둔 형태입니다. 사용자는 ml-intern "내 데이터셋으로 LLaMA를 파인튜닝해줘" 같은 한 줄 명령으로 작업을 시작할 수 있고, 에이전트는 그 순간부터 도구를 선택하고 실행하며 결과를 피드백받는 루프를 자동으로 돕니다.

ml-intern은 또한 모델 종속성이 적은 설계를 따릅니다. LiteLLM을 통해 Anthropic Claude, OpenAI GPT 같은 상용 모델뿐 아니라 Ollama, vLLM, LM Studio, llama.cpp 같은 로컬 추론 백엔드를 그대로 사용할 수 있고, MCP(Model Context Protocol) 서버까지 도구로 연결할 수 있습니다. Apache-2.0 라이선스로 공개되어 있어 개인 학습, 사내 연구, 추가 도구 통합 등 다양한 맥락에서 자유롭게 활용할 수 있습니다.

ML Intern 의 핵심 기능

ml-intern은 CLI 한 줄로 동작하지만, 그 뒤에는 Hugging Face의 다양한 자산과 클라우드 컴퓨트가 도구로 연결되어 있습니다. 주요 기능은 다음과 같습니다:

Hugging Face 생태계 도구 통합: HF Docs와 Papers를 검색해 근거를 모으고, HF Repos·Datasets에서 모델과 데이터셋을 탐색하며, HF Jobs로 GPU 학습 작업을 실제로 실행할 수 있습니다.
GitHub 코드 검색: 작업 흐름이 필요하면 GitHub의 코드와 저장소를 직접 검색해 참고 구현을 가져옵니다.
로컬·샌드박스 실행 도구: 기본은 사용자 로컬 파일시스템에서 bash, read, write, edit 도구를 실행하며, --sandbox-tools 옵션을 켜면 격리된 HF Space 샌드박스 안에서 코드와 학습 스크립트를 실험할 수 있습니다.
MCP 서버 연결: configs/cli_agent_config.json에 MCP 서버를 등록해 두면 회사 내부 도구나 외부 서비스를 그대로 에이전트의 도구로 노출할 수 있습니다.
세션 트레이스 공유: 모든 세션은 Claude Code JSONL 형식으로 사용자의 비공개 Hugging Face 데이터셋({username}/ml-intern-sessions)에 자동 업로드되어, HF Agent Trace Viewer로 턴·도구 호출·모델 응답을 직접 열람할 수 있습니다.
알림 게이트웨이(Slack): CLI 세션에서 승인이 필요한 시점, 오류 발생, 턴 종료 등을 Slack 채널로 알림 보낼 수 있습니다(현재는 일방향 알림 전용).

ML Intern의 에이전틱 루프 구조

ml-intern은 README에 명확하게 그려진 두 단계 구조를 통해 안정적인 자율 실행을 목표로 합니다. 외곽에는 사용자 입력과 이벤트를 관리하는 submission_loop가 있고, 그 안에서 실제 LLM 호출과 도구 실행을 담당하는 에이전틱 루프(Agentic Loop)가 최대 300회 반복됩니다.

사용자 메시지
     ↓
[ContextManager 에 메시지 추가]
     ↓
     ╔═══════════════════════════════════════════╗
     ║      반복 루프 (최대 300회)               ║
     ║                                           ║
     ║  메시지 + 도구 스펙 가져오기              ║
     ║         ↓                                 ║
     ║  litellm.acompletion()                    ║
     ║         ↓                                 ║
     ║  tool_calls 가 있는가? ──아니오──> 종료   ║
     ║         │                                 ║
     ║        예                                 ║
     ║         ↓                                 ║
     ║  assistant 메시지 추가 (tool_calls 포함)  ║
     ║         ↓                                 ║
     ║  Doom Loop Detector 체크                  ║
     ║         ↓                                 ║
     ║  각 tool_call 마다:                       ║
     ║    • 승인 필요? ──예──> 사용자 확인 대기  ║
     ║    │                                     ║
     ║    아니오                                 ║
     ║    ↓                                      ║
     ║    • ToolRouter.execute_tool()            ║
     ║    • 결과를 ContextManager 에 추가        ║
     ║         ↓                                 ║
     ║  루프 계속 ─────────────────┐             ║
     ║         ↑                   │             ║
     ║         └───────────────────┘             ║
     ╚═══════════════════════════════════════════╝

이 구조에서 흥미로운 부분은 두 가지입니다. 하나는 ContextManager가 약 170k 토큰 지점에서 자동 압축(auto-compaction)을 수행하면서 메시지 히스토리를 관리하고, 동시에 세션을 HF Hub로 업로드한다는 점입니다. 다른 하나는 Doom Loop Detector가 반복되는 도구 호출 패턴을 감지해 보정용 프롬프트를 주입해, 에이전트가 같은 도구를 무한히 반복하며 길을 잃는 흔한 실패 모드를 줄여 준다는 점입니다. ToolRouter는 HF 문서·연구, HF Repos·Datasets·Jobs·Papers, GitHub 코드 검색, 샌드박스/로컬 도구, 플래닝, MCP 서버 도구를 한 곳에서 라우팅합니다.

또한 에이전트는 processing, assistant_chunk, tool_call, tool_output, tool_state_change, approval_required, turn_complete, error, interrupted, compacted, undo_complete, shutdown 같은 이벤트를 event_queue로 흘려보냅니다. CLI는 이 이벤트를 받아 스트리밍 출력, 승인 프롬프트, 알림 전송 등을 수행하므로, 외부 UI를 새로 붙이거나 Slack/웹훅 같은 통합을 만드는 일이 비교적 수월합니다.

ML Intern 설치 및 사용법

ML Intern 설치는 uv를 활용한 한 줄 흐름으로 정리되어 있습니다. 저장소를 클론한 뒤 의존성을 동기화하고 ml-intern 도구를 PATH에 노출시키면 어느 디렉토리에서나 호출할 수 있습니다.

# 1) 저장소 복제 및 의존성 설치
git clone git@github.com:huggingface/ml-intern.git
cd ml-intern
uv sync
uv tool install -e .

# 2) 이후 어느 위치에서나 호출 가능
ml-intern

프로젝트 루트에 .env 파일을 두고 키 값을 채워 줍니다. 사용하려는 백엔드에 따라 필요한 항목만 채우면 됩니다.

ANTHROPIC_API_KEY=<your-anthropic-api-key>   # Anthropic 모델 사용 시
OPENAI_API_KEY=<your-openai-api-key>         # OpenAI 모델 사용 시
LOCAL_LLM_BASE_URL=http://localhost:8000     # 로컬 모델 공통 폴백
LOCAL_LLM_API_KEY=<optional-local-api-key>   # 로컬 모델 공통 키(선택)
HF_TOKEN=<your-hugging-face-token>
GITHUB_TOKEN=<github-personal-access-token>

대화형 모드는 ml-intern, 헤드리스 모드는 ml-intern "fine-tune llama on my dataset"처럼 프롬프트를 그대로 인자로 넘기는 식입니다. 모델은 --model 플래그로 자유롭게 바꿀 수 있고, 인터랙티브 모드 안에서는 /model 슬래시 명령으로 전환합니다.

ml-intern --model anthropic/claude-opus-4-7 "your prompt"      # ANTHROPIC_API_KEY 필요
ml-intern --model openai/gpt-5.5 "your prompt"                  # OPENAI_API_KEY 필요
ml-intern --model ollama/llama3.1:8b "your prompt"
ml-intern --model vllm/meta-llama/Llama-3.1-8B-Instruct "your prompt"
ml-intern --sandbox-tools "test this training script in a GPU sandbox"
ml-intern --max-iterations 100 "your prompt"

로컬 모델은 OpenAI 호환 HTTP 엔드포인트를 LiteLLM이 호출하는 구조이므로, ml-intern이 직접 가중치를 로드하지 않습니다. 따라서 ollama serve, vllm, lm_studio, llama.cpp 같은 추론 서버를 먼저 띄우고, ollama/, vllm/, lm_studio/, llamacpp/ 접두사를 가진 모델 ID로 선택하는 흐름입니다. 공유 베이스 URL은 LOCAL_LLM_BASE_URL/LOCAL_LLM_API_KEY에서 받고, 제공자별로 OLLAMA_BASE_URL, VLLM_API_KEY 같은 변수를 두면 그쪽이 우선합니다.

샌드박스 도구를 켜면 에이전트는 사용자의 로컬 파일시스템 대신 비공개 HF Space를 만들어 그 안에서 코드를 실행합니다. 본격적인 HF Jobs로 학습을 돌리기 전에 GPU 샌드박스에서 한 번 검증하는 용도로 적합합니다. 기본값을 영구적으로 바꾸려면 ~/.config/ml-intern/cli_agent_config.json에 { "tool_runtime": "sandbox" }를 두면 됩니다.

ML Intern의 트레이스 공유와 거버넌스

ml-intern은 모든 세션을 자동으로 사용자의 비공개 HF 데이터셋({your-hf-username}/ml-intern-sessions)에 업로드하며, 데이터는 Claude Code JSONL 포맷으로 정리되어 HF Agent Trace Viewer로 그대로 열람할 수 있습니다. CLI 안에서는 /share-traces, /share-traces public, /share-traces private 명령으로 가시성을 조절할 수 있고, 동일한 설정은 Hugging Face Hub의 데이터셋 페이지에서도 변경 가능합니다. 트레이스 업로드를 완전히 끄려면 ~/.config/ml-intern/cli_agent_config.json에 { "share_traces": false }를 두면 됩니다. 별도의 smolagents/ml-intern-sessions 데이터셋은 백엔드 KPI 스케줄러용 익명 텔레메트리에만 사용되고, 개인 세션 데이터와는 분리되어 있습니다.

알림 게이트웨이로는 현재 Slack을 지원합니다. Slack 봇 토큰(SLACK_BOT_TOKEN)과 채널 ID(SLACK_CHANNEL_ID)를 환경 변수로 두면 slack.default 목적지가 자동 생성되며, approval_required, error, turn_complete 같은 이벤트를 Slack 채널로 보낼 수 있습니다. 더 정교한 라우팅은 messaging.destinations를 통해 JSON 설정에서 여러 목적지를 정의할 수 있습니다.

ML Intern 의 라이선스

ML Intern 프로젝트는 Apache-2.0 라이선스로 공개되어 있어, 개인·연구·상업적 용도로 자유롭게 사용할 수 있고 자체 도구나 사내 워크플로우에 통합하는 데에도 제약이 적습니다.

ml-intern 데모

ml-intern 프로젝트 GitHub 저장소

ml-intern 트레이스 뷰어 (Hugging Face)

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~