로컬, 자체 호스팅, 커스텀 엔드포인트

이 페이지에서는 직접 호스팅하는 모델 서버(Ollama, llama.cpp, LM Studio, vLLM, SGLang, Osaurus)에 Revka를 연결하는 방법과, OpenAI 또는 Anthropic 호환 API에 사용할 수 있는 두 가지 “직접 엔드포인트 지정” 프리픽스(custom: 및 anthropic-custom:)를 설명합니다. 로컬 추론, 에어갭 배포, 네트워크 내 자체 GPU 서버, 또는 기명 프로바이더가 지원하지 않는 게이트웨이·프록시가 필요할 때 활용하세요.

전체 프로바이더 목록 및 자격 증명 확인 순서는 프로바이더 카탈로그를 참고하세요. 느린 LLM 튜닝(타임아웃, 루프 감지)은 라우팅, 안정성 및 튜닝과 설정: 프로바이더, 에이전트 및 라우팅의 [pacing] 섹션을 참고하세요.

Ollama

Ollama는 퍼스트파티 프로바이더입니다. Ollama의 네이티브 /api/chat 엔드포인트(OpenAI 호환 /v1/chat/completions 아님)를 사용하며, 비전, 스트리밍, 선택적 thinking 토글을 지원합니다.

default_provider = "ollama"
default_model    = "llama3.2"

기본 베이스 URL은 http://localhost:11434입니다. 원격 인스턴스에 연결하려면 api_url(또는 REVKA_PROVIDER_URL 환경 변수)로 재정의하세요:

default_provider = "ollama"
api_url          = "http://10.0.0.1:11434"
default_model    = "llama3.2"

api_url 끝에 /api 또는 /api/chat이 있으면 자동으로 정규화되므로, https://ollama.example.com/api/와 https://ollama.example.com은 동일하게 동작합니다.

필드	타입	기본값	설명
api_url	string	http://localhost:11434	Ollama 베이스 URL; REVKA_PROVIDER_URL 환경 변수로도 설정 가능
OLLAMA_API_KEY	환경 변수	없음	보호된/원격 엔드포인트용 Bearer 토큰
[runtime] reasoning_enabled	bool	미설정	Ollama에 think: true/false로 전달

인증

로컬 엔드포인트(localhost, 127.0.0.1, ::1)의 경우, 키가 설정되어 있더라도 Revka는 Authorization 헤더를 전송하지 않습니다. 원격 엔드포인트에서 OLLAMA_API_KEY(또는 api_key)가 있으면 Bearer 토큰으로 전송됩니다.

클라우드 모델

모델 이름이 :cloud로 끝나는 경우(예: llama3.2:cloud) Ollama의 클라우드 라우팅을 요청합니다. 이 경우 원격 api_url과 API 키가 모두 필요하며, 로컬 엔드포인트에서 :cloud 모델을 요청하거나 키가 설정되어 있지 않으면 Revka가 즉시 오류를 반환합니다.

추론 / thinking

[runtime] 아래에 reasoning_enabled를 설정하면 Ollama의 think 플래그가 전달됩니다:

[runtime]
reasoning_enabled = true

추론을 지원하는 모델에서만 적용됩니다. think: true로 요청했을 때 모델이 지원하지 않아 실패하면, Revka는 think를 제거한 채 자동으로 한 번 재시도하여 호출이 성공하도록 합니다. 또한 Revka는 텍스트를 반환하기 전에 모델 출력에서 <think>...</think> 블록을 제거합니다.

비전

Ollama는 비전을 지원합니다. 사용자 메시지에 이미지 마커를 삽입하면(아래 비전 지원 참고), Revka가 이미지를 추출하여 Ollama의 images 배열로 전송합니다.

참고

Ollama는 네이티브 tools API 대신 시스템 프롬프트 기반 XML 스타일(<tool_call>) 도구 호출을 사용합니다. 로컬 모델이 네이티브 도구 호출을 자주 무시하기 때문입니다. 이는 에이전트 루프에서 투명하게 처리됩니다.

