튜토리얼: Gemini CLI + MCP + Context7 + VS Code Companion (작성중)

728x90

Gemini CLI + MCP + Context7 + VS Code Companion 을 사용하여

HF Custom Config를
HF Hub에 올리고
AutoConfig.from_pretrained()까지 수행하기

0. 목표

다음 네 가지 개념 과 도구 를 실제 작업 을 통해 익히는 게 핵심임.

AI Agent : 스스로 사용할 도구를 선택하여 작업을 수행하는 AI 시스템
Gemini CLI : 터미널에서 쓰는 AI Agent
MCP (Model Context Protocol) : AI Agent가 외부 도구를 확장하는 방식
Context7 : 최신 라이브러리 문서를 AI Agent 에게 공급하는 도구
VS Code Companion (동반자) : 현재 편집 중인 code의 context를 AI Agent에게 전달하는 도구

이를 익히기 위한 실습 예로

HF (Hugging Face) custom config (설정 클래스) 를
Hub 에 업로드하고 이를 로드하는 작업 을 사용함.

이 실습에서 소스코드 중 일부 실행 파일의 작성과 실행, 검증을 모두 Gemini CLI 를 이용할 예정임.

간단한 예제로 하기 위해서
model weights (모델 가중치) 나 model.py 작성은
다루지 않음.

1. AI Agent (에이전트) 란 무엇인가

AI Agent 란,

단순히 질문에 답하는 AI Chatbot을 넘어서
요청을 수행하기 위해 스스로 도구를 선택하고 작업을 수행하는 AI 프로그램 임.

좀 더 쉽게 비교하면 다음과 같음.

구분	설명	예시
일반 LLM Large Language Model 거대 언어 모델	질문을 받아 답변만 생성	"이 코드 설명해줘" => 설명만 반환
AI Agent	질문을 받아 도구 호출, 파일 읽기, 코드 실행까지 수행	"이 코드 고쳐줘" => 파일 열고, 수정하고, 실행까지 수행

즉, AI Agent는 목표를 주면 스스로 계획을 세우고 여러 도구를 써서 실행하는 주체 임.
(사람을 대신하여 prompt의 요청에 따라 자율적으로 계획을 세우고 지원되는 도구를 사용하여 실행하고 결과를 응답)

Agentic System

Agent가 실행되는 데 필요한 모든 구성 요소 (Tool, Memory 등)들을 포함하는 전체 지원 환경을 가리킴.

이 튜토리얼에서 사용하는 Gemini CLI 가 바로 AI Agent 임.

사람: 목표만 제시
Agent: 목표 분석 → 도구 선택 → 실행 → 결과 확인 → 다음 행동 결정

단순한 LLM은 "질문 → 답변"만 함.

반면, AI Agent는

목표를 이루기 위해
스스로 계획을 세우고,
필요한 도구를 호출하고, 실행하고,
결과를 확인하고,
오류가 있으면 스스로 수정까지 함.

2. 네 도구의 관계 한눈에 보기

각각의 역할을 한 문장씩 요약하면 다음과 같음.

Gemini CLI : 목표를 받아 계획하고 실행하는 AI Agent
MCP : Gemini CLI가 외부 도구를 붙이는 표준 방식
Context7 : 최신 라이브러리 문서를 MCP를 통해 공급
VS Code Companion : 지금 편집 중인 파일 맥락을 Gemini에게 전달

각각의 연결방식은 다음과 같음:

항목	Context7	VS Code Companion
연결 방식	MCP	VS Code 익스텐션 직접 통신
등록 위치	`.gemini/settings.json` 의 mcpServers	`/ide install` 명령으로 설치
실행 방식	`npx` 로 MCP 서버 프로세스 실행	VS Code 익스텐션이 IDE 맥락을 직접 전달
터미널 제약	외부 터미널에서도 동작 가능	VS Code integrated terminal 에서만 동작
공급하는 것	최신 라이브러리 문서	열린 파일, 커서 위치, 선택 영역

3. MCP (Model Context Protocol) 란 무엇인가

MCP 는 AI Agent가 외부 도구를 연결하는 표준 규약 (standard protocol) 임.

즉, MCP 는 "AI Agent 와 외부 도구"를 연결하는 공통 인터페이스 임.

이 문서에서는

Context7 을
MCP 서버로 등록해서
Gemini CLI가 사용하게 만듦.

2026.03.16 - [개발환경] - Gemini CLI: Extension, Skill, MCP, Tool (정리)

Gemini CLI: Extension, Skill, MCP, Tool (정리)

Gemini CLI 확장하기: Extension, Agent Skills, MCP, Custom Tools 완전 정리 Gemini CLI는 기본 제공 기능 외에도,사용자가 직접 기능을 확장할 수 있는여러 메커니즘을 제공함. 대표적으로 다음 4가지가 있음:Exte

ds31x.tistory.com

4. Context7 이란 무엇인가

4-1. Context7 이 MCP서버로 사용되는 이유

Gemini CLI는 Google 검색을 포함한 여러 도구를 이미 쓸 수 있는 에이전트임.

