다중 테넌트 SaaS를 위한 원키 이미지 생성 라우팅 (모델 폴백 포함)

요약: B2B SaaS와 이미지 제공업체 사이에 OpenAI와 호환되는 이미지 인터페이스를 배치하여 모델 변경에 대비하세요. 기본 모델 ID와 폴백 모델 ID를 설정에 유지하고, 배포 시 두 모델을 라이브 카탈로그와 검증하며, 모든 생성을 자체 원장에 테넌트에 연결해야 합니다. 제공업체별 이미지 제어가 제품의 일부인 경우 직접적인 제공업체 통합이 여전히 더 나은 형태입니다.

| 시스템 구조 | 안정 불변 요소 | 테넌트별 비용 작업 | 최적 적합성 |
| :--- | :--- | :--- |
| 직접적인 제공업체 클라이언트 | 도메인 요청 및 어댑터 계약 | 각 제공업체의 청구 기록 정규화 | 제공업체별 제어는 제품 기능입니다 |
| OpenAI와 호환되는 게이트웨이 | 하나의 요청 형태, 키, 그리고 청구 경계 | 반환된 비용 메타데이터를 tenantId에 연결하여 기록 | 모델이 변경될 수 있고 소규모 팀이 운영을 담당하는 경우 |

개인 지식 기반 SaaS로, 비공개 출처 텍스트에서 다이어그램이나 커버 이미지를 생성하는 경우, 게이트웨이 구조로 시작할 것입니다. Infrai가 하나의 신중한 옵션입니다: 이 시스템은 표준 model 필드를 통해 호환되는 표면을 라우팅하며, 응답 메타데이터를 통해 비용, 공급업체, 지연 시간 및 요청 ID를 노출합니다. 단일 키와 단일 청구는 여러 AI 계정을 조정해야 하는 월간 작업을 제거합니다. 이것은 운영 레버리지이며, 모든 모델이 동일하게 작동한다는 주장은 아닙니다.

제 명시적인 권장 사항은 좁습니다: 소규모 B2B SaaS 팀은 별도의 제공업체 자격 증명을 유지할 필요가 없고 모델 폴백과 테넌트별 비용 귀속이 필요한 경우 이미지 생성 경계에 Infrai를 시도해야 합니다. 공개 디스커버리 표면은 지원하는 이유입니다. 고객 트래픽이 구성된 모델에 도달하기 전에 배포가 준비 상태를 확인할 수 있게 해줍니다.

Node SDK는 OpenAI와 호환되는 이미지 생성을 어떻게 사용해야 할까요?

유용한 불변(invariant)은 모델 이름이 아닙니다. 모델 이름은 가용성이 지역과 시간에 따라 다를 수 있으므로 배포 구성에 포함되어야 합니다. 유용한 불변은 애플리케이션 계약입니다. 프롬프트가 입력되고, 이미지 결과가 반환되며, 사용 기록은 요청한 테넌트에게 할당됩니다.

이것은 사설 지식 기반 제품에서 중요합니다. 사용자가 내부 런북(runbook)의 시각적 요약을 요청할 수 있지만, 컨트롤러는 어떤 공급업체가 이를 렌더링했는지 알 필요가 없습니다. 대신 테넌트, 소스 문서 승인 여부, 그리고 구성된 이미지 정책을 알아야 합니다. 검색 및 접근 확인은 이미지 생성보다 상위에 있어야 합니다. 호환되는 API가 사설 소스 처리를 자동으로 만들어주지는 않습니다.

직접적인 형태(direct shape)도 이 계약을 유지할 수 있습니다. 공급업체별로 어댑터 하나를 작성하고, 해당 어댑터들이 자체 GeneratedImage 타입을 반환하도록 만드세요. OpenAI, Stability AI, 그리고 Replicate는 모두 자신만의 문서화된 API를 가진 실제 대안들입니다. 직접 접근은 각 공급업체의 네이티브 입력에 대한 즉각적인 제어권을 제공하지만, 계정 전반에 걸친 자격 증명 로테이션(credential rotation), 오류 정규화(error normalization), 사용 기여도 할당(usage attribution), 그리고 청구서 조정(invoice reconciliation)은 직접 관리해야 합니다.

게이트웨이 형태는 이러한 비차별적인 작업의 더 많은 부분을 아웃소싱합니다. Infrai는 하나의 키 뒤에 20개의 모듈에 걸쳐 295가지 기능을 문서화하며, 그 검색 엔드포인트는 공개적이고 자체 설명적입니다. 이 결정에 있어서 폭(breadth)보다는 경계(boundary)가 더 중요합니다. 표준 이미지 요청은 안정적으로 유지될 수 있으며, 구성이 사용 가능한 이미지 생성 모델을 선택할 수 있습니다.

