> ## 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.

# 연결

> AI 모델 제공자(OpenAI, Azure OpenAI, Ollama) 연결 및 클라우드 스토리지를 구성합니다.

<Info>관리자 › 설정 › 연결</Info>

AI 모델을 사용하려면 먼저 LLM 프로바이더와의 연결을 설정해야 합니다.

* 여러 프로바이더를 동시에 연결해 사용자가 다양한 모델을 선택하도록 구성할 수 있습니다.
* 여기서 연결한 프로바이더의 모델이 [모델](/ko/admin/settings/models) 목록에 노출됩니다.

<Frame caption="관리자 > 설정 > 연결에서 LLM 프로바이더, 클라우드 계정, 스토리지를 구성합니다">
  <img src="https://mintcdn.com/cloocus/Or1RjU_AzOVJRxuS/images/admin/settings-connections-full.png?fit=max&auto=format&n=Or1RjU_AzOVJRxuS&q=85&s=190ea4ee467cd3770931fcea2ff972c9" alt="연결 설정 탭" width="2880" height="1800" data-path="images/admin/settings-connections-full.png" />
</Frame>

***

## AI Provider

모든 LLM 프로바이더(OpenAI, Azure OpenAI, Azure AI Foundry, Vertex AI 등)의 연결을 **AI Provider** 섹션 하나에서 통합 관리합니다.

* **AI Provider 연결 관리** 목록에 각 연결이 나열됩니다.
* 여러 연결을 동시에 구성해 부하를 분산하거나 다양한 모델을 노출할 수 있습니다.

<Steps>
  <Step title="연결 추가">
    **AI Provider 연결 관리**의 **"+" 버튼**을 클릭하고 프로바이더 유형을 선택합니다.
  </Step>

  <Step title="연결 정보 입력">
    연결 Modal에서 API Base URL, API Key를 입력합니다.
  </Step>

  <Step title="연결 확인">
    저장 후 모델 목록이 자동으로 갱신되는지 확인합니다.
  </Step>
</Steps>

<Tabs>
  <Tab title="OpenAI">
    | 설정 항목            | 설명                             |
    | ---------------- | ------------------------------ |
    | **API Base URL** | `https://api.openai.com/v1`    |
    | **API Key**      | OpenAI에서 발급받은 키 (`sk-...`)     |
    | **Prefix ID**    | 모델 ID 접두사 (선택 — 다중 연결 시 충돌 방지) |
    | **Model IDs**    | 수동 지정 (비우면 자동 조회)              |
  </Tab>

  <Tab title="Azure OpenAI">
    | 설정 항목            | 설명                                   |
    | ---------------- | ------------------------------------ |
    | **API Base URL** | `https://{리소스명}.openai.azure.com/`   |
    | **API Key**      | Azure Portal에서 발급받은 키                |
    | **API Version**  | API 버전 (필수, 예: `2024-02-15-preview`) |
    | **Prefix ID**    | 모델 ID 접두사 (선택)                       |
    | **Model IDs**    | 배포된 모델명 수동 지정                        |
  </Tab>

  <Tab title="Azure AI Foundry">
    | 설정 항목            | 설명                                          |
    | ---------------- | ------------------------------------------- |
    | **API Base URL** | `https://{프로젝트명}.{리전}.models.ai.azure.com/` |
    | **API Key**      | Azure AI Foundry에서 발급받은 키                   |
    | **API Version**  | API 버전 (기본: `2024-05-01-preview`)           |
    | **Prefix ID**    | 모델 ID 접두사 (선택)                              |
    | **Model IDs**    | 수동 지정 (비우면 연결 확인 시 자동 조회)                   |

    <Accordion title="Azure OpenAI와 AI Foundry의 차이">
      |                          | Azure OpenAI                             | AI Foundry                          |
      | ------------------------ | ---------------------------------------- | ----------------------------------- |
      | **엔드포인트 형식**             | `{url}/openai/deployments/{모델}/...`      | `{url}/openai/v1/...`               |
      | **모델 식별**                | 배포(deployment) 이름                        | 모델 ID                               |
      | **인증** (입력은 둘 다 API Key) | 전송 시 `api-key` + `Authorization: Bearer` | 전송 시 `Authorization: Bearer`만       |
      | **용도**                   | Azure에서 OpenAI 모델 전용                     | Azure AI에 배포된 다양한 모델 (OpenAI + OSS) |

      Azure OpenAI는 모델을 **배포 단위로** 관리하고, AI Foundry는 **모델 카탈로그**에서 바로 접근합니다. 이미 Azure OpenAI를 사용 중이라면 **별도로 AI Foundry를 추가할 필요는 없습니다** — OSS 모델이나 AI Foundry 전용 모델이 필요할 때 추가하세요.
    </Accordion>
  </Tab>

  <Tab title="Vertex AI">
    | 설정 항목          | 설명                                            |
    | -------------- | --------------------------------------------- |
    | **Project ID** | Google Cloud 프로젝트 ID (필수)                     |
    | **Location**   | 리전 (기본: `us-central1`)                        |
    | **인증**         | Global GCP Key 또는 Custom Service Account JSON |

    연결 확인 시 사용 가능한 모델 목록이 자동으로 표시됩니다.
  </Tab>
