‘앞에 붙는 /는 호스트 바로 아래에서 시작한다.’ 2026년 11월 14일자 개발자 블로그 'datasette-llm 0.1a11'을 통해 호환 엔드포인트 지원 기능을 알게 되었고, httpx로 확인해 보니 이 예상과 달랐습니다.
httpx 0.28.1의 Client(base_url=...)는 /chat/completions를 기본 경로에 추가합니다. 이때 base_url의 /v1은 그대로 유지됩니다.
저는 LLM 연결 대상을 교체할 때, 전송하기 전에 완성된 URL까지 확인하고 싶습니다. 이번 내용은 httpx 단독 검증이며, Datasette나 각사 SDK를 재현한 것은 아닙니다.
macOS, CPython 3.12.13, httpx==0.28.1 환경에서 검증했습니다. 아래 내용을 repro.py에 저장하고 python repro.py로 실행합니다. build_request()만으로 요청을 만들 수 있으므로 서버나 API 키가 필요하지 않습니다.
예시 URL은 가상의 것입니다. 리버스 프록시의 /gateway 하위에 호환 API인 /v1이 있는 구성을 가정했습니다.
from urllib.parse import urljoin, urlsplit
import httpx
base = "https://llm.example.test/gateway/v1"
...
출력은 다음과 같았습니다.
base_url: https://llm.example.test/gateway/v1/
chat/completions
urljoin: /gateway/v1/chat/completions
...
앞에 /가 없는 첫 번째 경우는 동일했습니다. 두 번째 경우부터 차이가 발생했습니다.
urljoin()을 사용할 때는 앞에 붙는 / 때문에 기본 경로 자체가 대체됩니다. 하지만 httpx에서는 /gateway/v1이 그대로 남았습니다. 만약 /v1/chat/completions를 전달하면, v1이 중복되는 문제가 발생합니다.
오늘 이 출력을 보면서, 저는 /chat/completions의 모양에 현혹되어 있었다는 것을 깨달았습니다. 마치 브라우저의 감각으로 설정을 읽고 있었던 것입니다.
저는 비교 조건을 맞추기 위해 urljoin() 측에는 끝에 /를 붙였습니다. 이렇게 하면 끝에 있던 v1이 대체되므로, 비교 조건 통일이 필요했습니다.
설치된 httpx/_client.py 파일을 확인해 보았습니다. 대응하는 1차 자료는 httpx 0.28.1의 소스 코드입니다. 처리 과정을 추적할 곳은 _enforce_trailing_slash()와 _merge_url()입니다.
먼저, 클라이언트의 기본 URL에는 끝에 /가 보강됩니다. 출력의 base_url: 줄에서도 이를 확인할 수 있습니다.
상대 URL을 전달했을 경우, 기본 측의 raw_path에 전달한 쪽의 raw_path.lstrip(b"")를 연결합니다. 이 구현 방식 때문에, 앞에 /가 붙어 있어도 기본 경로는 유지됩니다. /v1과 같은 이름에 특별한 의미를 부여하는 처리는 없습니다.
이번 경우라면, 베이스는 /gateway/v1까지로 설정하고 호출 측은 chat/completions로 맞추는 것이 좋습니다. 앞에 붙는 /가 있어도 결과는 같지만, '기본 경로의 연속'처럼 보이게 하는 것이 목적입니다. 완성된 엔드포인트를 설정하는 설계라면, 호출 측도 그에 맞춰야 합니다.
입력란에 단순히 “URL”이라고만 적혀 있으면 헷갈립니다. 저라면 입력 예시에 /v1까지 포함해 둘 것입니다. 이용자에게 소스 코드를 읽어보게 하는 상황이 아니기 때문입니다.
매번 수동으로 살펴보는 것은 번거로우므로, 호출 측을 chat/completions로 고정하고 기본 URL을 3가지 방식으로 바꿔가며 대조해 보았습니다.
예상되는 연결 경로는 프록시 측의 루트 정의와 독립적으로 결정되어야 합니다. 만약 기본 URL부터 예상치를 만들어 버리면, 같은 설정 실수를 양쪽 모두에 넣고도 통과시켜버릴 수 있습니다.
import httpx
origin = "https://llm.example.test"
expected = origin + "/gateway/v1/chat/completions"
...
NG /gateway/chat/completions
OK /gateway/v1/chat/completions
NG /gateway/v1/chat/completions/chat/completions
누락과 중복을 잡아낼 수 있었습니다. 이 예시는 표시용일 뿐이며, CI(Continuous Integration)에 통합할 경우 NG라면 종료 코드를 0이 아닌 값으로 설정하거나 어설션(assertion) 처리를 해야 합니다.
구현에 통합할 때는 설정 로드 처리의 반환값을 전달해야 한다. 샘플 문자열만으로는 배포 시점의 값까지 확인할 수 없다. 래퍼(wrapper)에 의한 경로 변경도 확인 대상이다.
확인할 수 있었던 것은 전송 전 URL까지였다. 인증, 모델명, 프록시의 전달 목적지는 미확인이다. 수신 측에서의 경로 변경 또한 별도로 확인이 필요하다.
각 SDK의 URL 결합 규칙은 개별적으로 확인이 필요하다. 이번에는 0.28.1로 결과와 구현을 대조했다. 클라이언트를 변경할 때도 이 코드로 비교할 수 있다.
연결 대상을 전환하는 작업에서는 설정값과 완성된 URL을 세트로 확인한다. 이번의 경우, /gateway/v1와 chat/completions 조합이 기대하는 경로에 도달하는 형태였다. 전송 전에 경로 누락이나 중복을 잡아내면, 그 이후 연결 확인에서 조사 범위를 줄일 수 있다. 나는 먼저 이 대조를 거친 후에 실제 서버에서 인증과 응답을 확인하는 절차로 삼는다.