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/setup-ai.md (or send Accept: text/markdown).
AI 설정
cheap / fast / smart 별칭 뒤의 실제 모델 — 키는 서버에 남습니다.
설치 및 설정
어떤 단계를 시작하기 전에 시작하기 전에 및 터미널 기본 사항을 읽어보세요. 이 지침에서는 VS Code에서 전체 supastack 단일 저장소를 열었다고 가정합니다. 해당 루트 package.json은 저장소 루트를 표시합니다. pnpm 명령에서 작업 영역 패키지는 앱 또는 공유 코드 폴더입니다. 제품에서 작업공간은 팀의 데이터 컨테이너이자 보안 경계입니다. corepack pnpm --filter ... 명령이 해당 루트에서 실행되는 동안 monorepo에서 하나의 패키지를 선택합니다. 동기화된 모바일 또는 데스크톱 폴더만 열었다면 웹 백엔드, Docker 설정 또는 루트 스크립트가 포함되지 않습니다. 이 모노 저장소 또는 연결 가능한 호스팅 서버에서 백엔드를 실행하고 플랫폼 폴더의 자체 스크립트를 사용하세요. 환경 변수는 로컬 .env 파일이나 호스팅 대시보드에 저장된 명명된 설정입니다. 관련 앱을 변경한 후 다시 시작하고, NEXT_PUBLIC_ 및 EXPO_PUBLIC_ 값에서 서버 비밀을 유지하세요.
1. 로컬 웹 서버용 apps/web/.env.local를 열고 공급자 선택용 apps/web/src/agent-runtime.ts를 엽니다. .env.example은 지원되는 설정 이름 목록입니다.
2. 자체 공급자 계정이 있고 실제 생성을 테스트하려는 경우가 아니면 로컬 인터페이스 작업을 위해 AI_PROVIDER=fake를 유지하십시오. NEXT_PUBLIC_ 또는 EXPO_PUBLIC_ 설정에 공급자 키를 넣지 마십시오.
3. corepack pnpm --filter @supastack/web dev를 사용하여 리포지토리 루트에서 웹 앱을 시작합니다. 예상: 유료 공급자를 구성하지 않고도 로컬 화면을 탐색할 수 있습니다. 실제 생성에는 유효한 서버 공급자가 필요하며 데이터베이스 카탈로그에서 활성화된 모델 선택이 필요합니다.
기본 AI_PROVIDER=fake는 결정적 로컬 작업을 지원합니다. 실제 프로바이더 구성은 서버 환경에 속합니다. .env.example에 나열된 프로바이더 키에는 OpenAI, Anthropic, OpenAI 호환 엔드포인트가 포함됩니다.
AI_MODEL_POLICY에는 cheap, fast, smart 별칭용 순서가 지정된 모델 ID가 들어 있습니다. 빈 별칭 목록은 그 선택지를 비활성화합니다. 모델 ID는 유효한 불변 가격이 있는 활성화된 카탈로그 행과 일치해야 합니다.
AI_MODEL_POLICY='{"cheap":[],"fast":["catalog-model-id"],"smart":["catalog-model-id"]}'
AGENT_FRAMEWORK=ai-sdk # ai-sdk | mastra | langgraph | openai-agents복사 명령
설명을 따라 명령이 실행되는 폴더를 확인하세요. 두 개의 터미널에 레이블이 지정되어 있으면 두 개의 터미널 창을 열고 두 번째 명령을 사용하는 동안 첫 번째 명령을 계속 실행하세요.
corepack pnpm --filter @supastack/web dev구현 워크플로
프로덕션 작업을 수락하기 전에 카탈로그와 워크스페이스 정책을 구성하세요. 브라우저는 활성화된 별칭을 받고, 기능 매칭, 모델 선택, 권한 검사, 예산 적용은 서버에 남습니다.
자격 증명을 NEXT_PUBLIC_ 및 EXPO_PUBLIC_ 변수 밖에 두세요. 자체 키 모드에는 기존 암호화 봉투와 서버 복호화 경계를 사용하세요. 저장된 프로바이더 키를 인터페이스에 반환하지 마세요.
검증 및 문제 해결
앱에서 사용할 수 있는 AI 모델이 없다고 보고하는 경우 서버의 AI_PROVIDER, 관리자 카탈로그의 활성화된 모델 및 가격, 저렴하고 빠른/스마트 별칭 정책을 확인하세요. 실제 공급자가 인증 오류를 반환하는 경우 apps/web/.env.local에서 해당 키를 확인하고 서버를 다시 시작하세요. 접두사가 NEXT_PUBLIC_인 키는 브라우저에 표시되므로 제거해야 합니다.
비활성화된 별칭, 누락된 기능, 비활성 권한, 소진된 예산을 검증하세요. 실제 생성에는 별도로 승인된 프로바이더 스모크 실행을 사용하세요. 사용 가능한 별칭이 없으면 원시 모델 선택기를 노출하는 대신 서버 정책과 카탈로그 구성을 검사하세요.
설정을 계속하려면 백그라운드 작업 설정 가이드를 읽어보세요.