3단계 키 계층
플랫폼은 LLM API 키를 3단계로 관리합니다. 우선순위는 개인 > 그룹 > 전역 순입니다.
| 계층 | 경로 | 용도 |
|---|---|---|
| 개인 키 | /keys (개인) | 개인적으로 사용할 API 키 |
| 그룹 키 | /keys (그룹) — 그룹 관리자만 탭 노출 | 그룹 멤버가 함께 사용하는 키 |
| 전역 키 | /admin/keys (관리자 대시보드) | 모든 사용자가 사용할 수 있는 키 |
[!NOTE]
- 사용자가 대화할 때, 등록한 개인 키가 우선 사용됩니다. 없으면 그룹 키, 그것도 없으면 전역 키로 폴백합니다.
지원 프로바이더
LLM 키로 등록할 수 있는 프로바이더는 다음과 같습니다.
| 프로바이더 | 식별자 | 비고 |
|---|---|---|
| OpenAI | openai | ChatGPT 계열 |
| Anthropic | anthropic | Claude 계열 |
google | Gemini 계열 | |
| z.ai | zai | GLM 계열 |
| z.ai (Coding Plan) | zai | 코딩 플랜 전용 시드 키 |
| OpenRouter | openrouter | 여러 사업자 모델을 하나의 키로 · openrouter.ai에서 키 발급 |
| vLLM (자체 호스팅) | vllm | 추론 서버 · 커스텀 Base URL 지원 |
| Ollama (자체 호스팅) | ollama | 로컬 LLM 런타임 · 커스텀 Base URL 지원 |
| llama.cpp (자체 호스팅) | llamacpp | llama-server 추론 서버 · 커스텀 Base URL 지원 |
| SGLang (자체 호스팅) | sglang | 추론 서버 · 커스텀 Base URL 지원 |
vLLM · Ollama · llama.cpp · SGLang 은 직접 실행 중인 서버 주소를 커스텀 Base URL 로 지정합니다. 기본값은 순서대로 http://localhost:8000/v1 · http://localhost:11434/v1 · http://localhost:8080/v1 · http://localhost:30000/v1 이며, 목록에 없는 다른 OpenAI 호환 엔드포인트는 vLLM 프로바이더로 연결하면 됩니다.
[!NOTE] localhost · 사설망 주소는 보안 정책상 기본 차단됩니다. 서버 관리자가 해당 주소를 허용 목록(
PROVIDER_INTERNAL_ORIGINS)에 추가해야 연결할 수 있습니다.
자체 호스팅 서버를 인증 없이 실행한 경우(예: --api-key 미지정)에는 API 키 칸에 아무 값이나 입력해도 됩니다 — Ollama 는 키를 무시하고, 나머지는 더미 값으로 동작합니다.
키 유형
/keys 에서 등록하는 키는 용도에 따라 세 종류입니다.
| 유형 | 용도 |
|---|---|
| LLM | 대화·워크플로우 등 LLM 호출 |
| 임베딩 (Embedding) | 지식 베이스 문서 임베딩 (OpenAI · Google · OpenAI 호환) |
| 리랭커 (Reranker) | 지식 베이스 재순위화 (OpenAI 호환) |
키 등록
/keys에서 키 추가 를 클릭합니다.- 키 유형과 프로바이더를 선택합니다.
- API 키 와 필요시 커스텀 Base URL · 라벨 등을 입력합니다.
- 저장합니다.
[!IMPORTANT]
- 등록된 키는 서버에서 암호화되어 저장됩니다.
- 키 원문은 어떤 화면에서도 다시 표시되지 않으며, 복호화는 시스템이 키를 사용할 때만 내부적으로 이루어집니다.
- 키 원문을 잊어버렸다면 삭제 후 다시 등록해야 합니다.
키 편집 · 삭제
등록한 키는 목록에서 언제든 수정하거나 삭제할 수 있습니다.
- 편집 — 라벨 변경, 키 활성/비활성 전환, 새 API 키로 교체. 자체 호스팅(vLLM · Ollama · llama.cpp · SGLang) 및 OpenAI 호환 키는 추론 강도(reasoning effort)·비전(vision) 지원 여부도 설정할 수 있습니다.
- 삭제 — 더 이상 사용하지 않는 키는 목록에서 바로 삭제합니다.
모델 관리
각 키에 대해 사용할 모델을 개별적으로 활성화/비활성화 할 수 있습니다.
개인/그룹/전역 키 모델 관리 — 프로바이더의 모델을 활성화/비활성화합니다
- 모델 새로고침 버튼으로 프로바이더에서 제공하는 모델 카탈로그를 자동 발견합니다.
- 특정 모델만 노출하도록 토글을 끌 수 있습니다.
- 전체 활성화 / 전체 비활성화 버튼으로 모델을 한 번에 제어할 수 있습니다.
연결 테스트
연결 테스트 기능으로 입력한 키가 실제로 동작하는지 확인할 수 있습니다.
관리자 전용
- 전역 키 등록/수정/삭제는 관리자만 가능합니다. 관리자 대시보드의 전역 API 키(
/admin/keys)에서 관리합니다. - 전역 기본 모델 설정 — 모든 사용자의 기본 모델 지정.
/admin/keys에서 모델의 "모든 사용자의 기본 모델로 설정" 버튼으로 지정합니다. - 가입 활성화/비활성화 — 회원가입 허용 여부
자세한 내용은 관리자 가이드 를 참고하세요.
다음 단계
- 프로필 & 환경설정 — 기본 모델/에이전트 설정
- 관리자 가이드 — 전역 키·전역 기본 모델