모델이 실행되기 전
사용자는 프롬프트와 cheap, fast, smart 같은 별칭을 제공합니다. 프로덕션 서버는 작업을 수락하기 전에 인증, 워크스페이스 소유권, 엔타이틀먼트를 확인합니다. 프로바이더 모델 ID와 시크릿은 그 경계 뒤에 유지됩니다 — 실제 프로바이더 모델로의 매핑은 계약이 아니라 구성이므로, 친근한 별칭이 클라이언트에 필요한 유일한 모델 어휘입니다.
내구성 있는 작업 레코드는 백그라운드 실행이 시작되기 전에 요청에 ID를 부여합니다. 그 ID는 제출, 워커, 사용량 레코드, 결과를 연결합니다. 사용자가 다른 곳으로 이동한 후 작업을 복구할 방법도 제공합니다.
순서가 중요합니다: 비싼 작업은 저렴한 검사를 통과한 뒤에만 시작합니다. 무엇이든 큐에 넣기 전에 인증, 소유권, 엔타이틀먼트를 검증하면 인증되지 않았거나 미지불 요청이 프로바이더에 도달하지 않고 — 실패를 사용자에게 설명 가능하게 만듭니다. AI 모듈 가이드는 그 검사들이 어디 있는지 문서화하고, 워크스페이스 경계 포스트는 소유권이 클라이언트에서 신뢰되는 대신 서버에서 도출되는 이유를 설명합니다.
누구의 키이고 누구의 한도인지 결정하세요
AI 기능은 지출 결정입니다. supastack은 워크스페이스가 자체 프로바이더 키를 가져오거나 — 암호화되어 저장되고 클라이언트에 절대 노출되지 않음 — 플랫폼 키로 실행하게 하고, 모델 가격 카탈로그에 대해 워크스페이스별 예산을 강제합니다. 구현이 무엇이든 질문은 같습니다: 누가 지불하는가, 그리고 한도는 어디서 강제되는가?
강제는 브라우저 측 추정이 아니라 서버 워크플로에 속합니다. 생성 후에 검사되는 예산은 초과 지출을 기록할 뿐이고, 디스패치 전에 검사되면 그것을 방지합니다. 프로바이더 키 설정이 구성 측을 다룹니다.
실행을 명시적으로 만드세요
Trigger.dev가 ai.generate 워크플로를 실행합니다. capability 인식 라우터가 구성된 정책과 요청 요구 사항에 따라 모델을 선택합니다. 그 정책을 운영 입력으로 취급하세요: 사용할 수 없는 별칭이 인터페이스에 작동하는 선택지로 나타나서는 안 됩니다.
제출 중 네트워크 장애는 작업이 큐에 들어갔는지 클라이언트를 불확실하게 만들 수 있습니다. 프로덕션 경로는 작업 범위 멱등성 키와 저장된 제출을 사용해 복구가 원래 요청을 재사용하게 합니다. 타임아웃마다 새 작업을 내면 중복된 작업과 비용의 위험이 있습니다.
내구성은 인터페이스를 단순하게 유지하는 것이기도 합니다: 화면은 재시도를 조율하는 대신 작업 상태를 읽어 렌더링합니다. 생성이 모델 호출, 도구 단계, 스케줄에 걸칠 때, 명시적 워크플로 계약 — enqueue, status, cancel — 이 “진행 중”을 정직하게 유지합니다.
실패 모드에 이름을 붙이세요
요청과 결과 사이에는 잘못되는 일의 구체적이고 유한한 집합이 있습니다. 추상적인 “오류”가 아니라 각각을 이름으로 설계하세요 — 모든 작업은 설명 가능한 상태로 끝나야 합니다: 큐 대기, 실행 중, 이유 있는 실패, 결과 있는 완료. 작업 복구가 복구 측의 킷 레퍼런스입니다.
그 아래의 인터페이스 요구 사항은 어떤 상태도 거짓말할 수 없다는 것입니다. 작업보다 오래 사는 스피너나 한 번도 실행되지 않은 작업의 성공 메시지는 발생을 기다리는 지원 티켓과 결제 분쟁입니다.
- 제출 타임아웃 — 다시 큐에 넣는 대신 저장된 제출과 작업 범위 멱등성 키로 복구.
- 작업 중 프로바이더 실패 — 인터페이스가 보여줄 수 있는 이유와 함께 작업을 실패로 표시.
- 예산 소진 — 지출 후가 아니라 디스패치 전에 거부.
- 사용자가 이탈 — 내구성 레코드와 복구 URL이 상태와 결과를 복원.
일어난 일을 추적하세요
생성은 텍스트 이상의 것을 만듭니다. 애플리케이션은 사용량과 작업 결과를 기록하고, 인터페이스는 인증된 API를 통해 상태를 읽습니다. 사용량 레코드가 예산을 강제 가능하게 합니다 — 결과가 반환된 뒤 추정되는 것이 아니라 반환되기 전에 기록됩니다.
완료 이메일은 별도의 전송 레코드를 가진 별도 단계입니다. 성공한 모델 응답이 이메일이 전송되었음을 확립하지는 않습니다. 이러한 결과를 구분해 두면 모델을 불필요하게 재실행하지 않고 장애를 설명하고 재시도하기 쉬워집니다.
결과에는 사용자가 돌아올 수 있는 자리도 필요합니다: 작업 페이지, 기록 목록, 완료 이메일에 담긴 복구 URL. 일시적인 알림에만 존재하는 생성은 두 번 만들어 달라는 요청을 받을 작업입니다.
모든 경계를 검증하세요
결정적 fake 어댑터로 먼저 애플리케이션의 결정을 테스트하세요: 거부된 액세스, 비활성화된 별칭, 중복 제출, 결과 복구, 일반 오류. 이 테스트는 프로바이더 자격 증명 없이 실행되어야 합니다.
그런 다음 실제 통합에는 명시적으로 옵트인하는 프로바이더 스모크 프로세스를 사용하세요. 문서화된 샌드박스 구성과 외부 호출 승인이 필요합니다. 이 구분은 일반 개발을 빠르게 유지하면서 프로덕션 증거를 구체적이고 추적 가능하게 만듭니다.
제품이 바뀌어도 그 분할을 안정적으로 유지하세요: 모든 경계 결정 근처의 결정적 커버리지로, 프로바이더 교체, 라우터 정책 변경, 새 별칭이 고객을 실패시키는 대신 테스트를 실패시키게 합니다.
SaaS의 AI 기능에 관한 흔한 질문
AI를 페이월 뒤에 두는 대화마다 나오는 몇 가지 질문이 있습니다.
- AI 기능의 인가는 어디서 일어나야 하나요? — 무엇이든 큐에 넣기 전에: 인증하고, 워크스페이스를 해석하고, 엔타이틀먼트를 확인한 뒤 작업을 만드세요. 생성 후에 실행되는 검사는 오용을 문서화할 뿐입니다.
- 자체 키(BYOK) 지원이 필요한가요? — 고객이 자체 프로바이더 관계를 가지고 있다면 그렇습니다: 누가 지불하고 누가 속도 제한을 소유하는지를 결정합니다. 키를 암호화해 저장하고 클라이언트에서 멀리 두세요 — AI 구성 가이드가 그 모델을 다룹니다.
- 재시도가 이중 청구하지 않게 하려면요? — 멱등성 키를 작업에 범위 지정하고 복구 중 저장된 제출을 재사용해서, 타임아웃이 두 번째 청구 가능한 실행을 만들 수 없게 하세요.
- 어떤 사용량 데이터를 기록해야 하나요? — 작업별로: 모델, 소비 단위, 가격 카탈로그 대비 비용, 워크스페이스 — 작업을 다시 실행하지 않고 예산을 강제하고 지출 질문에 답하기에 충분하게.
- 생성은 언제 백그라운드 작업에 속하나요? — 요청보다 오래 살 수 있을 때마다. 모델 지연, 재시도, 다단계 작업은 내구성 있는 실행을 지지합니다. 즉각적이고 저렴한 호출만 인라인에 속합니다.