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

# 모델

> 모델 목록 관리, 기본 모델 설정, 모델 순서 지정, 프리셋 가져오기/내보내기

<Info>관리자 › 설정 › 모델</Info>

[연결](/ko/admin/settings/connections)에서 등록한 LLM 프로바이더의 모델 목록을 관리합니다.

* 개별 모델의 활성화/비활성화, 커스터마이징, 표시 순서, 기본 모델 설정을 이 탭에서 제어합니다.

<Frame caption="연결된 모든 모델을 한 곳에서 관리합니다 — 활성화, 커스터마이징, 순서 지정">
  <img src="https://mintcdn.com/cloocus/Or1RjU_AzOVJRxuS/images/admin/settings-models-list.png?fit=max&auto=format&n=Or1RjU_AzOVJRxuS&q=85&s=fdff0e8bf7f234188c58a213c2105658" alt="모델 관리 탭" width="2880" height="1800" data-path="images/admin/settings-models-list.png" />
</Frame>

***

## 모델 목록

Workspace 모델(관리자가 직접 생성/커스텀한 모델)과 Base 모델(연결된 API에서 가져온 시스템 모델)을 합쳐서 표시합니다.

* 목록 상단의 **모델 검색** 입력창으로 이름·ID를 필터링할 수 있습니다.

| 항목                     | 설명                          |
| ---------------------- | --------------------------- |
| **모델명**                | 사용자에게 표시되는 모델 이름            |
| **ID**                 | API 호출 시 사용되는 모델 식별자        |
| **Enabled / Disabled** | 해당 모델의 사용 가능 여부 토글 (Switch) |

각 모델 행에는 이 모델을 참조하는 **에이전트·플로우·평가 개수 배지**(예: `Agents 6`, `Flows 1`, `Evaluations 9`)가 함께 표시되어, 해당 모델이 어디에 쓰이는지 한눈에 파악할 수 있습니다(모델 편집 화면 하단 **Used by**와 동일한 의존성 정보).

### 모델 숨김 (Shift+Click)

모델 목록에서 **Shift 키를 누른 상태**로 모델 행의 아이콘을 클릭하면 숨김/표시 토글이 나타납니다. 숨김 처리된 모델은 `meta.hidden` 상태로 관리되며, 사용자의 모델 선택 목록에서 보이지 않습니다.

<Note>
  숨김(Hidden)과 비활성화(Disabled)는 별개 기능입니다.
  숨김은 모델 선택 목록에서 감추는 것이고, 비활성화는 모델 자체를 사용 불가로 전환합니다.
</Note>

***

## 기본 모델 및 순서 설정

모델 목록 우측 상단의 설정(톱니바퀴) 아이콘을 클릭하면 모델 설정 모달이 열립니다.

| 설정 항목     | 설명                               |
| --------- | -------------------------------- |
| **기본 모델** | 새 채팅 시작 시 자동 선택되는 모델             |
| **모델 순서** | 모델 선택 목록의 표시 순서 (드래그 또는 화살표로 조정) |

***

## 모델 활성화/비활성화

모델별 **Enabled / Disabled** 토글(Switch)로 필요한 모델만 사용자에게 노출할 수 있습니다.

<Note>
  비활성화(Disabled)된 모델은 사용자의 모델 선택 드롭다운에 표시되지 않습니다.
  에이전트의 base model로 지정된 모델은 비활성화해도 에이전트 실행에는 영향이 없습니다.
</Note>

***

## 모델 커스터마이징

모델 행의 **편집(연필) 아이콘**을 클릭하면 해당 모델을 커스터마이징할 수 있습니다.

<Accordion title="커스터마이징 항목" icon="sliders">
  | 설정                                      | 설명                                                                   |
  | --------------------------------------- | -------------------------------------------------------------------- |
  | **모델 이름 / ID**                          | 사용자에게 표시되는 이름과 API 호출용 식별자                                           |
  | **모델 이미지**                              | 모델 아바타 이미지 변경/초기화                                                    |
  | **작업 프롬프트** (Task Prompt)               | 기본 시스템 프롬프트 — 역할·행동·제약을 서술 (비우면 기본값 사용). 우측 **AI** 버튼으로 초안을 다듬을 수 있음 |
  | **답변 포맷 프롬프트** (Response Format Prompt) | 응답의 마크다운 스타일·구조·톤·길이 지정 (비우면 기본 형식). 우측 **AI** 버튼 제공                 |
  | **고급 매개변수** (Advanced Params)           | Temperature, Top P, Top K, Stop 토큰 등 (`고급 매개변수 > 표시`로 펼침)            |
  | **가드레일**                                | 이 모델에 적용할 가드레일 연결                                                    |
  | **기능** (Capabilities)                   | 웹 검색, 이미지 생성 등 활성화                                                   |
  | **접근 권한** (Access)                      | 특정 그룹/사용자에게만 노출                                                      |
</Accordion>

<Note>
  **지식 기반·데이터베이스·도구·용어집 연결과 자동 평가는 에이전트 전용**입니다. 관리자 모델 편집에서는 제공되지 않으며, [워크스페이스 > 에이전트](/ko/workspace/agents)에서 설정합니다. 모델 편집에서 런타임에 적용되는 리소스는 **가드레일**뿐입니다.
</Note>

<Note>
  모델을 커스터마이징하면 해당 모델에 대한 **Workspace 설정 레코드**가 생성됩니다. 이것은 에이전트와 달리 기반 모델을 직접 수정하는 것이 아니라 **오버라이드 설정**을 추가하는 개념입니다.
