기사 디렉토리
Cloudflare AI 기본 URL이 항상 404 오류를 반환하는 이유는 무엇인가요?
이 글에서는 Cloudflare와 호환되는 OpenAI 기본 URL을 몇 초 만에 빠르게 얻고 설정하는 방법을 알려드립니다. 공식 REST API, AI Gateway 형식, 그리고 타사 클라이언트(Dify/One-API)에 맞는 완벽한 템플릿을 제공하여 단 한 번의 클릭으로 무료 AI API를 바로 사용할 수 있도록 도와줍니다!
지난주에 독립 개발자인 친구가 갑자기 연락해서 401 오류로 가득 찬 화면 스크린샷을 보내왔습니다. 그는 "형, 오늘 하루 종일 클라우드플레어 AI API 디버깅을 해봤는데 도저히 안 돼."라고 말했습니다.
그의 코드를 슬쩍 봤다. 기본 URL은 /ai/v1로 설정되어 있었지만, 요청 본문은 공식 REST API 형식이었기 때문에 두 가지가 전혀 일치하지 않았다.
그는 OpenAI SDK를 사용하여 Workers AI에서 모델을 디버깅하고 싶다고 했는데, 문제가 있을까요?
이건 심각한 문제입니다.
Cloudflare의 AI 서비스는 시나리오에 따라 완전히 다른 세 가지 기본 URL을 사용합니다. 각 URL은 고유한 형식과 적용 시나리오를 가지고 있습니다. 관련 문서가 존재하지만 여러 페이지에 흩어져 있어 처음 접속할 때 어떤 문서를 참조해야 할지 파악하기 어렵습니다. 잘못된 URL을 사용하면 401 또는 400 오류가 발생하여 서비스에 접속할 수 없습니다.
처음에 이 문제를 접했을 때, 해결 방법을 찾기까지 여러 번 시도해야 했습니다. 오류 메시지로 가득 찬 화면을 보고는 말문이 막혔습니다.
오늘은 여러분이 더 이상 실수를 하지 않도록 이 세 가지 길을 명확하게 그려드리겠습니다.
OpenAI 호환 인터페이스 기본 URL
가장 흔히 사용되는 것부터 시작해 봅시다.
OpenAI SDK 또는 LangChain, Dify, NextChat, One-API와 같이 사용자 지정 OpenAI 형식을 지원하는 도구를 사용하는 경우 이 방법이 올바릅니다.
https://api.cloudflare.com/client/v4/accounts/{你的account_id}/ai/v1
이것은 Cloudflare가 OpenAI 인터페이스 형식에 맞춰 특별히 설계한 것입니다. 전체 대화 엔드포인트 뒤에 `/chat/completions`를 추가하세요. 기존 OpenAI 기본 URL을 이 주소로 바꾸고, API 키를 Cloudflare 토큰으로 바꾸면 바로 실행될 것입니다. `@cf/deepseek-ai/deepseek-r1-distill-qwen-32b`와 `@cf/meta/llama-3.1-8b-instruct` 같은 모델을 사용해 봤는데 모두 정상적으로 작동했습니다.
하지만 이는 텍스트 기반 대화 모델만 지원한다는 점에 유의해야 합니다.
Cloudflare의 공식 네이티브 REST API
그래프 작성을 위해 Stable Diffusion을 사용하거나, 오디오 전사를 위해 Whisper를 사용하거나, 또는 텍스트 이외의 모델을 사용해야 하는 경우, 두 번째 방법인 Cloudflare 공식 네이티브 REST API를 이용하세요.
https://api.cloudflare.com/client/v4/accounts/{你的account_id}/ai/run
모델 이름은 경로에 직접 입력할 수도 있고(예: /ai/run/@cf/bytedance/stable-diffusion-xl-lightning), 요청 본문의 `model` 필드에 입력할 수도 있습니다. 저는 경로가 더 간결하고 깔끔하기 때문에 `model` 필드에 입력하는 방식을 선호합니다. 저도 처음에는 이 부분에서 혼란스러웠습니다. 일부 모델은 두 가지 방법 모두를 지원하지만, 다른 모델은 한 가지 방법만 지원합니다. 문서를 확인할 때 이 점에 유의하세요.
AI 게이트웨이 기본 URL
세 번째 방법이 있습니다. 바로 AI 게이트웨이입니다.
이 시나리오는 약간 다릅니다. Cloudflare 백엔드에 AI 게이트웨이를 설정하여 타사 API를 프록시하는 경우(예: OpenAI 요청을 캐싱, 모니터링 및 속도 제한을 위해 Cloudflare 게이트웨이를 통해 전달하는 경우) 기본 URL은 다음과 같습니다...
https://gateway.ai.cloudflare.com/v1/{你的account_id}/{你的gateway_id}/openai
완료 엔드포인트 뒤에 `/chat/completions`를 추가하면 모든 트래픽이 Cloudflare 게이트웨이를 통해 전송되고, 로그 패널에 각 요청의 지연 시간과 결과가 표시됩니다. 이 기능은 팀 규모가 커지고 프로젝트가 많아질수록 여러 공급업체의 백엔드에서 데이터를 하나씩 검색해야 하는 번거로움을 없애주어 매우 유용합니다.
선택 방법: 세 가지 URL 세트를 한 문장으로 설명합니다.
네, 세 가지 경로를 모두 살펴봤습니다. 요약하자면, 원칙은 단 하나입니다.
당신이 걸어갈 길은 당신이 사용하는 도구에 달려 있습니다.
OpenAI SDK를 사용하여 대화 모델을 호출하려면 `/ai/v1`로 이동하세요. 이미지/오디오 모델을 호출하려면 `/ai/run`으로 이동하세요. 게이트웨이를 통한 통합 관리를 위해서는 `/gateway/`로 이동하세요. 인증 방법은 동일합니다. 헤더에 `Authorization: Bearer` 뒤에 API 토큰을 입력하세요. Cloudflare 백엔드에서 토큰을 생성하고 `Workers AI: Edit` 권한을 확인하는 것을 잊지 마세요.
account_id는 어디에서 찾을 수 있나요? Cloudflare 관리자 패널에 로그인하고 오른쪽 사이드바의 API 섹션으로 스크롤하거나 브라우저 주소 표시줄을 확인하세요. 32자리의 영숫자 문자열이 바로 account_id입니다.
솔직히 말해서, 그날 친구가 그 일을 끝내는 걸 도와준 후에 친구가 제게 한 말이 꽤 맞는 것 같아요. 제가 방법을 몰랐던 게 아니라, 설명서가 그 방법을 명확하게 설명해주지 않았던 거라는 거죠.
많은 기술 설정이 이와 같습니다. 특별히 어려운 것은 아니지만, 진입점이 너무 많아 처음 시도할 때 길을 잃기 쉽습니다. Cloudflare AI를 설정하는 동안 설명할 수 없는 오류가 발생했다면, 기본 URL이 잘못되었거나 형식이 잘못되었을 가능성이 큽니다. 다음 세 가지 URL 세트를 잘 보관해 두면 다음에 같은 문제가 발생했을 때 쉽게 찾을 수 있습니다.
천만에요.
여기까지 읽어주셔서 감사합니다. 도움이 되셨다면 좋아요와 공유 부탁드립니다. 최신 소식을 가장 먼저 받아보고 싶으시다면 팔로우도 해주세요! ⭐
제 글을 읽어주셔서 감사합니다. 다음에 또 뵙겠습니다.
Chen Weiliang의 블로그( https://www.chenweiliang.com/ ) 에 공유된 "오류 보고를 멈추세요! OpenAI 호환성을 위해 Cloudflare를 쉽게 구성하세요"라는 글이 도움이 되기를 바랍니다.
이 기사 링크( https://www.chenweiliang.com/cwl-34252.html )를 자유롭게 공유해 주세요.