그럼에도 Context7을 별도로 쓰는 이유는 "검색 가능 여부" 가 아니라 "무엇을 어떻게 가져오는가" 의 차이 때문임.

일반 웹 검색으로 HF의 transformers 사용법을 찾으면 다음과 같은 문제가 생길 수 있음.

버전이 서로 다른 블로그 포스트, Stack Overflow 답변, 비공식 튜토리얼이 섞여서 나옴
오래된 예제 코드가 현재 버전 API와 맞지 않을 수 있음
어떤 결과가 공식 문서 기준인지 에이전트가 판단해야 하는 부담이 생김

Context7은 이 문제를 다음 방식으로 해결함.

공식 라이브러리 문서와 코드 예제 만 가져옴
특정 버전 기준 으로 문서를 필터링할 수 있음
에이전트가 별도로 출처를 판단할 필요 없이 검증된 예제 를 바로 쓸 수 있음

일반 웹 검색은 도서관에서 "transformers 관련 책 전부"를 가져오는 것임.
Context7은 "transformers 공식 매뉴얼 최신판"만 딱 골라서 가져오는 것임.
검색 자체를 못 하는 게 문제가 아니라, 어떤 문서를 신뢰할 것인가의 문제임.

4-2. Context7이 하는 일

Context7 은 Gemini가 답변하기 전에 최신 공식 문서를 가져다가 Gemini의 입력으로 넣어주는 도구 임.

https://context7.com/ 의 화면. 다양한 문서들이 보임.

과정을 정리하면 다음과 같음.

사용자 질문
Gemini CLI가 Context7 호출 (MCP 경유)
Context7이 최신 HF 공식 문서 검색 후 반환
Gemini가 최신 문서를 읽고 코드 생성 및 실행

Context7 사용 시 Gemini가 최신 공식 문서를 읽고 답변함.

4-3. MCP 서버로서의 Context7

Context7은 MCP 서버로 동작함.

Gemini CLI 설정 파일에 등록
Gemini가 필요할 때 자동으로 Context7을 호출해서 최신 문서를 가져옴.

5. VS Code Companion 이란 무엇인가

VS Code Companion 은 Gemini CLI와 VS Code (에디터) 를 연결해주는 도구임.

이게 없으면 Gemini CLI는 "내가 지금 어떤 파일의 어느 줄을 보고 있는지"를 모름.

Companion을 켜두면 다음 정보가 Gemini에게 전달됨.

현재 열려 있는 파일 (open files)
커서 위치 (cursor position)
선택한 코드 영역 (text selection)
변경된 부분 비교 (native diffing)

Gemini CLI에게 '이 코드 고쳐줘'라고 하면, Companion 없이는 어떤 코드인지 모름.

Companion이 있으면 VS Code에서 지금 보고 있는 파일을 Gemini가 같이 볼 수 있음.

즉,

Context7은 "최신 문서",
VS Code Companion은 "현재 내 코드 맥락" 을
AI Agent (=Gemini CLI)에게 공급하는 역할임.

2026.04.02 - [utils] - Gemini-cli : Gemini CLI Companion

Gemini-cli : Gemini CLI Companion

Gemini CLI Companion 은 vscode의 extension(확장 프로그램)으로Gemini CLI와 vscode가 연동되게 해 줌. Gemini CLI가 지금 VS Code에서 개발자가 현재 무엇을 보고 있는지 더 잘 이해하게 해 주는 extension임요구조건V

ds31x.tistory.com

6. 이번 튜토리얼을 위한 task

위의 네 도구를 실제로 써볼 수 있는 가장 작은 실습 예제로
HF custom config 를 Hub 저장소에 올리고 다시 로드하기 를 선택함.

이번 튜토리얼에서 하는 작업은 다음 다섯 가지임.

custom config 클래스 (PreTrainedConfig 상속) 초안 작성
Gemini CLI + Context7으로 해당 파일 검토 및 수정
업로드 스크립트를 Gemini CLI가 생성 후 직접 실행
HF Hub 사이트에서 업로드 결과 직접 확인
검증 스크립트를 Gemini CLI가 생성 후 직접 실행

model weights 저장이나 modeling.py, AutoModel 작성은 이번 튜토리얼 범위 밖임.

PreTrainedConfig 에 대한 보다 자세한 내용은 다음을 참고:

https://ds31x.github.io/wiki/hf/hf_config/

HF-Config

ds31x.github.io

7. 튜토리얼

1) 사전 요구 사항들

필요한 것은 다음과 같음:

Node.js 와 npm : Context7 MCP 서버 실행에 필요 (JavaScript Runtime)
Python 3.8 이상 및 transformers, huggingface_hub 패키지
Gemini CLI : 공식 GitHub에서 설치
VS Code
Hugging Face 계정 과 access token (접근 토큰)
Context7 API key : 무료 발급 가능 (권장)

설치 확인은 다음 명령어로 함.

node -v
npm -v
python -V
gemini --version
pip show transformers huggingface_hub

HF 토큰은 미리 로그인해 둠.

hf auth login

이 명령어를 실행하면 HF 토큰 입력을 요청함.
HF 사이트 > 우측 상단 프로필 > Settings > Access Tokens 에서 발급받을 수 있음.
Hub에 파일을 업로드하려면 반드시 write 권한이 있는 토큰이어야 함.