</Note>

***

## 사용자에게 노출되는 모델 제어

| 메커니즘               | 효과                  | 설정 위치                |
| ------------------ | ------------------- | -------------------- |
| **활성화/비활성화** (토글)  | 비활성 → 모델 선택 목록에서 제외 | 모델 행 토글              |
| **숨기기** (Shift+클릭) | 숨김 → 모델 선택 목록에서 제외  | 모델 행 Shift+아이콘 또는 메뉴 |
| **기본 모델**          | 새 채팅 시 자동 선택        | 설정 모달                |
| **표시 순서**          | 모델 선택 드롭다운 순서       | 설정 모달 (드래그)          |
| **접근 권한**          | 특정 그룹/사용자만 접근       | 모델 편집 > 접근 권한        |

<Tip>
  일시적으로 목록에서만 감추려면 **숨기기**, 사용을 완전히 차단하려면 **비활성화**를 사용하세요. (둘의 차이는 위 "모델 숨김" 설명 참고)
</Tip>

***

## 토큰 제한

모델별 일일 토큰 사용량을 제한해 AI 사용 비용을 관리합니다.

* 모델 목록 **우측 상단의 `토큰 제한` 버튼**으로 전역 기본값을 설정합니다.
* **각 모델 행의 `토큰 제한` 드롭다운**으로 모델별 한도를 설정합니다.

### 전역 토큰 제한 (토큰 제한 버튼)

| 항목              | 설명                                                           |
| --------------- | ------------------------------------------------------------ |
| **사용량 제한 활성화**  | 토큰 제한 기능 전체 ON/OFF                                           |
| **기본 일별 토큰 제한** | 모델 행에 별도 한도가 설정되지 않은 모든 모델에 적용 (`0` = 무제한, 비어있음 = 전역 설정을 따름) |
| **초과 시 동작**     | **경고**(메시지만 표시하고 사용 허용) 또는 **차단**(추가 사용 차단)                  |

### 모델별 한도

각 모델 행의 **`토큰 제한` 드롭다운**에서 해당 모델의 일일 한도를 개별 지정합니다. 지정하지 않은 모델은 위의 기본 일별 토큰 제한을 따릅니다.

<Note>
  관리자(Admin) 역할은 토큰 제한 체크에서 제외됩니다. 제한은 전역·사용자·그룹·조직 4단계로 설정 가능하며, 여러 곳에 설정되면 **가장 관대한(높은) 값**이 적용됩니다. 사용자별·모델별 사용 현황은 [사용자 관리](/ko/admin/users#사용량-제한)의 사용량 탭에서 확인합니다.
</Note>

***

## Ollama 모델 관리

모델 목록 상단의 **다운로드 아이콘**을 클릭하면 Ollama 모델 관리 모달이 열립니다.

| 기능             | 설명                                   |
| -------------- | ------------------------------------ |
| **Pull**       | Ollama 모델 레지스트리에서 모델 다운로드 (최대 3개 동시) |
| **Update All** | 모든 Ollama 모델을 최신 버전으로 업데이트           |
| **Upload**     | GGUF 파일 업로드 또는 URL에서 다운로드하여 모델 생성    |
| **Delete**     | Ollama 모델 삭제                         |

<Note>
  Ollama 인스턴스가 여러 개 연결되어 있으면 관리할 인스턴스를 먼저 선택해야 합니다.
</Note>

***

## 모델 프리셋 Import / Export

모델 설정을 JSON 형태로 백업하고 복원할 수 있습니다.

* 이 기능은 **관리자 전용**입니다.

| 기능                 | 설명                       |
| ------------------ | ------------------------ |
| **Import Presets** | JSON 파일에서 모델 프리셋 복원      |
| **Export Presets** | 현재 모델 프리셋을 JSON 파일로 다운로드 |
| **단일 Export**      | 모델 행의 더보기 메뉴(⋯) > Export |

<Warning>
  Import 시 기존 모델 설정이 덮어씌워집니다. 반드시 Export로 백업 후 진행하세요.
</Warning>

<AccordionGroup>
  <Accordion title="Import 시 어떤 모델이 가져와지나요?" icon="circle-question">
    `base_model_id`가 null인 모델(Workspace 커스텀 설정)만 Import 됩니다. 에이전트(`base_model_id`가 다른 모델을 참조)는 이 탭에서 Import되지 않습니다 — 에이전트는 워크스페이스 > 에이전트에서 별도로 Import하세요.
  </Accordion>

  <Accordion title="모든 모델 설정을 초기화하려면?" icon="circle-question">
    설정 모달(톱니바퀴) 하단의 **Reset All Models** 버튼을 클릭하면 모든 Workspace 커스텀 설정이 삭제됩니다. 연결된 기본 모델 목록은 유지되지만, 이름/설명/프롬프트 등 커스터마이징 내용이 모두 초기화됩니다.
  </Accordion>
</AccordionGroup>

***

## 관련 페이지

<Columns cols={3}>
  <Card title="연결" icon="plug" href="/ko/admin/settings/connections">
    LLM 프로바이더 API 연결 구성
  </Card>

  <Card title="에이전트" icon="robot" href="/ko/workspace/agents">
    모델 위에 지식 기반·도구·가드레일을 결합한 AI 어시스턴트
  </Card>

  <Card title="사용량" icon="chart-line" href="/ko/monitoring/usage">
    모델별 토큰 사용량 및 비용 분석
  </Card>
</Columns>