커스텀 프로바이더 및 로컬 LLM

Revka는 50개 이상의 네임드 프로바이더를 기본으로 지원하지만, 이에 국한되지 않습니다. OpenAI Chat Completions 또는 Anthropic Messages 와이어 포맷을 지원하는 서비스라면 모두 Revka 백엔드로 사용할 수 있으며, 개인 머신에서 많이 사용되는 로컬 추론 서버인 Ollama, llama.cpp, LM Studio, vLLM, SGLang은 이미 네임드 프로바이더로 내장되어 있습니다. 이 가이드에서는 custom: 및 anthropic-custom: 프리픽스를 사용해 임의의 엔드포인트를 지정하는 방법, 일반적인 로컬 서버 설정 방법, 그리고 느린 로컬 모델이 타임아웃이나 루프 감지를 유발하지 않도록 에이전트 루프를 조정하는 방법을 안내합니다.

사용하려는 프로바이더가 카탈로그에 없거나, 자체 게이트웨이 또는 사내 LLM 프록시를 운영하거나, 모든 처리를 로컬에서 완결하고 싶을 때 이 페이지를 활용하세요. 기본 클라우드 프로바이더를 선택하려면 프로바이더 퀵스타트를 참고하세요.

커스텀 프로바이더 및 엔드포인트

프로바이더의 베이스 URL은 일반적으로 내장된 기본값에서 가져옵니다. 다른 URL이 필요한 경우 Revka는 두 가지 방법을 제공합니다: URL을 포함하는 프로바이더 프리픽스를 사용하거나, 네임드 프로바이더에 api_url 오버라이드를 명시적으로 지정하는 방법입니다.

custom: 및 anthropic-custom: 프리픽스

프로바이더 프리픽스는 엔드포인트 URL을 default_provider에 직접 포함하므로, 별도로 네임드 프로바이더를 등록할 필요가 없습니다.

OpenAI-compatible

~/.revka/config.toml

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

custom:은 Revka의 공유 OpenAI 호환 구현을 통해 라우팅됩니다. /v1/chat/completions를 사용하며(404 시 /v1/responses API로 폴백), Bearer 인증, base64 이미지를 통한 비전, OpenAI JSON 스키마 형식의 네이티브 툴 콜링을 지원합니다.

Anthropic-compatible

~/.revka/config.toml

default_provider = "anthropic-custom:https://your-api.example.com"
api_key          = "your-key"
default_model    = "claude-sonnet-4-6"

anthropic-custom:은 커스텀 Anthropic Messages API 엔드포인트로 라우팅됩니다. OpenAI 형식이 아닌 Anthropic 와이어 포맷을 노출하는 프록시나 게이트웨이에 사용하세요.

커스텀 프로바이더는 프로바이더 전용 환경 변수 대신 범용 키 환경 변수로 인증합니다.

export API_KEY="your-key"        # or: export REVKA_API_KEY="your-key"
revka agent -m "hello"

참고

custom: 프로바이더와 api_url이 지정된 프로바이더에 대해서는 API 키 불일치 검사가 건너뜁니다. 예를 들어 openai 프로바이더에 sk-ant- 키를 사용할 경우 경고를 표시하는 검사입니다. 커스텀 엔드포인트는 어떤 형식의 키도 잘못된 경고 없이 사용할 수 있습니다.

api_url, api_path, extra_headers

이 세 가지 최상위 설정 키를 사용하면 네임드 프로바이더를 비표준 엔드포인트로 연결할 수 있습니다. 또한 프리픽스만으로는 필요한 정보를 모두 전달하기 어려울 때 custom: 프로바이더에도 적용됩니다.

