백엔드 패스스루 계약¶

일부 백엔드 타입의 경우, Continuum Router는 채팅 완성 요청 바디를 수신한 그대로 업스트림 서버에 전달한다. 필드 이름 변경, 구조 변경, 값 변환 없이 그대로다. 이 문서에서는 패스스루 보증을 제공하는 백엔드, 알려진 소비자가 의존하는 필드, 그리고 요청을 변환하는 백엔드와의 경계를 정의한다.

패스스루 백엔드¶

다음 백엔드 타입은 POST /v1/chat/completions 요청 바디를 그대로 전달한다. 비표준 최상위 필드, extra_body, 인식할 수 없는 키 모두 포함된다.

OpenAI
Llamacpp (llama-server)
Mlxcel (LlamaCppBackend 재사용; src/infrastructure/backends/factory/backend_factory.rs 참고)
Ollama
vLLM
LMStudio
LocalAI

패스스루에는 동등한 세 가지 구현 지점이 있다.

HTTP 경로: src/proxy/backend.rs::make_http_request — 주 패스스루 지점. 비-Anthropic, 비-Gemini 분기의 else 블록에서 payload.clone()을 호출해 바디를 그대로 전달한다.
Unix 소켓 경로: 같은 파일의 make_unix_socket_request 내 형제 else 블록으로, backend.transport가 UnixSocket일 때 실행된다.
스트리밍 경로: src/http/streaming/handler.rs의 client.post(&backend_url).json(&current_payload) 호출 지점으로, 스트리밍 폴백 루프의 각 시도에서 current_payload를 그대로 전달한다.

세 지점 모두 중간 변환 단계를 거치지 않는다. Mlxcel이 LlamaCppBackend를 상속한다는 팩토리 수준의 설명(src/infrastructure/backends/factory/backend_factory.rs 참고)은 여전히 유효하며, 위의 패스스루 지점에는 영향을 주지 않는다.

알려진 소비자¶

다음 필드들은 실제 운영에서 사용되며 패스스루 과정에서 반드시 변경 없이 전달되어야 한다.

chat_template_kwargs — llama.cpp / MLxcel용 Jinja 템플릿 파라미터 (예: {"enable_thinking": false, "preserve_thinking": true}). Qwen3 계열의 thinking-mode 제어에 필요하다.
thinking_budget_tokens — llama-server가 허용하는 요청별 thinking 예산 상한. llama-server를 통한 Qwen3 thinking 모드에 필요하다.
extra_body — OpenAI 클라이언트 라이브러리(예: Python openai SDK의 extra_body kwarg)가 전달하는 추가 파라미터 객체. {"skip_special_tokens": false} 같은 vLLM 전용 설정을 전달하는 데 사용된다.

변환 백엔드¶

다음 백엔드 타입은 요청을 전달하기 전에 공급자별 변환 레이어를 거친다. 비표준 필드는 원본 그대로 전달되지 않을 수 있다.

Anthropic — src/http/handlers/anthropic/transform.rs. 변환 과정에서 thinking 블록(budget_tokens 포함)이 다운스트림 OpenAI 호환 호출용 reasoning_effort로 변환된다.
Gemini — src/infrastructure/backends/gemini/transform.rs. Gemini 네이티브 요청 재구성; 현재 필드 매핑은 변환 소스를 참고한다.

통합 테스트¶

패스스루 계약은 다음 통합 테스트로 보호된다.

tests/llamacpp_passthrough_test.rs — chat_template_kwargs, thinking_budget_tokens, extra_body, 임의의 알 수 없는 필드가 llama-server 엔드포인트에 변경 없이 도달하는지 검증한다.
tests/mlxcel_passthrough_test.rs — Mlxcel 백엔드 타입에 동일한 검증을 적용한다. 두 백엔드 간의 향후 차이가 별도 실패 테스트로 드러나도록 파일을 분리했다.
tests/anthropic_input_test.rs — thinking.budget_tokens가 변환되어 다운스트림 서버에 원시 thinking_budget_tokens 필드로 도달하지 않음을 확인하는 부정 테스트(test_anthropic_thinking_budget_tokens_transforms_to_reasoning_effort)를 포함한다.

이 테스트 중 하나라도 리팩터링으로 인해 실패한다면, 일반적인 테스트 실패가 아닌 공개 계약에 대한 변경으로 취급해야 한다. 병합 전에 이 문서를 업데이트하여 새로운 동작을 반영한다.

보증 범위¶

글로벌 프롬프트가 비활성화된 경우, 업스트림 서버가 수신하는 JSON 바디는 클라이언트가 보낸 바디와 동일하며, 다음의 알려진 예외가 있다.

라우터가 추가하는 내부 HTTP 헤더 (예: x-request-id, api_key 설정 시 Authorization: Bearer).
global_prompts가 설정된 경우 글로벌 시스템 프롬프트 주입. 이 경우 messages 배열이 수정되지만, messages 외의 최상위 필드는 변경되지 않는다.

패스스루 경로는 추가적인 최상위 JSON 키를 주입하지 않는다.