로컬 및 자체 호스팅 OpenAI 호환 서버

LM Studio, llama.cpp, vLLM, SGLang, Osaurus는 모두 OpenAI /v1/chat/completions 형식을 지원하며, Revka의 OpenAiCompatibleProvider 구현을 공유합니다. 각 프로바이더의 정식 ID로 선택하세요:

프로바이더	ID (별칭)	기본 베이스 URL	인증
LM Studio	lmstudio (lm-studio)	http://localhost:1234/v1	선택 사항; 기본 키 lm-studio
llama.cpp	llamacpp (llama.cpp)	http://localhost:8080/v1	선택 사항 (LLAMACPP_API_KEY); 비전 활성화
vLLM	vllm	http://localhost:8000/v1	선택 사항 (VLLM_API_KEY)
SGLang	sglang	http://localhost:30000/v1	선택 사항 (SGLANG_API_KEY)
Osaurus	osaurus	http://localhost:1337/v1	선택 사항; 기본 키 osaurus

각각에 대한 최소 설정 예시:

default_provider = "vllm"
default_model    = "Qwen/Qwen2.5-7B-Instruct"

서버가 기본이 아닌 호스트나 포트에서 실행되는 경우(예: LAN의 다른 머신이나 Docker 호스트), api_url로 재정의할 수 있습니다:

default_provider = "lmstudio"
api_url          = "http://host.docker.internal:1234/v1"
default_model    = "your-loaded-model"

lmstudio, osaurus, llamacpp는 키를 설정하지 않으면 각각 플레이스홀더 키(lm-studio, osaurus, llama.cpp)로 폴백합니다. 이는 Bearer 값이 필요하지만 유효성 검사를 하지 않는 서버를 위한 것입니다. vllm과 sglang의 경우 키는 선택 사항이며 설정된 경우에만 전송됩니다.

팁

이 백엔드들은 소형 컨텍스트 모델을 위한 [pacing] 설정 섹션(step_timeout_secs, 루프 감지 유예 기간) 및 [agent] 컨텍스트 제어와 함께 사용하면 효과적입니다. 설정: 프로바이더, 에이전트 및 라우팅을 참고하세요.

비전 지원

백엔드	비전
Ollama	지원
llama.cpp (llamacpp)	지원
custom: 엔드포인트	지원
LM Studio, vLLM, SGLang, Osaurus	기본적으로 미활성화

이미지를 전송하려면 사용자 메시지에 이미지 마커를 삽입하세요. 두 가지 형식을 지원합니다:

Describe this chart [IMAGE:/path/to/file.png]
Describe this chart [IMAGE:data:image/png;base64,iVBORw0KG...]

원격 이미지 URL을 사용하려면 [multimodal] 아래에 allow_remote_fetch = true를 설정해야 합니다. 이미지 수와 크기는 제한됩니다(max_images 1–16, max_image_size_mb 1–20). 설정: 프로바이더, 에이전트 및 라우팅의 [multimodal] 섹션을 참고하세요.

모델 검색

Revka는 각 프로바이더의 모델 카탈로그를 디스크에 캐시하고 프로바이더의 models 엔드포인트에서 갱신합니다.

revka models refresh                       # refresh the default provider
revka models refresh --provider vllm       # refresh one provider
revka models list --provider vllm          # print the cached catalog

라이브 검색은 **ollama, llamacpp, sglang, vllm, osaurus**에서 지원됩니다. lmstudio는 라이브 검색을 지원하지 않으므로 모델을 수동으로 설정하세요:

revka models set your-loaded-model

설정된 모든 프로바이더의 연결 상태와 인증을 한 번에 확인하려면 revka doctor models를 사용하세요. 전체 명령어 레퍼런스: revka models, providers & auth.

커스텀 엔드포인트 (OpenAI 호환)