토큰 설정 관련해선 다음을 참고: 2026.03.05 - [ML] - Hugging Face Access Token 생성 및 권한 설정 가이드

Hugging Face Access Token 생성 및 권한 설정 가이드

Access Token이란?Hugging Face Access Token은Hugging Face의 다양한 서비스에프로그래밍 방식으로 접근하기 위한 인증(Authentication) 수단임.즉,CLI(Command Line Interface)나 Python 코드에서Hugging Face Hub에 접근할 때,

ds31x.tistory.com

hf auth login 등에 대한 자세한 건 다음을 참고: https://ds31x.github.io/wiki/hf/hf_start/

HF Start

Hugging Face Hub와 주요 라이브러리 구조, 인증 방법(hf auth login)을 소개

ds31x.github.io

2) 프로젝트 디렉토리와 파일 구조

이번 튜토리얼에서

사람이 직접 만드는 파일 과
Gemini CLI가 만드는 파일 을 구분하면 다음과 같음.

my_config_only_repo/
├─ .gemini/
│  └─ settings.json              : 사람이 직접 작성 (MCP 등록)
├─ GEMINI.md                     : 사람이 직접 작성 (에이전트 행동 규칙)
└─ src/
   └─ my_config_pkg/
      ├─ __init__.py
      ├─ configuration_mine.py     : 사람이 초안 작성, Gemini가 검토·수정
      ├─ upload_config_to_hub.py   : Gemini CLI가 직접 생성·실행
      └─ verify_config_from_hub.py : Gemini CLI가 직접 생성·실행·결과 보고

다시 한번 강조하지만 model 관련 파일은 없음.
config-only (설정만 있는) 저장소가 목표임.

3) MCP 서버 등록

수정해야할 파일은 Gemini CLI의 로컬 설정파일인 .gemini/settings.json 임

프로젝트 루트에 .gemini/settings.json 파일을 만들고 다음처럼 작성함.

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

npx 는 Node.js 명령어임.
이 설정은 "Gemini CLI가 Context7 MCP 서버를 필요할 때 npx로 실행해라"는 뜻임.
이 설정을 통해 Gemini가 Context7을 알아서 호출할 수 있게 됨.

Context7 API key를 발급받았다면 다음 둘 중의 하나의 설정을 사용할 것.

다음은 Node.js가 설치된 경우로 npx를 이용 (로컬프로세스로 실행됨).

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {
        "CONTEXT7_API_KEY": "발급받은_키"
      }
    }
  }
}

아래의 경우처럼 환경변수에서 읽어오는 형태를 사용해도 됨.

다음은 httpUrl을 통한 방법 (Context7 원격서버에 접속).

{
  "mcpServers": {
    "context7": {
      "httpUrl": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "$CONTEXT7_API_KEY"
      }
    }
  }
}

그리고 셸에서 환경 변수 (environment variable) 로 API key를 다음과 같이 설정:
(사실 앞서 설정에 직접 기재한 경우는 환경변수에 넣지 않아도 됨)

export CONTEXT7_API_KEY="발급받은_키"

Context7은

API key 없이도 동작하지만,
사용량 제한 (rate limit) 이 있으므로 가능하면 발급받는 것을 권장함.

4) `GEMINI.md` 작성

GEMINI.md 는 "이 프로젝트에서 Gemini가 어떻게 행동해야 하는지"를 미리 정해두는 파일 임.

이를 통해 에이전트 행동 규칙 정의할 수 있음.

GEMINI.md 는 이 프로젝트용 AI Agent의 행동 지침서임.
한 번 써두면 Gemini가 프로젝트를 열 때마다 이 규칙을 먼저 읽음."

# Project rules

- 이 프로젝트는 'hf5' conda 환경을 활성화하여 실행해야 함.
- conda 환경의 python을 사용해야 하니 python으로 실행할 것(python3 쓰지 말 것)
- Hugging Face Transformers 관련 작업은 반드시 Context7을 먼저 사용할 것.
- 학습 기억보다 Hugging Face 공식 문서를 우선으로 참조할 것.
- 이 프로젝트의 목표는 config 업로드와 AutoConfig.from_pretrained() 확인까지임.
- 명시적으로 요청하지 않는 한 모델 코드는 생성하지 말 것.
- 스크립트를 생성한 경우 즉시 실행하고 출력 결과를 보고할 것.
- 가장 작은 수정안(patch)을 먼저 제안하고, 적용 전에 확인을 받을 것.
- 스크립트 실행 후 성공한 것과 실패한 것을 반드시 요약할 것.

특히, 마지막 세 줄이 특히 중요함.

스크립트를 생성한 경우 즉시 실행하고 출력 결과를 보고할 것.
- When creating scripts, always run them immediately and report the output.
- Gemini가 파일을 만들면 바로 실행하고 결과를 알려주게 강제함.
가장 작은 수정안(patch)을 먼저 제안하고, 적용 전에 확인을 받을 것
- Propose the smallest patch first, then ask before applying.
- AI Agent가 과도하게 많은 것을 바꾸지 않도록 제한함.
스크립트 실행 후 성공한 것과 실패한 것을 반드시 요약할 것.
- After running any script, summarize what succeeded and what failed.
- 실행 후 성공/실패 여부를 반드시 요약하게 만듦.

