연결 - Cloosphere Guide

관리자 › 설정 › 연결

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

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

연결 설정 탭 — 관리자 > 설정 > 연결에서 LLM 프로바이더, 클라우드 계정, 스토리지를 구성합니다

AI Provider

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

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

연결 추가

AI Provider 연결 관리의 ”+” 버튼을 클릭하고 프로바이더 유형을 선택합니다.

연결 정보 입력

연결 Modal에서 API Base URL, API Key를 입력합니다.

연결 확인

저장 후 모델 목록이 자동으로 갱신되는지 확인합니다.

OpenAI
Azure OpenAI
Azure AI Foundry
Vertex AI

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

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

설정 항목	설명
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	수동 지정 (비우면 연결 확인 시 자동 조회)

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 전용 모델이 필요할 때 추가하세요.

설정 항목	설명
Project ID	Google Cloud 프로젝트 ID (필수)
Location	리전 (기본: `us-central1`)
인증	Global GCP Key 또는 Custom Service Account JSON

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

연결 설정 공통 사항

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

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

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

Ollama API 연결

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

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

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

직접 연결 (Direct Connections)

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

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

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

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

Cloud Accounts

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

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

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

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

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 보안 감사 필요

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

사용 흐름

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

채팅에서 Google 도구 첨부

연결이 완료되면 채팅 입력창에 Gmail · 구글 캘린더 · Google Drive 도구가 칩으로 첨부됩니다.

채팅 입력창에 Gmail·구글 캘린더·Google Drive 도구가 칩으로 첨부된 상태 — 채팅 입력창에 첨부된 Google 도구

자연어로 질의·실행

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

오늘 캘린더 일정을 묻는 질문에 에이전트가 캘린더를 조회해 응답한 화면 — 캘린더 일정 조회 질의응답

Image Attachment Mode

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

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

AWS S3
Azure Blob
Google Cloud Storage

설정 항목	설명
Bucket Name	S3 버킷 이름
Region	AWS 리전
Endpoint URL	커스텀 Endpoint (선택)
Access Key ID	인증 키 ID
Secret Access Key	비밀 키
Key Prefix	파일 경로 접두사 (선택)

설정 항목	설명
Storage Endpoint	Azure Blob Storage Endpoint
Container Name	컨테이너 이름
Storage Key	인증 키

설정 항목	설명
Bucket Name	GCS 버킷 이름
Authentication	Global Google Cloud Key 또는 Custom Key 선택

Shared Storage (파일 업로드)

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

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

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

스토리지 설정 변경 후 “Test” 버튼으로 연결 상태를 반드시 확인하세요.

모델

연결된 모델 활성화/비활성화 및 Workspace 모델 설정

문서

임베딩 엔진 및 RAG 파이프라인 설정

코드 게이트웨이

코딩 도구용 LLM 프록시 설정

​AI Provider

​연결 설정 공통 사항

​Ollama API 연결

​직접 연결 (Direct Connections)

​Cloud Accounts

​Google Workspace 통합

​사용 흐름

​Image Attachment Mode

​Shared Storage (파일 업로드)

​관련 페이지

모델

문서

코드 게이트웨이

AI Provider

연결 설정 공통 사항

Ollama API 연결

직접 연결 (Direct Connections)

Cloud Accounts

Google Workspace 통합

사용 흐름

Image Attachment Mode

Shared Storage (파일 업로드)

관련 페이지