백엔드 패스스루 계약¶

일부 백엔드 타입의 경우, Continuum Router는 요청이 전송 계층에 도달한 시점부터는 채팅 완성 요청 바디를 백엔드별 재구성 없이 그대로 전달합니다. 이는 엣지에서 업스트림까지의 바이트 동등성 보증보다 좁은 범위입니다. 앞단의 핸들러 단계는 make_http_request, make_unix_socket_request, LlamaCppBackend::execute_chat_completion이 페이로드를 보기 전에 여전히 이를 수정할 수 있습니다. 이 문서는 전송 계층 보증을 제공하는 백엔드, 알려진 소비자가 의존하는 필드, 그리고 요청을 변환하는 백엔드와의 경계를 정의합니다.

패스스루 백엔드¶

다음 백엔드 타입은 채팅 완성 전송 경로에서 백엔드별 변환을 적용하지 않습니다. 요청이 해당 경로에 도달한 뒤에는 비표준 최상위 필드, 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를 그대로 전달합니다.
팩토리 경유 llama.cpp / MLxcel 경로: src/infrastructure/backends/llamacpp/backend.rs::LlamaCppBackend::execute_chat_completion. src/infrastructure/backends/factory/backend_factory.rs를 통해 BackendTypeConfig::Llamacpp와 BackendTypeConfig::Mlxcel에 대해 실행됩니다.

바로 아래에서 설명하는 클라우드 OpenAI 필드 제거를 제외하면, 네 지점 모두 공급자별 변환을 적용하지 않습니다.

클라우드 OpenAI 예외¶

OpenAI 백엔드 타입은 OpenAI 클라우드와 로컬 OpenAI 호환 엔진을 모두 포괄하는데, 두 쪽은 알 수 없는 필드를 다르게 다룹니다. api.openai.com은 인식할 수 없는 최상위 키가 하나라도 있으면 HTTP 400으로 거부하고, 로컬 엔진은 그 필드들을 실제로 소비합니다. 그래서 전송 지점들은 게이트가 걸린 필터 하나를 적용합니다. /v1/chat/completions 요청의 목적지 URL에 api.openai.com이 포함되면, 엔진 전용 필드인 chat_template_kwargs, thinking_budget_tokens, enable_thinking, preserve_thinking, top_k, min_p, repeat_penalty(src/infrastructure/backends/field_filter.rs의 NON_OPENAI_FIELDS)를 전송 전에 제거합니다.

제거는 클라우드 OpenAI로 채팅을 보내는 모든 지점에서 실행됩니다. make_http_request의 비스트리밍 패스스루 분기, 스트리밍 전송, 그리고 mid-stream 폴백과 자동 선택 폴백 루프의 각 홉이 해당합니다. 폴백은 백엔드를 바꿀 수 있으므로 게이트는 홉마다 다시 평가됩니다.
같은 차단 목록이 클라우드 Gemini 제거에도 쓰입니다(Google의 /v1beta/openai/chat/completions 엔드포인트도 필드 이름을 똑같이 엄격하게 검증합니다). Azure OpenAI와 Anthropic /v1/messages 브리지는 별도 표면이라 이 게이트의 대상이 아닙니다.
제거는 최상위 필드에만 적용됩니다. extra_body와 reasoning_effort는 절대 건드리지 않습니다. extra_body는 공급자별 설정을 위한 의도된 통로이고, reasoning_effort는 클라우드 OpenAI가 직접 받아들입니다(클라우드 Gemini는 thinking_level로 매핑합니다).
로컬 엔진 URL에는 api.openai.com이 들어가지 않으므로, llama.cpp, vLLM, MLxcel, Ollama, LM Studio, LocalAI에는 이 필터가 아무 동작도 하지 않고 패스스루 보증도 그대로 유지됩니다.

알려진 소비자¶

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

chat_template_kwargs: llama.cpp / MLxcel용 Jinja 템플릿 파라미터 (예: {"enable_thinking": false, "preserve_thinking": true}). Qwen3 계열의 thinking-mode 제어에 필요합니다.
thinking_budget_tokens: llama.cpp가 허용하는 요청별 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 백엔드 타입에 대한 별도 커버리지를 유지합니다. 프록시 경로 픽스처와 함께 팩토리 경유 BackendFactory -> LlamaCppBackend::execute_chat_completion 어서션을 포함해서, MLxcel 배선이 달라지면 별도의 실패 테스트로 드러납니다.
tests/anthropic_input_test.rs: thinking.budget_tokens가 변환되어 다운스트림 서버에 원시 thinking_budget_tokens 필드로 도달하지 않음을 확인하는 부정 테스트(test_anthropic_thinking_budget_tokens_transforms_to_reasoning_effort)를 포함합니다.
src/infrastructure/backends/field_filter.rs의 유닛 테스트: 클라우드 게이트 제거를 커버합니다. 클라우드 OpenAI 채팅 요청에서는 차단 목록의 모든 필드가 제거되고, 로컬 엔진 요청은 전부 유지되며, 채팅이 아닌 엔드포인트는 건드리지 않습니다.

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

보증 범위¶

이 보증은 위에 나열한 전송 지점에 적용됩니다. 업스트림 서버가 클라이언트가 제출한 JSON 바디의 바이트 단위 사본을 항상 받는다는 의미는 아닙니다.

패스스루 지점이 실행되기 전에 chat_completions는 여전히 라우터 수준 전처리를 수행할 수 있습니다.

global_prompts가 설정된 경우 글로벌 시스템 프롬프트 주입. 이 경우 messages 배열이 수정됩니다.
o1, o3, gpt-5* 모델 ID에 대해 transform_payload_for_openai()가 max_tokens를 max_completion_tokens로 변경.
web_search.enabled가 적용되는 자체 호스팅 백엔드 대상 요청에 라우터 관리 web_search 주입. 업스트림 호출 전에 tools 항목이 추가될 수 있습니다.

전송 계층 자체에서는 추가적인 최상위 JSON 키를 주입하지 않으며, 위에서 설명한 클라우드 OpenAI 제거를 제외하면 패스스루 필드를 걸러내거나 이름을 바꾸지 않습니다.