위의 GEMINI.md는 매우 단순화시킨 것임. 실제 프로젝트에선 보다 정교하게 사용하는 것을 권함

2026.04.12 - [개발환경] - Gemini-CLI: GEMINI.md - Local Instructional Context

Gemini-CLI: GEMINI.md - Local Instructional Context

1. OverviewGEMINI.md는 Gemini CLI가 각 prompt와 함께 자동으로 읽어 들이는 local instructional context file.AI에게 "어떻게 응답할 것인가", "어떻게 작업할 것인가"를 사전에 정의하는 configuration file의 역할을

ds31x.tistory.com

5) custom config 작성

src/my_config_pkg/configuration_mine.py 를 다음처럼 작성함.

이 파일은

사람이 직접 초안을 만들고,
이후 Gemini CLI가 검토 및 수정함.

# Transformer 기준의 설정값
# Vaswani 2017
from transformers import PreTrainedConfig

class MyConfig(PreTrainedConfig):
    model_type = "my-config-demo"

    def __init__(
        self,
        vocab_size=10000,           # Adjusted from BERT's 30522 to a more generic size
        hidden_size=512,            # Adjusted from BERT's 768 to a common Transformer size
        num_hidden_layers=6,        # Adjusted from BERT's 12 to a more typical number of layers
        num_attention_heads=8,      # Adjusted from BERT's 12 (512 / 8 = 64, a common head size)
        intermediate_size=2048,     # Adjusted from BERT's 3072 (4 * hidden_size for 512)
        hidden_act="relu",          # ReLU is a common activation in standard Transformers
        hidden_dropout_prob=0.1,
        attention_probs_dropout_prob=0.1,
        max_position_embeddings=512, # A reasonable max sequence length
        # type_vocab_size=2,        # Removed as it's specific to BERT's segment embeddings
        initializer_range=0.02,
        layer_norm_eps=1e-12,
        pad_token_id=0,
        **kwargs
    ):
        super().__init__(pad_token_id=pad_token_id, **kwargs)

        self.vocab_size                 = vocab_size
        self.hidden_size                = hidden_size
        self.num_hidden_layers          = num_hidden_layers
        self.num_attention_heads        = num_attention_heads
        self.intermediate_size          = intermediate_size
        self.hidden_act                 = hidden_act
        self.hidden_dropout_prob        = hidden_dropout_prob
        self.attention_probs_dropout_prob = attention_probs_dropout_prob
        self.max_position_embeddings    = max_position_embeddings
        # self.type_vocab_size            = type_vocab_size # Removed
        self.initializer_range          = initializer_range
        self.layer_norm_eps             = layer_norm_eps
        
        
# AutoConfig 등록
MyConfig.register_for_auto_class("AutoConfig")

PreTrainedConfig 를 상속 (inheritance) 하면 HF가 제공하는 저장,불러오기,Hub 업로드 기능을 그대로 물려받을 수 있음.
- CustomConif 클래스를 처음부터 다 만드는 게 아님: 반드시 HF가 만든 클래스를 물려받아서 확장해서 구현해야 함.
**kwargs 를 반드시 super().__init__(**kwargs) 로 넘겨야 하는 이유는, HF 상위 클래스가 자체적으로 처리해야 하는 설정 값들이 있기 때문임.
- 이걸 빠뜨리면 from_pretrained() 에서 예상치 못한 오류가 날 수 있음.
register_for_auto_class("AutoConfig") 는 "이 클래스를 AutoConfig 테이블에 등록해달라"는 요청임.
- 문자열 "AutoConfig" 는 어떤 Auto 클래스에 등록할지를 지정하는 것이고, config이므로 "AutoConfig" 를 씀.

이 클래스에서 반드시 챙겨야 할 세 가지는 다음과 같음.

PreTrainedConfig 상속
model_type 문자열 정의
**kwargs 를 super().__init__(**kwargs) 로 전달
AutoConfig 에 등록!

6) VS Code Companion 연결 및 Gemini CLI 실행

VS Code에서 프로젝트를 열고, integrated terminal (내장 터미널) 에서 gemini 를 실행함:
(conda 등을 통한 격리된 환경을 사용한다면, integrated terminal에서 해당 환경을 활성화하고 나서 실행하길 권함)

gemini

Integrated Terminal 이 보이는 패널에서 Gemini-CLI가 동작하고 있는 모습.

중요
Gemini-CLI는
반드시 VS Code 내장 터미널 에서 실행해야 함.
외부 터미널 (Windows Terminal, iTerm2 등) 에서 실행하면
VS Code Companion이 IDE 맥락을 전달할 수 없음.

만약 VS Code Companion이 설치가 안되어 있다면
CLI 안에서 다음 명령어를 순서대로 실행함.

/ide install
/ide enable

VS Code Companion 의 동작여부는 다음으로 확인 가능:

VS Code Companion이 설치되었고 활성화 된 상태라면 다음을 입력

