Cloudflare AI Gateway, 정말 최고죠.

무료로 로깅(Logging)이나 캐싱(Caching), 인증 정보의 집약 등을 할 수 있는 매우 편리한 신의 서비스입니다. 출시 직후부터 상당히 많이 사용하고 있습니다.

사용법은 간단하며, 요청 대상의 Base URL을 변경하기만 하면 됩니다.

• 변경 전:
  https://api.openai.com/v1

• 변경 후:
  https://gateway.ai.cloudflare.com/v1/<account-id>/<gateway-id>/openai

이것만으로 Cloudflare AI Gateway를 경유하여 로그나 통계 등을 이용할 수 있습니다. 간단하죠.

한편 약점으로서, 대응하는 LLM 서비스가 다소 적다는 문제가 있었습니다. 그것을 해결하는 것이 Custom Providers 기능입니다.

이 기능을 사용함으로써 AI Gateway가 표준으로 대응하지 않는 LLM 프로바이더(Provider)에 대한 요청도 AI Gateway를 경유하여 전송할 수 있습니다. 당연히 AI Gateway의 각종 기능도 이용할 수 있습니다.

즉, 최고라는 뜻입니다.

다만, Custom Providers를 사용하고 있으면, 베타 버전이라서 그런 것인지 사양(Specification) 때문인지는 잘 모르겠지만, 의문스러운 동작 때문에 "어라, 접속이 안 되잖아" 하는 상황이 발생할 수 있습니다.

이 기사에서는 그 원인이 될 수 있는 의문스러운 사양 같은 동작과, 잠정적인 대처 방법을 기록합니다.

※ AI Gateway를 어느 정도 이해하고 있는 사람을 대상으로 하는 내용입니다.

Custom Providers의 의문스러운 사양이란?

Custom Providers에서는 설정한 Base URL의 끝부분에 따라 실제 요청 대상 경로(Path)가 변화합니다.

이 동작으로 인해 의도한 URL로 요청이 라우팅(Routing)되지 않는 경우가 있습니다.

/v1인 경우 (신규 생성 시에만)

Base URL의 끝부분이 Custom Provider 신규 생성 시의 Base URL 끝부분을 /v1로 설정하면, 왜인지 끝부분의 /v1이 제거된 상태로 요청이 전송됩니다.

https://example.com/v1인 경우

예: Base URL이

• AI Gateway로의 요청:
  https://gateway.ai.cloudflare.com/v1/<account-id>/<gateway-id>/custom-<slug>/models

• 요청 대상:
  https://example.com/models

https://example.com/v1/models가 되지 않습니다.

• 요청 대상:

• AI Gateway로의 요청:
  https://gateway.ai.cloudflare.com/v1/<account-id>/<gateway-id>/custom-<slug>/v1/models

• 요청 대상:
  https://example.com/v1/models

https://example.com/v1/v1/models가 되지 않습니다.

• 요청 대상:

왜일까요?

게다가, 후술할 다른 패턴으로 Custom Provider를 생성한 후, Base URL을 https://example.com/v1로 변경했을 경우에는 이 동작이 재현되지 않습니다.

/v[^/]+$에 매치되는 경우

Base URL의 끝부분이 Base URL의 끝부분이 /vABCDE와 같은 버전 형식의 세그먼트(Segment)로 되어 있는 경우, 해당 세그먼트는 실질적으로 무시됩니다.

그 상태에서 실제 요청 대상은 다음과 같이 결정되는 것으로 보입니다.

• 요청 경로가 버전 형식의 세그먼트로 시작하는 경우, 해당 세그먼트를 사용한다.
• 요청 경로가 버전 형식의 세그먼트로 시작하지 않는 경우, 맨 앞에 /v1을 자동으로 부가한다.

신규 생성이 아니라, 이미 생성된 Custom Provider의 Base URL을 /v1로 끝나는 값으로 변경했을 경우에도 이 동작이 적용됩니다.