기명 프로바이더가 맞지 않는 경우, custom: 프리픽스를 사용하여 OpenAI 호환 엔드포인트를 지정할 수 있습니다. URL이 프로바이더 ID의 일부가 됩니다:

default_provider = "custom:https://your-api.example.com/v1"
api_key          = "your-key"

URL은 반드시 http:// 또는 https://를 사용해야 하며, 비어 있거나 유효하지 않은 URL은 시작 시 명확한 오류와 함께 실패합니다. 커스텀 엔드포인트는 비전이 활성화됩니다. 프로바이더에 알려진 키 프리픽스가 없으므로 custom: 프로바이더에서는 API 키 불일치 검사가 건너뜁니다.

안정성 폴백 체인을 포함하여 프로바이더 이름이 허용되는 모든 곳에 custom: URL을 사용할 수 있습니다:

[reliability]
fallback_providers = ["custom:http://host.docker.internal:1234/v1", "anthropic"]

anthropic-custom:

커스텀 Anthropic Messages API 엔드포인트(예: 자체 호스팅 Anthropic 호환 게이트웨이)를 대상으로 하려면 anthropic-custom: 프리픽스를 사용하세요. 이렇게 하면 지정한 베이스 URL에 대해 Revka의 네이티브 Anthropic 프로바이더를 통해 라우팅됩니다:

default_provider = "anthropic-custom:https://your-anthropic-compat.example.com"
api_key          = "your-key"

동일한 URL 유효성 검사가 적용되며, 키 프리픽스 불일치 검사는 건너뜁니다.

api_path 및 extra_headers

비표준 또는 게이트웨이 엔드포인트에 유용한 두 가지 튜닝 옵션입니다. custom: 및 위의 로컬 서버를 포함한 OpenAI 호환 프로바이더에 적용됩니다.

api_path

기본적으로 Revka는 베이스 URL에 /chat/completions를 추가합니다(베이스 URL이 이미 /chat/completions로 끝나는 경우에는 그대로 사용). 다른 경로를 사용하는 API의 경우 api_path로 재정의하세요:

default_provider = "custom:https://your-gateway.example.com"
api_path         = "/v2/generate"

api_path를 설정하면 기본 /chat/completions 접미사를 대체합니다. 앞의 슬래시는 선택 사항이며, 필요한 경우 Revka가 구분자를 삽입합니다.

extra_headers

모든 프로바이더 요청에 추가 HTTP 헤더를 전송합니다. 게이트웨이 라우팅, 테넌트 식별자, HTTP-Referer / X-Title 같은 헤더에 유용합니다. Revka의 기본 헤더에 추가되거나 이를 재정의합니다.

[extra_headers]
"X-Title" = "revka"
"X-Tenant-Id" = "team-42"

REVKA_EXTRA_HEADERS

동일한 헤더를 REVKA_EXTRA_HEADERS 환경 변수로도 설정할 수 있으며, Key:Value,Key2:Value2 형식을 사용합니다. 환경 변수 헤더는 같은 이름의 설정 파일 헤더를 재정의합니다.

export REVKA_EXTRA_HEADERS="X-Title:revka,X-Tenant-Id:team-42"

콜론이 없거나 키가 비어 있는 항목은 경고와 함께 건너뜁니다. 함께 사용할 수 있는 다른 프로바이더 튜닝 키(provider_timeout_secs, provider_max_tokens, [runtime] reasoning_effort)는 라우팅, 안정성 및 튜닝에서 설명합니다.

관련 페이지

• 프로바이더 빠른 시작 — 프로바이더를 선택하고 첫 번째 채팅을 실행하기
• 프로바이더 카탈로그 — 베이스 URL, 환경 변수, 기능이 포함된 전체 프로바이더 목록
• 커스텀 프로바이더 및 로컬 LLM — 작업 중심 가이드
• revka models, providers & auth — 모델 카탈로그 및 프로바이더 CLI
• 설정: 프로바이더, 에이전트 및 라우팅 — 전체 설정 키 레퍼런스