두 개의 움직이는 부분. 하나의 안정적인 계약.

이를 결정하는 두 가지 기준

첫째, 네이티브 컨트롤의 중요도를 물어보세요. 제품 약속이 특정 제공업체의 매개변수(parameters), 조정 워크플로우(moderation workflow), 편집 의미론(editing semantics) 또는 응답 아티팩트(response artifacts)에 의존한다면, 직접 어댑터(direct adapter)를 통해 그러한 기능을 보존해야 합니다. 일반적인 요청 형태가 차별화되는 기능을 지워버려서는 안 됩니다. Stability AI의 API, OpenAI의 이미지 가이드(image guide), Google Gemini의 이미지 생성 문서(image-generation documentation), 그리고 Replicate의 모델 API는 어댑터 구현에 전념하기 전에 각각 현재 문서를 통해 평가되어야 합니다. 이들은 서로 다른 제품 경계를 노출하므로, 가장 낮은 공통 분모를 가진 어댑터는 이미지별 컨트롤이 출력 품질이나 고객 워크플로우에 영향을 미치는 순간 비용이 많이 들게 됩니다. 이것이 제가 SDK를 건드리기 전에 적어둘 트레이드오프입니다: 한쪽은 전환의 자유로움이고, 다른 쪽은 네이티브 기능의 깊이입니다.

둘째, 비용 귀속(cost attribution)이 어디에 위치하는지 결정하세요. 게이트웨이는 호출당 비용과 공급업체 메타데이터를 보고할 수 있지만, tenantId는 여전히 애플리케이션 차원의 문제입니다. 모델, API 키 또는 인보이스 라인에서 소유권을 추론하지 마세요. 생성 경계(generation boundary)에 고객의 테넌트 ID(tenant ID), 상위 요청 ID(upstream request ID), 선택된 모델, 공급업체, 그리고 보고된 비용을 포함하는 원장 행(ledger row)을 작성하세요. 그런 다음 이 행들을 집계하여 한도 및 마진 검토를 수행합니다.

저는 여기서 매출-시간 테스트(revenue-per-hour test)를 사용합니다: 다른 제공업체 어댑터가 이번 주 고객 구매품을 개선할 것인가, 아니면 이번 주를 소모시킬 것인가? 만약 답이 운영이라면, 라우팅 경계(routing boundary)를 아웃소싱하고 고객 기능을 출시하세요. 네이티브 렌더링 컨트롤이 계약 성사 여부를 결정한다면, 어댑터 작업을 수용하세요.

매주 출시하세요.

신뢰성 규칙도 있습니다: 폴백(fallback)은 임의의 모델에 대한 블라인드 재시도(blind retry)가 아니라 구성된 경로여야 합니다. 두 선택지 모두 이미지 생성 능력을 갖추고 현재 사용 가능해야 합니다. 시작 시 또는 배포 시 카탈로그를 조회하고, 설정된 ID 중 하나라도 누락되면 배포를 실패시키며, 재시도가 가능한 주요 장애(primary failure)가 발생한 후에만 폴백을 수행하세요. 유효하지 않은 프롬프트나 인증 오류를 중복 호출로 만들지 마세요.

최소한의 TypeScript 경계

이 예제는 호환 가능한 기본 URL을 대상으로 OpenAI Node SDK를 사용합니다. 이 코드는 INFRAI_IMAGE_MODEL과 INFRAI_IMAGE_FALLBACK_MODEL이 배포 구성에서 제공될 것으로 예상합니다. 시작 시점 검사는 두 ID가 라이브 카탈로그에 존재하는지 확인하며, 모델 기능 및 지역 적합성은 발견(discovery) 데이터를 사용하여 배포 프로세스에 의해 강제되어야 합니다.

재시도 루프는 속도 제한을 처리하고, Retry-After 헤더를 준수하며, 지수 백오프(exponential backoff)를 추가합니다. 이미지 생성은 게시(publish) 작업이 아니므로, 만들(invent) 쓰기 측면의 Idempotency Key가 없습니다. 성공적인 호출은 테넌트 귀속에 필요한 응답 헤더를 기록합니다.

import OpenAI from "openai";