/mcp list

정상 상태라면 다음처럼 출력됨.

context7 - Ready

이 상태에서 Gemini CLI는 다음 두 가지를 동시에 활용할 수 있음.

Context7 : 최신 HF 공식 문서 (MCP 경유)
VS Code Companion : 현재 열린 파일, 커서 위치, 선택 영역

7) VS Code Companion 동작 확인

Companion이 실제로 IDE 맥락을 전달하고 있는지 연결 직후에 바로 확인 하는 것이 좋음.

이 확인을 먼저 해두면,

이후 Gemini의 답변이 "내 파일을 실제로 보고" 나온 것인지,
"일반적인 예시 코드 기준으로" 나온 것인지 구분할 수 있음.

확인 방법 1 : 열린 파일 목록 질문

VS Code에서 configuration_mine.py 를 열어 둔 상태에서 Gemini CLI 안에 다음처럼 입력함.

현재 VS Code에서 열려 있는 파일이 무엇인가요?
(What files do I currently have open in VS Code?)

Companion이 정상 동작하고 있다면 다음과 비슷한 답변이 나옴.

You currently have the following file open in VS Code:
- src/my_config_pkg/configuration_mine.py

Companion이 연결되어 있지 않다면 다음처럼 답변함.

I don't have access to your IDE context.
You may need to run /ide enable first.

이 차이가 Companion 유무의 핵심임.

Companion 없이는 Gemini CLI가 "터미널 안의 텍스트"만 봄.
Companion이 있으면 Gemini CLI가 "VS Code에서 지금 열린 파일과 커서 위치"까지 볼 수 있음.

확인 방법 2 : 커서 위치 질문

VS Code에서 configuration_mine.py 를 열고, hidden_size 가 정의된 줄에 커서를 올려둔 상태에서 다음처럼 입력함.

현재 VS Code에서 커서가 어디에 있나요?
(Where is my cursor right now in VS Code?)

Companion이 정상 동작하면 다음처럼 현재 줄 번호와 파일명을 알려줌.

Your cursor is currently at line 9 in
src/my_config_pkg/configuration_mine.py

확인 방법 3 : 선택 영역 질문

VS Code에서 __init__ 메서드 일부를 드래그해서 선택한 상태에서 다음처럼 입력함.

지금 선택한 코드가 무엇인가요?
(What code do I have selected right now?)

Companion이 정상 동작하면 선택한 코드 블록을 그대로 인식해서 답변함.

You have the following code selected:
    def __init__(
        self,
        hidden_size=128,
        ...
    ):

동작 확인 결과 요약

질문	Companion 정상	Companion 없음
"What files do I have open?"	파일명 정확히 답변	모른다고 답변
"Where is my cursor?"	파일명 + 줄 번호 답변	모른다고 답변
"What code is selected?"	선택 코드 블록 답변	모른다고 답변

세 가지 중 하나라도 정상 답변이 나오면 Companion이 동작하고 있는 것임.

Companion이 동작하지 않는 경우 체크리스트

VS Code integrated terminal 에서 gemini 를 실행했는지 확인 (외부 터미널 불가)
/ide install 과 /ide enable 을 실행했는지 확인 (/ide status로 활성화 여부 확인.)
VS Code를 재시작한 뒤 다시 시도
Gemini CLI 버전이 VS Code Companion을 지원하는지 확인

8) Step 1 — Gemini CLI가 config 파일 검토하기

8-1) 검토 전 Companion 맥락(context) 전달 확인

config 검토를 요청하기 전에, Companion이 실제로 현재 파일을 전달하고 있는지 한 번 더 확인함.

VS Code에서 configuration_mine.py 를 활성화된 탭으로 열어 둔 상태에서 다음처럼 입력함.

Context7은 아직 사용하지 말고, 다음만 알려줘:
현재 VS Code에서 열려 있는 파일의
클래스 이름과 model_type 값이 무엇인가요?

Without using Context7 yet, just tell me:
what is the class name and model_type value
in the file I currently have open in VS Code?

Companion이 정상이면 다음처럼 파일을 직접 읽어서 답변함.

In the currently open file configuration_mine.py:
- Class name  : MyConfig
- model_type  : "my-config-demo"

이 답변이 나오면 Companion 에서 수행하는 Gemini CLI 맥락 전달이 정상 이라는 뜻임.

이 확인이 중요한 이유

이후 검토 요청에서 Gemini가 "내 파일을 실제로 보고" 대답하는 것인지,
아니면 "일반적인 예시 코드를 기준으로" 대답하는 것인지를 구분하기 위함임.
Companion이 없으면 Gemini는 내 코드가 아닌 일반적인 답변을 줄 수 있음.

8-2) contex7 정보로 검토 요청

Companion 의 정상동작을 확인한 뒤, 다음 요청을 입력함:
(수정은 아직 하지 않고 검토만 먼저 요청함.)

