For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ko/docs/web/ai.md (or send Accept: text/markdown).

AI 기능

채팅, 태스크, 모델 정책, bring-your-own-key.

이 가이드에 대해 질문하기

가짜 AI를 사용해 본 다음 실제 공급자를 선택하세요

첫 번째 결과를 얻으려면 웹 자습서의 /dashboard 작업을 따르십시오. 즉, 로컬 흐름을 시작하고 프롬프트를 대기열에 추가한 후 실행하고 결과를 확인하세요. AI_PROVIDER=fake는 데이터를 외부 모델로 보내거나 유료 API 키를 사용하지 않고 반복 가능한 데모 응답을 반환합니다.

실제 생성을 위해서는 먼저 지속형 계정을 구성하고 AI 공급자를 선택한 후 아래 AI 구성을 따르세요. 데이터베이스 카탈로그에 모델과 해당 가격을 추가하고 각 별칭에 허용되는 모델을 선택한 다음 작업공간에 필요한 액세스 권한을 부여합니다. fast와 같은 별칭은 사용자에게 친숙한 선택입니다. 그 자체는 외부 공급자의 모델 ID가 아닙니다.

백그라운드 AI task에도 구성된 작업 서비스가 필요합니다. 모델 선택 항목이 표시되지 않으면 다시 시도하기 전에 카탈로그 및 별칭 정책을 검사하세요. 액세스가 거부되면 활성 작업공간의 자격을 검사하세요. 브라우저, 모바일 앱 또는 데스크톱 창이 아닌 웹 서버 구성에 모든 공급자 API 키를 유지하세요.

작업 라이프사이클 따라가기

프로덕션 작업 API는 작업을 영속화하고 Trigger.dev ai.generate 워크플로를 디스패치하기 전에 인증된 워크스페이스와 권한을 검증합니다. 라우터는 기능 요구 사항과 구성된 모델 정책을 적용합니다.

POST /api/ai/tasks
  → authenticated workspace + entitlement
  → durable task record
  → Trigger.dev ai.generate
  → model routing + generation
  → usage record + result
  → transactional completion delivery

별칭과 예산 구성

사용자는 활성화된 별칭을 선택합니다: cheap, fast, smart. 서버는 기본 모델 ID, 프로바이더 자격 증명, 워크스페이스 정책, 예산 적용을 제어합니다. 암호화된 자체 키 지원도 같은 서버 경계를 유지해야 합니다.

워크플로 의미를 명시적으로 유지

JobRunner는 enqueue, status, cancel만 약속합니다. Trigger.dev의 워크플로 의미는 명시적이며 내구성 있는 실행 동작을 포함합니다. 일반 계약에서 재시도나 스케줄링 보장을 추론하지 마세요.

프로덕션 제출 경로는 모호한 디스패치를 처리하기 위해 멱등성과 저장된 작업 복구를 사용합니다. 생성 완료는 완료 이메일 전송과 분리되어 있습니다.

설치 및 설정

AI_PROVIDER=fake가 개발을 결정적으로 유지합니다. 프로덕션 프로바이더는 서버 사이드에서 구성합니다(OpenAI, Anthropic 또는 OpenAI 호환 엔드포인트). 키는 클라이언트 번들에 들어가지 않습니다. AI_MODEL_POLICY는 사용자 대면 별칭(cheap, fast, smart)을 카탈로그 모델 id에 매핑하고, 빈 별칭은 해당 선택지를 인터페이스에서 제거합니다.

모델 카탈로그(ai-model-catalog)는 능력과 불변 가격 메타데이터를 담아 가격 변경 후에도 사용 기록이 설명 가능합니다.

POST /api/ai/tasks          → durable task + Trigger.dev dispatch
GET  /api/ai/tasks/{taskId}  → status + result
/chat                        → streaming assistant surface

구현 워크플로

채팅 표면은 워크스페이스 멤버별 스레드를 유지하고 chat-stream-runtime을 통해 토큰을 스트리밍합니다. 긴 생성은 태스크로 실행됩니다: API 경계에서 인가되고, ai.generate 워크플로가 실행하며, 멱등 서브미션 스토어를 통해 복구 가능합니다.

bring-your-own-key 모드는 프로바이더 키를 AES-GCM 엔벌로프로 저장합니다(CREDENTIAL_ENCRYPTION_KEY, byok-key-vault.ts). 복호화는 서버 실행 경로 안에서만 일어납니다. 사용량과 추정 비용은 요청별로 기록되어 워크스페이스 예산에 공급됩니다.

검증 및 문제 해결

비활성 별칭이 인터페이스에 없는지, 엔타이틀먼트·예산 거부가 디스패치 전에 일어나는지, 재시도된 서브미션이 태스크를 재사용하는지, 저장된 BYOK 키가 클라이언트에 반환되지 않는지 확인합니다. 실제 모델 수용은 문서화된 프로바이더 smoke 경로에 두세요.