Custom 모델

Custom 모델은 OpenAI 호환 Chat Completions API를 제공하는 서버에 직접 연결한 모델입니다. llama.cpp, Ollama, LM Studio 같은 로컬 서버나 모델 카탈로그에 없는 외부 제공자를 쓸 때 등록합니다.

연결하기

등록한 모델은 버틀러 모델의 모델 목록에서 고를 수 있습니다. 기본 모델을 고르는 방법은 클라우드 모델을 참고합니다.

모델 ID 직접 입력

서버가 모델 목록을 제공하지 않거나 모델 찾기가 실패해도 등록할 수 있습니다. API 기본 URL을 입력한 뒤 모델 ID, 표시 이름, 최대 컨텍스트를 직접 채우고 모델 등록을 누릅니다. 최대 컨텍스트의 기본값은 16384입니다.

API 기본 URL 규칙

• http 또는 https 주소만 쓸 수 있습니다. 스킴 없이 입력하면 http://로 연결합니다.
• 경로 없이 호스트만 입력하면 끝에 /v1을 붙입니다. 예: http://localhost:8080 → http://localhost:8080/v1
• 경로를 포함해 입력하면 그 경로를 그대로 API 주소로 씁니다.
• URL에 사용자 이름이나 비밀번호를 넣을 수 없습니다. 인증이 필요하면 API 키 (선택) 칸을 씁니다.

모델 찾기 동작

• 모델 찾기는 API 주소의 /models를 요청해 모델 목록을 가져옵니다. API 키를 입력했다면 Bearer 토큰으로 함께 보냅니다.
• 모델 목록을 가져오지 못하거나 서버가 모델을 하나도 돌려주지 않으면 Custom 모델 검색 실패가 표시됩니다. 이때는 모델 ID를 직접 입력해 등록합니다.
• 서버가 모델의 컨텍스트 길이를 알려 주면 그 값을 최대 컨텍스트에 채우고, 알 수 없으면 16384를 채웁니다.

설정 더보기

설정 더보기를 누르면 다음 항목이 나타납니다.

• API 유형 — OpenAI-compatible로 고정되어 있습니다.
• 플랫폼 힌트 — llama.cpp, Ollama, LM Studio, Custom OpenAI 호환 중에서 고릅니다. 기본값은 Custom OpenAI 호환입니다. Butler는 API 표준을 우선 사용하고 플랫폼은 호환성 힌트로만 씁니다. llama.cpp를 고르면 모델 찾기가 서버 실행 설정의 컨텍스트 크기(n_ctx)를 함께 읽어 옵니다.

인증이 필요한 서버

API 키 (선택) 칸에 입력한 키는 모델마다 따로 저장되고, 요청할 때 Bearer 토큰으로 보냅니다.

• 키는 ~/.butler/auth/custom-model-credentials.json에 저장됩니다. 파일 권한은 소유자만 읽고 쓸 수 있게 설정됩니다.
• 편집할 때 키 칸을 비워 두면 기존 키를 그대로 씁니다.
• API 키 제거를 누르고 저장하면 키를 지웁니다.
• 모델을 삭제하면 그 모델의 키도 함께 지워집니다.

편집과 삭제

모델 관리의 등록된 모델에서 모델을 관리합니다.

• 편집 — 값을 고친 뒤 모델 저장을 누릅니다. 저장하지 않고 화면을 벗어나려고 하면 확인 창이 나타납니다.
• 삭제 — 확인 창에서 삭제를 누르면 선택 가능한 모델 목록에서 빠집니다.

로컬 추론 예산

추론 강도를 단계별로 지원하지 않는 Custom 모델을 버틀러 모델로 고르면 버틀러 모델 섹션에 로컬 추론 예산이 나타납니다. 선택한 로컬 모델의 최대 출력 토큰 중 추론에 사용할 비율을 퍼센트로 지정합니다.

주의 사항

관련 문서