</Tabs>

### 연결 설정 공통 사항

각 연결에는 다음 공통 기능이 있습니다:

| 기능            | 설명                                         |
| ------------- | ------------------------------------------ |
| **연결 확인**     | 설정 모달의 확인 버튼으로 API 접속 테스트                  |
| **Prefix ID** | 여러 연결의 모델명이 겹칠 때 `{prefix}.{model}` 형태로 구분 |
| **활성화/비활성화**  | 연결별 토글로 일시 중지 가능 (삭제하지 않고)                 |
| **Model IDs** | 수동 지정 시 해당 모델만 노출. 비우면 API에서 자동 조회         |

<Tip>
  동일 프로바이더에 **여러 연결**을 추가하면 모델 목록이 자동으로 병합됩니다. 예를 들어 Azure OpenAI 연결 2개(미국/한국 리전)를 추가하면 양쪽 리전의 모델이 모두 표시됩니다. 이때 **Prefix ID**로 구분하세요.
</Tip>

***

## Ollama API 연결

로컬 또는 사내 서버의 Ollama 인스턴스와 연결합니다.

| 설정 항목        | 설명           | 예시                       |
| ------------ | ------------ | ------------------------ |
| **Base URL** | Ollama 서버 주소 | `http://localhost:11434` |

여러 서버를 추가하여 부하를 분산할 수 있습니다. Ollama는 외부 네트워크 없이 완전한 데이터 프라이버시를 보장합니다.

***

## 직접 연결 (Direct Connections)

관리자가 설정한 연결 외에, **사용자가 개인 API 키로 LLM에 직접 연결**하도록 허용하는 기능입니다.

| 설정 항목        | 설명                | 기본값 |
| ------------ | ----------------- | :-: |
| **직접 연결 허용** | 사용자별 개인 API 연결 허용 | 활성화 |

활성화하면 사용자가 **개인 설정 > Connections**에서 OpenAI 호환 API를 추가할 수 있습니다.

<Note>
  직접 연결은 **OpenAI 호환 API만** 지원합니다 (Ollama 미지원). 사용자가 연결하는 API 서버에서 CORS 설정이 올바르게 구성되어 있어야 합니다.
</Note>

***

## Cloud Accounts

글로벌 클라우드 서비스 계정을 설정합니다.

* 여기서 설정한 Service Account Key는 개별 기능(TTS·STT·이미지 등)에서 별도 키가 없을 때 폴백으로 사용됩니다.

| 제공자              | 설정 항목                      |
| ---------------- | -------------------------- |
| **Google Cloud** | Service Account Key (JSON) |

<Note>
  Service Account Key를 비워두면 Application Default Credentials(ADC)를 사용합니다.
</Note>

***

## Google Workspace 통합

사용자가 채팅에서 **Gmail 발송·캘린더 일정 등록·Drive 문서 생성**을 사용하도록 허용합니다.

* 각 기능은 개별 토글로 제어하며, 실제 사용에는 **사용자별 Google OAuth 연결**과 **그룹 권한**이 모두 필요합니다.
* 안전을 위해 기본값은 모두 비활성화입니다.

| 토글           | 사용 범위(scope)      | 심사 요건                                        |
| ------------ | ----------------- | -------------------------------------------- |
| **Gmail 통합** | `gmail.send`      | Sensitive scope — Google App verification 필요 |
| **캘린더 통합**   | `calendar.events` | Restricted scope — CASA Tier 2 보안 감사 필요      |
| **Drive 통합** | `drive`           | Restricted scope — CASA Tier 2 보안 감사 필요      |

<Warning>
  Gmail·캘린더·Drive는 Google의 민감·제한 범위(scope)에 해당합니다. 프로덕션 배포 전 App verification 또는 CASA 심사를 완료해야 정상 동작합니다.
</Warning>

### 사용 흐름

관리자가 토글을 켜는 것은 시작일 뿐이며, 사용자별 연결까지 마쳐야 채팅에서 실제로 쓸 수 있습니다.