/huggingface/transformers 라이브러리로 context7을 사용해줘.
나는 전체 모델 저장소가 아닌 config-only 저장소만 원해.
다음 항목에 대한 최신 문서를 읽어줘:
1) PreTrainedConfig 요구사항
2) Hub에 configuration 저장 및 업로드하기
3) AutoConfig.from_pretrained 동작 방식
그런 다음 현재 VS Code에서 열려 있는 configuration_mine.py 파일을 검토해서
누락되거나 잘못된 부분이 무엇인지 알려줘.
아직 어떤 파일도 수정하지 말고, 보고만 해줘.

Use context7 with library /huggingface/transformers.
I only want a config-only repository, not a full model repository.

Read the current docs for:
1) PreTrainedConfig requirements
2) saving and pushing configuration to the Hub
3) AutoConfig.from_pretrained behavior

Then inspect the currently open configuration_mine.py file
and tell me what is missing or incorrect.

Do not edit any file yet. Just report.

Gemini CLI는 이 요청에서 다음을 수행함.

Context7을 호출해 최신 HF PreTrainedConfig 문서를 가져옴
VS Code Companion을 통해 현재 열린 configuration_mine.py 를 읽음
문서와 현재 파일을 대조해 문제점을 요약해서 알려줌

context7 과 학습된 지식을 기반으로 PreTrainedConfig 관련 내용을 확인.

AI Agent 개념 관련하여 주의할 점

사용자는 "검토해줘"라고 말했을 뿐임.
이 지시로부터 Gemini CLI가 스스로 Context7 호출 → 파일 읽기 → 비교검토 → 요약의 순서를 계획하고 실행함.
이것이 AI Agent의 핵심 동작 방식임.

8-3) 검토 결과에서 Companion 동작 여부 추가 확인

Gemini의 검토 결과 답변에서 다음 두 가지를 확인할 것:

1. 파일명이 답변에 명시되는지

# 좋은 예 — Companion이 맥락을 전달한 경우
In your currently open file `configuration_mine.py`, I can see...

# 좋지 않은 예 — 일반적인 답변인 경우
In a typical PreTrainedConfig subclass, you should...

2. 실제 클래스명과 필드명이 답변에 나오는지

# 좋은 예
Your MyConfig class defines hidden_size, num_labels, dropout_prob.
The model_type "my-config-demo" is correctly set.

# 좋지 않은 예
You should define a model_type in your config class.

Gemini 답변에 실제 파일의 클래스명, 변수명, 값이 구체적으로 언급 된다면 Companion이 제대로 동작하고 있다는 증거임.

9) Step 2 — Gemini CLI가 Upload Script를 직접 생성하고 실행하기

검토 결과를 확인한 뒤 다음 요청을 입력함:

(주의할 점은 아래의 prompt에서 "<your-username>" 은 실제 본인의 HF 계정명으로 바꿔야 함.

/huggingface/transformers 라이브러리로 context7을 사용해줘.
이제 다음 단계를 순서대로 수행해줘:

1. src/my_config_pkg/upload_config_to_hub.py 를 생성해줘.
   스크립트는 반드시 다음을 수행해야 해:
   - configuration_mine.py 에서 MyConfig 를 import 할 것
   - hidden_size=256, hidden_dropout_prob=0.2 로 인스턴스를 생성할 것
   - "<your-username>/my-config-demo" 로 Hub에 업로드할 것
   - 마지막에 성공 또는 오류 메시지를 명확하게 출력할 것

2. 생성 직후 스크립트를 바로 실행해줘.
   터미널 출력 전체를 보고해줘.
   오류가 있으면 보고 전에 원인을 파악하고 수정해줘.
   
Use context7 with library /huggingface/transformers.

Now do the following steps in order:

1. Create src/my_config_pkg/upload_config_to_hub.py.
   The script must:
   - Import MyConfig from configuration_mine.py
   - Instantiate it with hidden_size=256, hidden_dropout_prob=0.2
   - Push it to Hub as "<your-username>/my-config-demo"
   - Print a clear success or error message at the end

2. Run the script immediately after creating it.
   Report the full terminal output.
   If there is an error, diagnose it and fix it before reporting.

Gemini CLI가 이 요청에서 수행하는 것은 다음과 같음.

configuration_mine.py 에 필요한 최소 수정 적용
upload_config_to_hub.py 파일 생성
생성한 스크립트를 터미널에서 직접 실행
실행 결과 전체를 출력하고 성공/실패 요약

Gemini CLI가 만드는 upload_config_to_hub.py 는 대략 다음 형태가 됨:
(Gemini가 Context7 기반으로 최신 API를 참고해 생성하므로 세부 코드는 달라질 수 있음.)

import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).parent))
from configuration_mine import MyConfig

def main():
    cfg = MyConfig(
        hidden_size=256,
        dropout_prob=0.2,
    )
    print(f"Config 생성 완료: {cfg}")

    repo_id = "<your-username>/my-config-demo"
    print(f"Hub 업로드 시작: {repo_id}")
    cfg.push_to_hub(repo_id)
    print(f"업로드 성공: https://huggingface.co/{repo_id}")

if __name__ == "__main__":
    main()

push_to_hub() 는 PreTrainedConfig 를 상속했기 때문에 사용가능해진 메서드임.
즉, 직접 구현한 게 아니라 물려받은 method임.

