PrivateGPT 설정과 프로필 — settings.yaml로 제어하기

PrivateGPT는 YAML 설정 파일로 구성돼요. 기본 파일은 프로젝트 루트의 settings.yaml이고, 필요에 따라 프로필을 겹쳐서 기본 설정을 확장·재정의할 수 있어요. 환경변수 확장 문법 덕분에 민감한 값(포트 등)을 외부에서 주입하기도 쉬워요.

출처: https://docs.privategpt.dev/configuration/settings

프로필

프로필은 settings-{name}.yaml이라는 이름의 파일이에요. 시작 시 PGPT_PROFILES로 하나 이상을 활성화해요. 여러 프로필은 순서대로 병합되고, 나중 것일수록 앞의 것을 덮어써요.

PGPT_PROFILES=model,local private-gpt serve

이것은 settings.yaml을 로드한 뒤 settings-model.yaml, settings-local.yaml을 순서대로 병합해요. 대표적인 용도는 make auto-discover-models로 생성한 settings-model.yaml이 LLM·임베딩 모델을 정의하고, 기본 설정을 건드리지 않는 거예요.

환경변수 확장

설정 파일의 어떤 값이든 환경변수를 참조할 수 있어요.

server:
  port: ${PORT:8080}

문법은 ${VARIABLE_NAME:default_value}예요. 변수가 없으면 기본값을 써요. 기본값이 없는 변수는 설정 시 오류를 냅니다.

설정 폴더

기본적으로 설정 파일은 프로젝트 루트에서 찾아요. 바꾸려면:

PGPT_SETTINGS_FOLDER=/path/to/settings private-gpt serve

데이터 설정 예

PDF 인제스천 시 기본 리더(예: Docling)가 의미 있는 텍스트를 추출하지 못하면, 비전 리더(VLM 기반)로 재시도할지 PGPT_ENABLE_VISION_FALLBACK으로 제어할 수 있어요.

data:
  enable_vision_fallback: ${PGPT_ENABLE_VISION_FALLBACK:false}

이 기능은 멀티모달 모델이 하나 이상 설정돼 있어야 해요.

더 알아보기

모델을 세부 설정하는 토크나이저·컨텍스트 윈도우·샘플링 파라미터 조정은 Model Configuration 문서에서 확인할 수 있어요.