https://example.com/vABCDE인 경우

예: Base URL이

• AI Gateway로의 요청:
  https://gateway.ai.cloudflare.com/v1/<account-id>/<gateway-id>/custom-<slug>/models

• 요청 대상:

https://example.com/v1/models

https://example.com/vABCDE/models

이런 형태가 되지는 않습니다.

• 요청 대상:

AI Gateway로의 요청:

https://gateway.ai.cloudflare.com/v1/<account-id>/<gateway-id>/custom-<slug>/v1/models

• 요청 대상:

https://example.com/v1/models

https://example.com/vABCDE/v1/models

이런 형태가 되지는 않습니다.

• 요청 대상:-

AI Gateway로의 요청:

https://gateway.ai.cloudflare.com/v1/<account-id>/<gateway-id>/custom-<slug>/v2/models

• 요청 대상:

https://example.com/v2/models

https://example.com/vABCDE/v2/models

이런 형태가 되지는 않습니다.

• 요청 대상:-
• 왜일까요?

/v[^/]+$
에 매치하지 않는 경우

Base URL의 끝부분이 Base URL의 끝부분이 버전 형식의 세그먼트(segment)가 아닐 경우, 실제 요청 경로는 다음과 같이 결정되는 것 같습니다.

• 요청 경로가 버전 형식의 세그먼트로 시작하는 경우, 해당 경로를 그대로 Base URL에 결합합니다.
• 요청 경로가 버전 형식의 세그먼트로 시작하지 않는 경우, 앞에 /v1을 자동으로 붙입니다.

https://example.com

인 경우
예시: Base URL이 - AI Gateway로의 요청:

https://gateway.ai.cloudflare.com/v1/<account-id>/<gateway-id>/custom-<slug>/models

• 요청 대상:

https://example.com/v1/models

https://example.com/models

이런 형태가 되지는 않습니다.

• 요청 대상:-
• AI Gateway로의 요청:

https://gateway.ai.cloudflare.com/v1/<account-id>/<gateway-id>/custom-<slug>/v1/models

• 요청 대상:

https://example.com/v1/models

• 요청 대상:-
• AI Gateway로의 요청:

https://gateway.ai.cloudflare.com/v1/<account-id>/<gateway-id>/custom-<slug>/v2/models

• 요청 대상:

https://example.com/v2/models

• 요청 대상:

대처 방법

일반적인 API에서는 이러한 동작이 문제가 되는 경우가 많지 않습니다.

하지만 일부 서비스의 경우, Base URL의 끝부분이 재작성됨으로써 요청에 실패합니다.

예를 들어 Z.ai Coding Plan (GLM Coding Plan)의 원래 Base URL은 다음 URL입니다.

이를 그대로 Custom Provider로 등록하면, 요청 시 끝부분의 v4가 무시되고 대신 v1이 사용됩니다.

그 결과, 예를 들어 다음과 같은 URL로 요청이 전송되어 404 Not Found가 발생합니다.

임시적인 대처 방법으로는, 찝찝하지만 Custom Provider를 생성할 때 원래 Base URL의 끝부분에 /v1을 추가하여 등록하는 것입니다.

Z.ai Coding Plan의 경우, 다음과 같이 등록합니다.

새로 생성될 때의 동작으로 인해 끝부분에 추가한 /v1이 제거되므로, 실제 요청 대상에는 원래의 /v4를 유지할 수 있습니다.

그렇다고 해도 너무 불분명한 동작이며 문서에 기재된 내용과도 다르기 때문에 향후 변경될 가능성이 높아 보입니다 (베타 버전이니까).

그리고 전혀 관계없는 이야기지만 2026년 7월 시점에서는 AI Gateway의 문서에서 권장하는 REST API가 아직 불안정한 것 같아 추천하기 어렵습니다.

현시점에서는 아직 Unified API를 추천합니다 (Deprecated 되었지만…)

Discussion