PrivateGPT 동작 원리 — 시작 흐름과 모델 발견

PrivateGPT 동작 원리 — 시작 흐름과 모델 발견

PrivateGPT는 "설정 파일 없이 그냥 돌아가는" 것이 매력이에요. 그 뒤에는 시작 시 흐름, 모델 자동 발견, 스마트 기본값 적용이 있어요. 동작 원리를 알면 문제가 생겼을 때도 쉽게 대처할 수 있어요.

출처: https://docs.privategpt.dev/getting-started/how-it-works

시작 흐름

PrivateGPT가 시작되면 다음을 수행해요.

  1. settings.yaml과 PGPT_PROFILES에 지정된 추가 프로필을 로드해요.
  2. LLM 서버에 GET /v1/models를 호출해 모든 반환된 모델을 자동 등록해요.
  3. 발견된 각 모델에 스마트 기본값(128k 컨텍스트 윈도우, 툴 사용, 비전)을 적용해요.
  4. API 서버를 포트 8080에서 시작해요.

기본 사용에는 설정 파일이 필요 없어요 — 자동 발견이 다 처리해요.

모델 발견

시작 시 LLM 서버에 사용 가능한 모델을 질의하고, 반환된 모든 모델을 등록해서 GET /v1/models로 즉시 쓸 수 있게 해줘요. 자동 발견을 끄고 직접 관리하려면:

PGPT_LLM_AUTO_DISCOVER_MODELS=false private-gpt serve

환경변수

변수 기본값 설명
OPENAI_API_BASE — LLM 서버 엔드포인트(필수)
OPENAI_API_KEY (빈 값) 서버가 요구하면 API 키
OPENAI_EMBEDDING_API_BASE OPENAI_API_BASE와 동일 임베딩 서버 엔드포인트
PGPT_PROFILES (없음) 로드할 프로필 이름(쉼표 구분)
PGPT_LLM_AUTO_DISCOVER_MODELS true 시작 시 모델 자동 발견
PORT 8080 리슨 포트

설정 프로필

기본 자동 발견으로 부족할 때는 YAML 프로필을 써요. settings-{name}.yaml 파일을 만들고 PGPT_PROFILES=name으로 로드하고, 모델 발견 스크립트로 프로필을 자동 생성할 수도 있어요.

OPENAI_API_BASE=http://localhost:11434/v1 \
  uv run python scripts/auto_discover_models.py --out settings-model.yaml

더 알아보기

설정 파일·프로필·환경변수 확장의 전체 내용은 Settings & Profiles 문서에서 확인할 수 있어요.