참고로, 이 동작을 실행하기 위해선
앞서 절에서 애기한 hf auth login 명령어 실행을 통한 로그인이 되어 있어야함.

실제 동작시 에러를 만들기도 하며, 이를 알아서 수정을 함.

Native diffing을 이용하여 새로작성한 코드를 보여주면서 스크립트 생성에 대한 허가를 요청.

스크립트 실행에서 발생한 에러를 파악하고 이에 대한 수정을 제안하고 수정에 대한 허가를 요청

conda 가상환경을 사용할 것을 지시하였고, 이를 바탕으로 다시 실행 허가를 요청

10) HF Hub 사이트에서 업로드 결과 직접 확인하기

업로드가 성공했으면 HF 사이트에서 직접 눈으로 확인함.

10-1) 저장소 페이지 열기

웹 브라우저에서 다음 주소로 접속함.

https://huggingface.co/<your-username>/my-config-demo

<your-username> 는 업로드 시 사용한 값으로 바꿔서 접속함.

10-2) Files and versions 탭에서 파일 확인

저장소 페이지 상단 탭 중 "Files and versions" 를 클릭하면 다음 파일이 올라가 있어야 함.

my-config-demo/
├─ config.json             :이 파일이 있으면 업로드 성공 (auto_map 항목확인)
└─ configuration_mine.py   :custom class 코드가 함께 올라감

10-3) `config.json` 내용 직접 확인

config.json 파일을 클릭하면 업로드된 내용을 브라우저에서 바로 볼 수 있음.

내용은 다음과 같은 형태임.

확인 포인트는 다음 세 가지임.

"model_type": "my-config-demo" 가 있는지
hidden_size, hidden_dropout_prob 값 등이 업로드할 때 넣은 값과 일치하는지
transformers_version 이 기록되어 있는지
auto_map이 있는지

11) Step 3 — Gemini CLI가 검증 스크립트를 직접 생성하고 실행하기

HF 사이트에서 파일 업로드를 눈으로 확인한 다음, Gemini CLI로 돌아와서 코드 수준의 검증도 수행함:

(<your-username> 는 업로드 시 사용한 값으로 바꿔서 접속함.)

/huggingface/transformers 라이브러리로 context7을 사용해줘.
다음 단계를 순서대로 수행해줘:

1. src/my_config_pkg/verify_config_from_hub.py 를 생성해줘.
   스크립트는 반드시 다음을 수행해야 해:
   - AutoConfig.from_pretrained() 를 trust_remote_code=True 와 함께 
     사용해서 "<your-username>/my-config-demo" 에서 config를 로드할 것
   - type(cfg) 를 출력할 것
   - cfg.hidden_size, cfg.hidden_dropout_prob 를 출력할 것
   - hidden_size == 256, hidden_dropout_prob == 0.2 인지 assert 할 것
   - 모든 assert 가 통과하면 "검증 성공" 을 출력할 것
   - assert 가 실패하면 상세 내용과 함께 "검증 실패" 를 출력할 것

2. 생성 직후 스크립트를 바로 실행해줘.
   터미널 출력 전체를 보고해줘.
   오류가 있으면 보고 전에 원인을 파악하고 수정해줘.

Use context7 with library /huggingface/transformers.

Do the following steps in order:

1. Create src/my_config_pkg/verify_config_from_hub.py.
   The script must:
   - Load the config from "<your-username>/my-config-demo"
     using AutoConfig.from_pretrained() with trust_remote_code=True
   - Print type(cfg)
   - Print cfg.hidden_size, cfg.hidden_dropout_prob
   - Assert that hidden_size == 256,  hidden_dropout_prob == 0.2
   - Print "검증 성공" if all assertions pass
   - Print "검증 실패" with details if any assertion fails

2. Run the script immediately after creating it.
   Report the full terminal output.
   If there is an error, diagnose and fix it before reporting.

Gemini CLI가 만드는 verify_config_from_hub.py 는 대략 다음 형태가 됨.

from transformers import AutoConfig


def main():
    repo_id = "your-username/my-config-demo"
    print(f"Hub에서 config 로드 중: {repo_id}")

    cfg = AutoConfig.from_pretrained(
        repo_id,
        trust_remote_code=True,    # ← 처음부터 포함
    )
    print(f"type         : {type(cfg)}")
    print(f"hidden_size  : {cfg.hidden_size}")
    print(f"num_labels   : {cfg.num_labels}")
    print(f"dropout_prob : {cfg.dropout_prob}")

    try:
        assert cfg.hidden_size == 256,   f"hidden_size 불일치: {cfg.hidden_size}"
        assert cfg.num_labels == 3,      f"num_labels 불일치: {cfg.num_labels}"
        assert cfg.dropout_prob == 0.2,  f"dropout_prob 불일치: {cfg.dropout_prob}"
        print("\n검증 성공 ✓")
    except AssertionError as e:
        print(f"\n검증 실패 ✗ — {e}")


if __name__ == "__main__":
    main()