키	타입	기본값	의미
api_url	String?	프로바이더 기본값	베이스 URL 오버라이드 (예: 자체 호스팅 게이트웨이 또는 http://10.0.0.1:11434의 원격 Ollama).
api_path	String?	프로바이더 기본값	비표준 API의 요청 경로 접미사를 오버라이드합니다 (예: /chat/completions 대신 /v2/generate).
extra_headers	Map<String,String>	{}	모든 프로바이더 요청에 함께 전송되는 추가 HTTP 헤더.

default_provider = "custom:https://gateway.corp.example.com"
api_url          = "https://gateway.corp.example.com/llm/v1"
api_path         = "/chat/completions"
default_model    = "internal-model"

[extra_headers]
"X-Org-Id"    = "engineering"
"X-Route-Tag" = "revka"

extra_headers는 Key:Value,Key2:Value2 형식으로 환경 변수에서도 설정할 수 있습니다.

export REVKA_EXTRA_HEADERS="X-Org-Id:engineering,X-Route-Tag:revka"

팁

프로바이더 오류 메시지는 토큰과 유사한 패턴(sk-…, ghp_… 등)이 자동으로 삭제되고 500자로 잘린 후 로그나 채팅 응답에 전달됩니다. 키가 업스트림 오류 본문에 포함되더라도 [REDACTED]로 표시됩니다.

로컬 및 자체 호스팅 프로바이더

Revka는 인기 있는 로컬 추론 서버를 퍼스트클래스 네임드 프로바이더로 취급하며, 각각 적절한 기본 엔드포인트와 선택적 인증을 제공합니다. 사용을 위해 더미 REVKA_API_KEY를 내보낼 필요가 없습니다. 서버가 기본이 아닌 호스트나 포트에서 실행 중이라면 api_url로 엔드포인트를 오버라이드하세요.

프로바이더 ID	별칭	기본 엔드포인트	API 키
ollama	—	http://localhost:11434 (네이티브 /api/chat)	OLLAMA_API_KEY (선택)
llamacpp	llama.cpp	http://localhost:8080/v1	LLAMACPP_API_KEY (선택; 비전 지원)
lmstudio	lm-studio	http://localhost:1234/v1	선택 (기본값: lm-studio)
vllm	—	http://localhost:8000/v1	VLLM_API_KEY (선택)
sglang	—	http://localhost:30000/v1	SGLANG_API_KEY (선택)
osaurus	—	http://localhost:1337/v1	OSAURUS_API_KEY (선택; 기본값: osaurus)

로컬 프로바이더 설정 후 Revka가 연결 가능한지 확인하고 모델 목록을 가져옵니다.

revka models refresh --provider llamacpp   # swap in your provider id
revka agent -m "hello"

revka doctor models --provider <id>는 단일 프로바이더를 점검하여 ok, auth-error, 또는 연결 오류를 보고합니다. 데몬에 프로바이더를 연결하기 전에 유용하게 활용할 수 있습니다.

Ollama

Ollama는 OpenAI 호환 경로 대신 네이티브 /api/chat 엔드포인트를 사용하므로, 비전 이미지는 Ollama 자체 이미지 마커([IMAGE:<source>])를 통해 전달됩니다.

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

원격 또는 클라우드 Ollama는 api_url이 필요하며, URL에 포함된 /api 접미사는 자동으로 정규화됩니다. :cloud 모델 접미사는 원격 엔드포인트에서만 유효합니다.

default_provider = "ollama"
api_url          = "https://ollama.myserver.com"
default_model    = "llama3.2:cloud"

모델의 사고(thinking) 출력을 전환하려면 [runtime]에 reasoning_enabled를 설정하세요. Revka가 이를 Ollama의 think: true/false로 전달합니다. 추론을 지원하는 모델에서만 적용됩니다.

[runtime]
reasoning_enabled = true

참고

Ollama의 경우 api_url은 REVKA_PROVIDER_URL 환경 변수로도 지정할 수 있습니다.

llama.cpp

llamacpp 프로바이더는 llama-server를 대상으로 합니다. 서버를 시작한 후 Revka의 api_url을 해당 주소로 지정하세요. API 키는 llama-server를 --api-key 옵션으로 실행한 경우에만 필요합니다.

llama-server -hf ggml-org/gpt-oss-20b-GGUF --jinja -c 133000 --host 127.0.0.1 --port 8033

default_provider  = "llamacpp"
api_url           = "http://127.0.0.1:8033/v1"
default_model     = "ggml-org/gpt-oss-20b-GGUF"
default_temperature = 0.7

LM Studio

LM Studio는 포트 1234에 OpenAI 호환 서버를 노출합니다. 키는 필요하지 않으며 프로바이더가 자동으로 lm-studio 플레이스홀더를 제공합니다.

default_provider = "lmstudio"
default_model    = "your-loaded-model"

vLLM 및 SGLang

두 서버 모두 OpenAI 호환 추론 서버입니다. 서버를 시작하고 해당 프로바이더를 설정하세요. 서버에서 강제하지 않는 한 인증은 선택 사항입니다.

vLLM

vllm serve meta-llama/Llama-3.1-8B-Instruct

default_provider = "vllm"
default_model    = "meta-llama/Llama-3.1-8B-Instruct"
default_temperature = 0.7

SGLang

python -m sglang.launch_server --model meta-llama/Llama-3.1-8B-Instruct --port 30000

default_provider = "sglang"
default_model    = "meta-llama/Llama-3.1-8B-Instruct"
default_temperature = 0.7

팁

이러한 서버는 범용 custom: 프리픽스를 통해서도 연결할 수 있습니다. 예를 들어 default_provider = "custom:http://localhost:8080/v1"과 같이 사용할 수 있습니다. 그러나 네임드 프로바이더는 올바른 기본값과 모델 카탈로그 갱신 기능을 즉시 제공하므로 가급적 네임드 프로바이더를 사용하세요.

느린 로컬 LLM을 위한 튜닝

랩탑의 13B 모델은 호스팅 프런티어 모델보다 훨씬 느리며, 첫 번째 토큰이 늦게 도착하면 기본 에이전트 설정에서 응답 없음이나 무한 루프처럼 보일 수 있습니다. 바로 이런 경우를 위해 두 가지 설정 섹션이 마련되어 있습니다. 클라우드 사용자에게는 거의 필요하지 않습니다.

[pacing] — 타임아웃 및 루프 감지

[pacing] 섹션은 느린 워크로드에 대한 단계별 타임아웃 및 루프 감지 동작을 확장합니다.

[pacing]
step_timeout_secs               = 120
loop_detection_min_elapsed_secs = 60
loop_ignore_tools               = ["browser_screenshot", "browser_navigate"]
message_timeout_scale_max       = 8

키	기본값	의미
step_timeout_secs	미설정	단계별 LLM 추론 타임아웃으로, 전체 메시지 예산과 독립적입니다. 타임아웃이 발생해도 총 예산이 소모되지 않습니다.
loop_detection_min_elapsed_secs	미설정	루프 감지가 카운팅을 시작하기 전 유예 기간으로, 느린 시작을 루프로 오인하지 않도록 합니다.
loop_ignore_tools	[]	동일 출력 루프 감지에서 제외할 도구 목록 (예: 반복이 정상인 도구).
message_timeout_scale_max	4	툴 루프 깊이에 따라 기본 메시지 타임아웃이 확장되는 최대 배율.
loop_detection_enabled	true	패턴 기반 루프 감지의 마스터 토글.
loop_detection_window_size	20	루프 감지기의 슬라이딩 윈도우 크기.
loop_detection_max_repeats	3	루프 경고가 발생하기 전까지 허용되는 동일 툴+인자 연속 호출 횟수.

소형 모델을 위한 compact_context

[agent]의 compact_context 키는 에이전트를 13B 이하 소형 모델에 적합한 컴팩트 부트스트랩 프롬프트로 전환하여, 좁은 컨텍스트 윈도우에 맞게 시스템 프롬프트를 줄입니다. 기본적으로 활성화되어 있습니다.

[agent]
compact_context = true

컨텍스트가 부족할 때 관련 [agent] 설정과 함께 사용하세요.

키	기본값	의미
compact_context	true	소형(≤13B) 모델용 컴팩트 부트스트랩 프롬프트 사용.
max_system_prompt_chars	0 (무제한)	시스템 프롬프트를 N자로 강제 자르기 — 매우 좁은 컨텍스트 윈도우에 유용.
max_context_tokens	1050000	컨텍스트 압축이 시작되는 토큰 예산. 소형 모델의 윈도우에 맞게 낮게 설정하세요.
max_tool_result_chars	50000	중간 잘림이 적용되기 전 툴 결과의 최대 문자 수.

팁

컨텍스트가 제한된 모델에서는 [skills] prompt_injection_mode = "compact"도 설정하여 스킬 지시사항을 인라인으로 삽입하지 않고 온디맨드로 로드하고, 결정론적 컨텍스트 압축 레이어를 활용해 툴 출력을 작게 유지하세요. 두 가지 모두 동작을 바꾸지 않고 시스템 프롬프트 압박을 줄여줍니다.

라우트별 및 에이전트별 프로바이더

인스턴스 전체를 하나의 백엔드에 고정할 필요가 없습니다. 커스텀 또는 로컬 프로바이더는 범위를 지정할 수 있습니다.

• 라우팅 힌트 — [[model_routes]]를 사용해 hint:fast(또는 임의의 이름)를 특정 프로바이더+모델에 매핑합니다. custom:/anthropic-custom: 엔드포인트도 포함됩니다. 라우팅, 안정성 및 튜닝을 참고하세요.

• 위임 서브에이전트 — [agents.<name>] 블록에 자체 provider와 model을 지정합니다. 예를 들어 coder 서브에이전트에 로컬 코딩 모델을 사용할 수 있습니다.

  [agents.coder]
  provider    = "ollama"
  model       = "qwen2.5-coder:32b"
  temperature = 0.2

• 안정성 폴백 — 클라우드 프로바이더가 다운되었을 때 에이전트가 계속 동작할 수 있도록 로컬 프로바이더를 폴백으로 목록에 추가합니다. [reliability]를 참고하세요.

설정 확인

1. 엔드포인트 점검. revka doctor models --provider <id>에서 ok와 모델 수가 출력되어야 합니다. auth-error는 키(있는 경우)가 잘못된 것이고, 연결 오류는 URL이나 서버에 접근할 수 없다는 의미입니다.

2. 카탈로그 갱신. revka models refresh --provider <id>를 실행하면 최신 모델 목록을 가져와 default_model이 유효한지 검증합니다. 게이트웨이가 models 엔드포인트를 구현하지 않은 경우, default_model을 수동으로 설정하고 테스트 메시지를 전송하세요.

3. 메시지 전송. revka agent -m "hello"로 전체 경로를 검증합니다. 로컬 모델의 경우 첫 번째 토큰 지연 시간을 확인하세요. 설정값을 초과하면 [pacing] step_timeout_secs를 높이세요.

4. 전체 진단 실행. revka doctor는 데몬을 시작하기 전에 해석된 프로바이더, 키 존재 여부, 모델을 한 번에 검증합니다.

다음 단계

로컬, 자체 호스팅 및 커스텀 엔드포인트 로컬 서버와 커스텀 엔드포인트에 대한 전체 프로바이더 레퍼런스.

프로바이더 카탈로그 모든 프로바이더 ID, 별칭, 베이스 URL, 인증 환경 변수.

라우팅, 안정성 및 튜닝 모델 라우트, 폴백 체인, 타임아웃, 키 불일치 감지.

설정: 프로바이더, 에이전트 및 라우팅 [agent], [pacing] 및 핵심 프로바이더 키에 대한 레퍼런스.