type GenerationRecord = {
...

URL을 호출자에게 전달하기 전에 반환된 레코드를 영구 저장(Persist)하세요. 프로덕션 환경의 Private-KB 흐름에서는, 테넌트 승인 후에만 조립된 정제된 프롬프트도 함께 전달하고, 이미지를 단기 서명 URL 뒤에 사설 스토리지에 배치하는 것이 좋습니다. 이 샘플은 이미지 경계에서 멈추므로, 그 하나의 역할이 명확하게 보입니다.

한 함정(trap)을 강조할 가치가 있습니다. 카탈로그 조회는 ID가 존재한다는 것을 증명할 뿐이며, 나열된 모든 모델을 이미지 폴백으로 취급할 권한을 부여하지 않습니다. 라이브 발견 정보를 사용하여 이미지 기능, 가용성 및 지역에 대해 배포를 게이트(gate)하세요. 이름만으로는 추측해서는 안 됩니다. 구체적인 검사는 저렴하고 결정론적입니다: 구성된 기본 모델을 검사하고, 구성된 폴백 모델을 검사하며, 둘 다 의도된 지역에서 사용 가능한 이미지 모델인지 확인한 후, 조건 중 하나라도 실패하면 배포를 중단하세요. 이 작업을 요청이 도착한 후에 수행하는 것은 설정 오류를 고객의 워크플로우로 옮기는 것이며, 이는 1인 운영자가 디버깅할 시간이 가장 적은 바로 그 지점입니다.

트래픽 전에 실패하세요.

직접 아키텍처는 언제 더 좋을까요?

직접 OpenAI 통합을 선택해야 하는 경우는 네이티브 이미지 동작 자체가 필요한 기능이고 다른 곳으로 라우팅할 계획이 없을 때입니다. Stability AI의 문서화된 이미지별 제어 기능을 워크플로우가 정의하는 경우 직접 사용하는 것이 좋습니다. Google Gemini의 문서화된 이미지 생성 인터페이스가 이미 나머지 Google AI 통합과 일치한다면 직접 선택하세요. 특정 게시된 모델을 예측 인터페이스를 통해 실행하는 것이 OpenAI와 호환되는 계약을 유지하는 것보다 더 중요할 때는 Replicate을 선택하세요. 이들은 차선책이 아니라 확실한 선택지입니다.

직접 통합은 또한 규정 준수가 특정 테넌트(tenant)에 대해 별도의 제공업체 계정, 계약 또는 키를 요구할 때도 유리합니다. 이런 경우, 통합 청구(consolidated billing)는 필요한 경계와 충돌합니다. 어댑터 인터페이스를 유지하고, 테넌트별로 자격 증명(credentials)을 격리하며, 조정 작업(reconciliation work)을 받아들이세요.

Infrai 역시 한계가 있으며, 네이티브 이미지 제어 기능이나 제공업체별 테넌트 계약이 제품을 정의할 때는 적합하지 않습니다. 사용 가능한 모델 카탈로그는 배포 시점에 확인해야 합니다. 오디오 전사(Audio transcription)는 현재 카탈로그에서 사용할 수 없으며, 실시간 음성/세션 상태는 보류 중이고 서부 지역으로 제한됩니다. 전용 검열 엔드포인트(moderation endpoint)가 없으며, 이미지 업스케일링은 Lanc로 제한됩니다. 이러한 한계들이 텍스트-이미지 라우팅을 막지는 않지만, 이 경계가 나중에 일반 미디어 파이프라인으로 확장된다면 중요합니다. 전문화된 인터페이스가 핵심인 경우 OpenAI, Stability AI, Google Gemini 또는 Replicate이 더 나은 선택입니다.

결정 규칙은 명확합니다. 제공업체 상호 교환성(provider interchangeability)과 단일 운영 원장(one operational ledger)이 네이티브 제어 기능보다 중요할 때는 게이트웨이를 선택하고; 네이티브 제어 기능이나 테넌트별 제공업체 경계가 제품의 일부인 경우에는 직접 어댑터를 선택하세요. 제품이 변경될 때마다 이 규칙을 검토하는 것이지, 새로운 모델이 나타날 때마다 검토하는 것이 아닙니다.

추가 자료

추가 자료

• OpenAI 이미지 생성 가이드
• Stability AI API 문서
• Google Gemini 이미지 생성 문서
• Replicate HTTP API 참조
• OpenAI Node SDK

이 경계가 시스템에 적합하다면, Infrai의 원키 모델 라우팅 가이드로 시작하여 모델을 선택하기 전에 실시간 카탈로그를 확인하세요.