AutoConfig 는 HF Hub에서 config 파일을 읽어오는 generic class (범용 클래스) 임.
저장소 이름만 넘기면 Hub에서 config.json 을 자동으로 찾아서 로드함.
trust_remote_code=True 는 "Hub에 올라가 있는 외부 코드를 내 로컬에서 실행하겠다" 라고 허가하는 것임.
- 기본값이 False 인 이유는, 출처를 모르는 코드를 자동으로 실행하면 보안상 위험할 수 있기 때문임.
- 본인이 만든 저장소라면 안전하게 True 로 설정할 수 있음.
assert 는 "이 조건이 참이 아니면 즉시 오류를 발생시켜라"는 파이썬 내장 명령임.
업로드한 값과 읽어온 값이 정확히 일치하는지를 코드 수준에서 보장하기 위해 사용함.

참고로, AutoConfig가 실제 로딩을 하는 과정은 다음과 같음:

AutoConfig.from_pretrained("username/my-config-demo")
    ↓
config.json 에서 "model_type": "my-config-demo" 읽음
    ↓
Auto 등록 테이블에서 "my-config-demo" 검색
    ↓
등록 없음 → PretrainedConfig 로 폴백
등록 있음 → MyConfig 로 정확히 복원

f-string 에서 줄바꿈등을 잘못 작성하는 에러를 계속발생시킴. 이를 수정하려는 허가 요청.

정상적으로 실행되면 터미널 출력은 다음과 같음.

Hub에서 config 로드 중: your-username/my-config-demo
type         : <class 'transformers_modules.your-username.my-config-demo.configuration_mine.MyConfig'>
hidden_size  : 256
hidden_dropout_prob : 0.2

검증 성공 ✓

요약

이번 튜토리얼 전체를 통해 Gemini CLI가 수행한 것을 정리하면 다음과 같음.

단계	Gemini CLI 가 처리한 것	사용한 도구
문서 조회	최신 HF `PreTrainedConfig` 문서 검색	Context7 (MCP 경유)
코드 검토	현재 열린 파일 읽고 문제점 보고	VS Code Companion
코드 수정	`configuration_mine.py` 에 patch 적용	파일 시스템 직접 접근
스크립트 생성	`upload_config_to_hub.py` 작성	파일 시스템 직접 접근
업로드 실행	생성한 스크립트를 터미널에서 직접 실행	터미널 실행
검증 스크립트 생성	`verify_config_from_hub.py` 작성	파일 시스템 직접 접근
검증 실행	검증 스크립트 실행 후 결과 요약	터미널 실행

명심할 부분:

파일 작성, 실행, 검증을 사람이 아니라 Gemini CLI가 직접 수행 한다는 것
Context7이 최신 문서를 공급 하고, VS Code Companion이 현재 코드 맥락을 공급 한다는 것
Companion 동작 여부를 질문 → 답변의 구체성 으로 직접 확인할 수 있다는 것
이 모든 것이 AI Agent가 도구를 조합해서 작업을 수행하는 방식 이라는 것

728x90

'ML' 카테고리의 다른 글

Multi-Head "Masked/Cross" Attention - Transformer Decoder (1)	2026.04.18
Ex: Linear Regression 연습 (0)	2026.04.11
torch.nn.Module의 상태(state)-Parameter and Buffer (0)	2026.04.09
pytorch-torchinfo 란 (0)	2026.04.09
Multi-Head Self Attention - Transformer Encoder (0)	2026.04.07

튜토리얼: Gemini CLI + MCP + Context7 + VS Code Companion (작성중)

0. 목표

1. AI Agent (에이전트) 란 무엇인가

2. 네 도구의 관계 한눈에 보기

3. MCP (Model Context Protocol) 란 무엇인가

4. Context7 이란 무엇인가

4-1. Context7 이 MCP서버로 사용되는 이유

4-2. Context7이 하는 일

4-3. MCP 서버로서의 Context7

5. VS Code Companion 이란 무엇인가

6. 이번 튜토리얼을 위한 task

7. 튜토리얼

1) 사전 요구 사항들

2) 프로젝트 디렉토리와 파일 구조

3) MCP 서버 등록

4) GEMINI.md 작성

5) custom config 작성

6) VS Code Companion 연결 및 Gemini CLI 실행

7) VS Code Companion 동작 확인

확인 방법 1 : 열린 파일 목록 질문

확인 방법 2 : 커서 위치 질문

확인 방법 3 : 선택 영역 질문

동작 확인 결과 요약

Companion이 동작하지 않는 경우 체크리스트

8) Step 1 — Gemini CLI가 config 파일 검토하기

8-1) 검토 전 Companion 맥락(context) 전달 확인

8-2) contex7 정보로 검토 요청

8-3) 검토 결과에서 Companion 동작 여부 추가 확인

9) Step 2 — Gemini CLI가 Upload Script를 직접 생성하고 실행하기

10) HF Hub 사이트에서 업로드 결과 직접 확인하기

10-1) 저장소 페이지 열기

10-2) Files and versions 탭에서 파일 확인

10-3) config.json 내용 직접 확인

11) Step 3 — Gemini CLI가 검증 스크립트를 직접 생성하고 실행하기

요약

'ML' 카테고리의 다른 글

관련글

티스토리툴바

4) `GEMINI.md` 작성

10-3) `config.json` 내용 직접 확인