> ## Documentation Index
> Fetch the complete documentation index at: https://docs.banya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI 모델 연결

> CodePilot에서 AI 모델을 선택하고 API 키를 등록하는 방법을 안내합니다.

CodePilot이 답변을 만들려면 **AI 모델**이 연결되어 있어야 합니다.

대부분의 경우, 설정에서 **모델을 선택하고 개인 API 키만 등록**하면 됩니다. 기본으로 Google이 들어가 있어 바로 시작할 수 있습니다. 이 문서에서는 **Google Gemini**를 예로 설명합니다.

<Info>
  관리자(super)가 조직에서 사용할 프로바이더와 모델을 미리 켜두면, 팀원은 그 목록에서 고르기만 하면 됩니다. 목록에 없는 모델을 직접 등록하는 것은 [사용자 정의 모델](#4-사용자-정의-모델-직접-등록하기-독립-실행-전용)로, **로그인 없이 쓰는 독립 실행 환경 전용**입니다.
</Info>

***

## 1. Gemini API 키 발급받기

API 키는 Google에서 무료로 발급받을 수 있습니다.

<Steps>
  <Step title="Google AI Studio 접속">
    브라우저에서 [aistudio.google.com/apikey](https://aistudio.google.com/apikey) 에 접속하고 Google 계정으로 로그인합니다.
  </Step>

  <Step title="API 키 만들기">
    **API 키 만들기(Create API key)** 버튼을 클릭합니다. 프로젝트를 고르라고 하면 아무 프로젝트나 선택하거나 새로 만듭니다.
  </Step>

  <Step title="키 복사">
    `AIza` 로 시작하는 문자열이 생성됩니다. **복사** 버튼을 눌러 보관하세요.
  </Step>
</Steps>

<Warning>
  API 키는 비밀번호와 같습니다. 소스 코드나 사내 메신저에 붙여넣지 마세요. 유출되면 Google AI Studio에서 즉시 삭제하고 새로 발급받으세요.
</Warning>

<Info>
  Gemini는 무료 사용량이 제공됩니다. 사용량을 초과하면 과금될 수 있으니, Google AI Studio에서 결제 설정과 한도를 확인하세요.

  **코드 작업은 한 번에 오가는 컨텍스트가 큽니다.** 무료 티어나 낮은 등급에서는 분당 요청·토큰 한도(rate limit)에 자주 걸려 응답이 끊기거나 느려질 수 있습니다. 실제 개발에 쓴다면 **유료 티어를 권장합니다.**
</Info>

***

## 2. 모델 선택하고 API 키 등록하기

발급받은 키를 설정에서 등록합니다.

<Steps>
  <Step title="AI 모델 설정 열기">
    채팅 패널 오른쪽 위의 **톱니바퀴(⚙) 아이콘**을 클릭하고, 왼쪽 메뉴에서 **AI 모델** 을 선택합니다.

    <img src="https://mintcdn.com/banyaai/RKMDgz3hUid7a9AA/images/IDE_AI_MODEL.png?fit=max&auto=format&n=RKMDgz3hUid7a9AA&q=85&s=8b96b0601e4735ffdf2ddeae5616ea39" alt="AI 모델 설정" width="1030" height="685" data-path="images/IDE_AI_MODEL.png" />
  </Step>

  <Step title="AI 모델 선택">
    **AI 모델 선택** 드롭다운에서 사용할 프로바이더를 고릅니다. 기본으로 **Google** 이 들어가 있으니 그대로 두어도 됩니다.
  </Step>

  <Step title="모델 고르기">
    아래 **모델 설정**(선택한 모델의 API 설정을 구성하세요) 영역에서 **모델** 드롭다운을 열어 사용할 모델을 고릅니다. (예: `Gemini 3.0 Flash`)
  </Step>

  <Step title="개인 API 키 등록">
    **API Key** 항목을 **개인 API Key** 로 둔 다음, **개인 API Key** 입력창에 1단계에서 복사한 키를 붙여넣고 **저장** 을 클릭합니다.
  </Step>
</Steps>

이제 채팅에 아무 질문이나 입력해 연결을 확인해 보세요.

```
안녕? 잘 연결됐는지 확인용이야.
```

<Tip>
  **Streaming · Native tool calls · Thinking · Multimodal** 토글로 응답 방식을 조정할 수 있습니다. 자세한 내용은 [설정](/ide/settings) 문서를 참고하세요.
</Tip>

***

## 3. 관리자 키로 전환하기

관리자가 조직에 API 키를 등록해 두었다면, **API Key** 항목에 관리자 키와 개인 키를 고르는 드롭다운이 나타납니다. 여기서 관리자 키로 전환하면 개인 키 없이 바로 사용할 수 있습니다.

<img src="https://mintcdn.com/banyaai/WzAw27WCh1E5UjSP/images/IDE_MODEL_KEY_SOURCE.png?fit=max&auto=format&n=WzAw27WCh1E5UjSP&q=85&s=52e9db5bb0ca00bbffe00ef6bad53c45" alt="API 키 소스 선택" width="767" height="246" data-path="images/IDE_MODEL_KEY_SOURCE.png" />

| 선택              | 의미                            |
| --------------- | ----------------------------- |
| **관리자 API Key** | 조직이 등록한 키를 씁니다. 비용은 조직이 부담합니다 |
| **개인 API Key**  | 내가 발급받은 키를 씁니다. 비용은 내가 부담합니다  |

<Info>
  관리자 키와 개인 키가 모두 있으면 기본으로 **관리자 API Key** 가 선택됩니다. 등록된 키가 하나도 없으면 **등록된 키 없음** 으로 표시되니, 관리자에게 문의하거나 개인 키를 등록하세요.
</Info>

***

## 4. 사용자 정의 모델 직접 등록하기 (독립 실행 전용)

<Info>
  이 방법은 **로그인 없이 사용하는 독립 실행(BYOK) 환경 전용**입니다. 위 프로바이더 목록에 없는 모델을 엔드포인트까지 직접 지정해 등록할 때 사용합니다. 조직에 로그인한 상태에서는 **사용자 정의 모델** 항목이 보이지 않습니다.
</Info>

<Steps>
  <Step title="모델 추가">
    설정 → **AI 모델** 의 **사용자 정의 모델** 항목에서 **+ 모델 추가** 를 클릭합니다.

    <img src="https://mintcdn.com/banyaai/M07ciNHz_BJaV0H1/images/IDE_MODEL_ADD.png?fit=max&auto=format&n=M07ciNHz_BJaV0H1&q=85&s=27cae3b565f7510dbbc6ebc986ae930b" alt="사용자 정의 모델 추가" width="1050" height="734" data-path="images/IDE_MODEL_ADD.png" />
  </Step>

  <Step title="프로바이더 선택">
    **프로바이더** 드롭다운에서 **Google Gemini** 를 고릅니다. 선택하면 **API 엔드포인트**가 자동으로 채워집니다. 이 값은 그대로 두세요.

    <img src="https://mintcdn.com/banyaai/WzAw27WCh1E5UjSP/images/IDE_MODEL_FORM_GEMINI.png?fit=max&auto=format&n=WzAw27WCh1E5UjSP&q=85&s=a95f506381c02d1865dab8bfdfed305d" alt="Gemini 모델 등록 폼" width="755" height="956" data-path="images/IDE_MODEL_FORM_GEMINI.png" />
  </Step>

  <Step title="모델 정보 입력">
    아래 두 항목을 직접 입력합니다.

    | 항목        | 입력할 값                                              |
    | --------- | -------------------------------------------------- |
    | **모델 이름** | `Gemini 3.1 Pro` — 목록에 표시될 이름이므로 자유롭게              |
    | **모델 ID** | `gemini-3.1-pro-preview` — Google이 정한 정확한 값이어야 합니다 |

    <Warning>
      입력창에 흐리게 표시된 예시(`gemini-2.5-pro`)는 예전 모델입니다. 그대로 쓰지 말고 위 값을 직접 입력하세요.
    </Warning>
  </Step>

  <Step title="API 키 붙여넣기 후 저장">
    **API 키** 항목에 1단계에서 복사한 키를 붙여넣습니다. 나머지 항목(인증 방식, 컨텍스트 윈도우, 온도, 추가 헤더 등)은 손대지 말고 기본값 그대로 두고 **저장** 을 클릭합니다.
  </Step>

  <Step title="테스트 후 선택">
    저장한 모델 옆의 **테스트** 를 눌러 **연결 정상** 을 확인하고, **선택** 을 눌러 **✓ 활성** 상태로 만듭니다.

    <img src="https://mintcdn.com/banyaai/M07ciNHz_BJaV0H1/images/IDE_MODEL_TEST.png?fit=max&auto=format&n=M07ciNHz_BJaV0H1&q=85&s=472ae0e9b3c2052f036b5be2fede5cd4" alt="모델 테스트와 선택" width="748" height="275" data-path="images/IDE_MODEL_TEST.png" />

    <Warning>
      저장만 하고 **선택**하지 않으면 모델이 등록만 될 뿐 사용되지 않습니다. 반드시 선택까지 하세요.
    </Warning>
  </Step>
</Steps>

***

## 다른 제공사 사용하기

프로바이더 드롭다운에서 다른 제공사를 고르면 됩니다. 절차는 Gemini와 동일하고, **API 키를 발급받는 곳**만 다릅니다.

| 제공사              | 모델 ID 예시                 |
| ---------------- | ------------------------ |
| OpenAI           | `gpt-4o`                 |
| Anthropic Claude | `claude-opus-4-6`        |
| Google Gemini    | `gemini-3.1-pro-preview` |
| DeepSeek         | `deepseek-chat`          |

<Info>
  모델 ID는 제공사가 새 모델을 내놓을 때마다 바뀝니다. 위 값이 동작하지 않으면 각 제공사의 공식 문서에서 최신 모델 ID를 확인하세요.
</Info>

클라우드(Vertex AI · Azure OpenAI · AWS Bedrock)와 사내 서버(OpenAI 호환 엔드포인트)도 등록할 수 있습니다.

<Tip>
  인터넷 없이 쓰고 싶다면 API 키가 필요 없는 **로컬 모델**을 쓸 수 있습니다. 설정 → AI 모델에서 로컬 모델 서버를 연결하세요.
</Tip>

***

## 문제 해결

<AccordionGroup>
  <Accordion title="채팅에서 답변이 안 옵니다">
    **API Key** 항목이 **개인 API Key** 로 되어 있는데 키를 저장하지 않았거나, 관리자 키가 없는 상태일 수 있습니다. 개인 키를 저장했는지, 저장 후 **저장** 버튼까지 눌렀는지 확인하세요.
  </Accordion>

  <Accordion title="'등록된 키 없음' 으로 표시됩니다">
    관리자 키와 개인 키가 모두 없는 상태입니다. 개인 키를 발급받아 등록하거나, 관리자에게 조직 키 등록을 요청하세요.
  </Accordion>

  <Accordion title="쓰려는 모델이 목록에 없습니다">
    관리자(super)가 그 프로바이더를 켜두지 않았을 수 있습니다. 관리자에게 문의하세요. 로그인 없이 쓰는 독립 실행 환경이라면 [사용자 정의 모델](#4-사용자-정의-모델-직접-등록하기-독립-실행-전용)로 직접 등록할 수 있습니다.
  </Accordion>

  <Accordion title="사용자 정의 모델 테스트에서 '연결 실패'가 나옵니다">
    다음 순서로 확인하세요.

    1. **API 키** — 복사할 때 앞뒤 공백이 섞이지 않았는지 확인하고 다시 붙여넣어 보세요.
    2. **모델 ID** — `gemini-3.1-pro-preview` 처럼 Google이 정한 정확한 값이어야 합니다. 모델 이름(`Gemini 3.1 Pro`)과 혼동하지 마세요.
    3. **API 엔드포인트** — 프로바이더를 다시 선택하면 올바른 값으로 되돌아옵니다.
    4. **네트워크** — 사내 방화벽이 외부 API 호출을 막고 있을 수 있습니다. 관리자에게 문의하세요.
  </Accordion>

  <Accordion title="할당량 초과 오류가 납니다">
    Gemini 무료 사용량을 다 썼을 수 있습니다. Google AI Studio에서 사용량과 결제 설정을 확인하세요.
  </Accordion>
</AccordionGroup>

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="빠른 시작" icon="rocket" href="/getting-started/quickstart">
    바로 첫 요청을 보내고 변경 사항을 승인해 봅니다
  </Card>

  <Card title="조직 연결" icon="building" href="/getting-started/organization">
    팀으로 쓴다면 조직에 가입해 관리자 정책을 적용받습니다
  </Card>
</CardGroup>