```mermaid theme={null}
flowchart LR
    A["관리자: 토글 ON"] --> B["사용자: Google OAuth 연결"]
    B --> C["채팅에서 도구 첨부"]
    C --> D["자연어로 질의·실행"]
```

<Steps>
  <Step title="채팅에서 Google 도구 첨부">
    연결이 완료되면 채팅 입력창에 **Gmail · 구글 캘린더 · Google Drive** 도구가 칩으로 첨부됩니다.

    <Frame caption="채팅 입력창에 첨부된 Google 도구">
      <img src="https://mintcdn.com/cloocus/4H2vVXhPjOITz4vh/images/admin/google-workspace-attach.png?fit=max&auto=format&n=4H2vVXhPjOITz4vh&q=85&s=d716fe23a0029724cf1a93222e855ff9" alt="채팅 입력창에 Gmail·구글 캘린더·Google Drive 도구가 칩으로 첨부된 상태" width="4500" height="2700" data-path="images/admin/google-workspace-attach.png" />
    </Frame>
  </Step>

  <Step title="자연어로 질의·실행">
    첨부된 도구 범위 안에서 자연어로 요청하면 에이전트가 해당 Google 서비스를 조회·실행해 응답합니다.

    <Frame caption="캘린더 일정 조회 질의응답">
      <img src="https://mintcdn.com/cloocus/4H2vVXhPjOITz4vh/images/admin/google-workspace-answer.png?fit=max&auto=format&n=4H2vVXhPjOITz4vh&q=85&s=a97f0579ae0ec9464fe535cf02d2981e" alt="오늘 캘린더 일정을 묻는 질문에 에이전트가 캘린더를 조회해 응답한 화면" width="4500" height="2700" data-path="images/admin/google-workspace-answer.png" />
    </Frame>
  </Step>
</Steps>

***

## Image Attachment Mode

채팅에 첨부된 이미지의 처리 및 저장 방식을 설정합니다.

| 설정 항목                 | 설명                                              | 기본값             |
| --------------------- | ----------------------------------------------- | --------------- |
| **Image Upload Mode** | Base64 Inline 또는 Cloud Storage                  | `Base64 Inline` |
| **Storage Provider**  | Local, AWS S3, Azure Blob, Google Cloud Storage | `Local`         |

<Tabs>
  <Tab title="AWS S3">
    | 설정 항목                 | 설명                |
    | --------------------- | ----------------- |
    | **Bucket Name**       | S3 버킷 이름          |
    | **Region**            | AWS 리전            |
    | **Endpoint URL**      | 커스텀 Endpoint (선택) |
    | **Access Key ID**     | 인증 키 ID           |
    | **Secret Access Key** | 비밀 키              |
    | **Key Prefix**        | 파일 경로 접두사 (선택)    |
  </Tab>

  <Tab title="Azure Blob">
    | 설정 항목                | 설명                          |
    | -------------------- | --------------------------- |
    | **Storage Endpoint** | Azure Blob Storage Endpoint |
    | **Container Name**   | 컨테이너 이름                     |
    | **Storage Key**      | 인증 키                        |
  </Tab>

  <Tab title="Google Cloud Storage">
    | 설정 항목              | 설명                                       |
    | ------------------ | ---------------------------------------- |
    | **Bucket Name**    | GCS 버킷 이름                                |
    | **Authentication** | Global Google Cloud Key 또는 Custom Key 선택 |
  </Tab>
</Tabs>

***

## Shared Storage (파일 업로드)

문서, PDF 등 업로드 파일의 저장 위치를 설정합니다.

* Image Attachment Mode와 동일한 스토리지 제공자 옵션을 지원합니다.

| 설정 항목                     | 설명                                              | 기본값     |
| ------------------------- | ----------------------------------------------- | ------- |
| **File Storage Provider** | Local, AWS S3, Azure Blob, Google Cloud Storage | `Local` |

<Note>
  스토리지 설정 변경 후 **"Test"** 버튼으로 연결 상태를 반드시 확인하세요.
</Note>

***

## 관련 페이지

<Columns cols={3}>
  <Card title="모델" icon="robot" href="/ko/admin/settings/models">
    연결된 모델 활성화/비활성화 및 Workspace 모델 설정
  </Card>

  <Card title="문서" icon="file-lines" href="/ko/admin/settings/documents">
    임베딩 엔진 및 RAG 파이프라인 설정
  </Card>

  <Card title="코드 게이트웨이" icon="code" href="/ko/admin/code-gateway">
    코딩 도구용 LLM 프록시 설정
  </Card>
</Columns>