자체 파이프라인 구축하기
파일 탐색 및 계획 생성 워크플로우를 설계하기 위한 개념 가이드.
이 가이드는 PlanToCode의 핵심 아키텍처 패턴을 개념적 청사진으로 추출합니다. 유사한 시스템을 구축하거나 특정 설계 결정이 내려진 이유를 이해하려는 경우, 이 문서는 재사용하거나 적응할 수 있는 기본 패턴을 다룹니다.
파이프라인 아키텍처 맵
작업 입력에서 계획 출력까지의 다단계 파이프라인 개요.
핵심 아키텍처 패턴
작업 큐 패턴
모든 LLM 기반 작업은 상태 추적, 취소 지원, 재시도 로직을 갖춘 백그라운드 작업으로 실행됩니다. 작업은 SQLite에 영속되어 앱 재시작 시에도 상태가 유지됩니다.
Benefits
- UI 응답성을 LLM 지연에서 분리
- 스트리밍 중간에 취소 가능
- Provides job history of all operations
- 지수 백오프로 재시도 지원
Pitfalls to Avoid
- 작업 상태 관리가 복잡성 추가
- 재시작 시 오래된 작업의 주의 깊은 처리 필요
- 대규모 응답에 대한 스트림 누적이 메모리 소비
워크플로우 오케스트레이터 패턴
다단계 워크플로우는 단계를 순차적으로 예약하고, 단계 간에 중간 데이터를 전달하고, 모든 단계에서 실패를 처리하는 오케스트레이터에 의해 조정됩니다.
Components
- 정의 로더가 워크플로우 JSON 스펙을 읽음
- 단계 스케줄러가 순서대로 단계를 디스패치
- 페이로드 빌더가 이전 출력에서 입력 구성
- 이벤트 이미터가 UI 업데이트를 위한 진행 게시
리포지토리 패턴
모든 영속은 SQLite 작업을 추상화하는 타입화된 리포지토리를 통해 이루어집니다. 이는 깔끔한 API를 제공하고, 테스팅을 가능하게 하며, 데이터베이스 액세스를 중앙화합니다.
Benefits
- 타입화된 액세스가 SQL 인젝션 방지
- 리포지토리를 테스팅용으로 목 가능
- 중앙화된 쿼리 최적화
- 일관된 오류 처리
Pipeline Steps
1. 작업 모델 정의하기
시스템에서 작업을 구성하는 것을 정의하는 것부터 시작하세요. PlanToCode는 작업 설명, 파일 선택, 모델 기본 설정이 있는 세션을 사용합니다.
히스토리 추적을 위한 버전 관리와 함께 전용 테이블에 작업 메타데이터를 저장하세요.
2. 작업 큐 구축하기
작업을 저장소에 영속하고, 상태 이벤트를 발생시키고, 취소를 지원하는 작업 큐를 만드세요. 작업은 프롬프트, 응답, 토큰, 비용을 추적해야 합니다.
병렬 LLM 요청을 제어하기 위해 세마포어 기반 동시성 제한기를 사용하세요.
3. 프로세서 구현하기
각 작업 유형은 프롬프트를 빌드하고, LLM을 호출하고, 응답을 파싱하는 프로세서가 필요합니다. 긴 출력에는 스트리밍을 사용하세요.
프로세서는 무상태여야 하며 작업 매개변수를 통해 모든 컨텍스트를 받아야 합니다.
4. 워크플로우 오케스트레이터 만들기
다단계 워크플로우의 경우, 단계를 예약하고, 중간 데이터를 관리하고, 실패를 처리하는 오케스트레이터를 구축하세요.
코드 변경 없이 쉽게 수정할 수 있도록 워크플로우 정의를 JSON으로 저장하세요.
5. 라우팅 레이어 추가하기
페이로드를 정규화하고, API 키를 관리하고, 사용량을 추적하는 서버 프록시를 통해 LLM 요청을 라우팅하세요.
프로바이더 자격 증명은 서버에 보관하세요; 데스크톱 클라이언트에 절대 포함하지 마세요.
아키텍처 결정
로컬 데이터베이스를 사용해야 할까요, 서버 측 저장소를 사용해야 할까요?
작업 상태와 아티팩트에는 로컬 SQLite를 사용하세요. 이것은 오프라인 작업과 빠른 쿼리를 가능하게 합니다. 청구 및 크로스 디바이스 상태에만 서버와 동기화하세요.
스트리밍 vs 비스트리밍 응답?
계획 생성과 점진적으로 표시되는 모든 출력에는 스트리밍을 사용하세요. 텍스트 개선과 같은 짧은 변환에는 비스트리밍을 사용하세요.
LLM 프로바이더 실패를 어떻게 처리할까요?
지수 백오프로 자동 재시도를 구현하세요. 복원력을 위해 OpenRouter와 같은 폴백 프로바이더를 고려하세요.
파일 내용은 어디서 로드해야 할까요?
프롬프트를 빌드하기 직전에 프로세서에서 파일 내용을 로드하세요. 이것은 최신 내용을 보장하고 작업 레코드에 큰 blob 저장을 피합니다.
사용자 정의 vs 재사용할 것
Customize
- 특정 사용 사례를 위한 프롬프트 템플릿
- 프로젝트 유형에 맞는 파일 탐색 패턴
- 출력 형식 (XML, JSON, Markdown)
- 작업 유형별 모델 선택
Reuse
- 상태 추적이 있는 작업 큐 아키텍처
- 워크플로우 오케스트레이터 패턴
- 영속을 위한 리포지토리 패턴
- 스트리밍 응답 처리
- 프로바이더 라우팅과 정규화
피해야 할 일반적인 함정
클라이언트에 API 키 포함
자격 증명을 안전하게 관리하는 서버 프록시를 통해 모든 LLM 요청을 라우팅하세요.
작업 상태를 영속하지 않음
Store every job with full prompt and response for review and recovery.
LLM 호출에서 UI 차단
응답성 있는 인터페이스를 위해 이벤트 기반 UI 업데이트와 함께 백그라운드 작업을 사용하세요.
토큰 한도 무시
전송 전에 토큰을 추정하고 컨텍스트 윈도우 내에 유지하기 위해 큰 입력을 청크하세요.
취소 지원 없음
스트리밍 청크 사이에 취소 플래그를 확인하고 서버로 전파하세요.
영속할 아티팩트
- Full prompt sent to the LLM (for debugging and review)
- 스트리밍 누적을 포함한 완전한 응답
- 프로바이더 응답의 토큰 수
- 모델 가격을 기반으로 계산된 비용
- 버전 관리를 위한 시스템 프롬프트 템플릿 식별자
- 다단계 흐름을 위한 워크플로우 중간 데이터
구현 노트
- 동시 읽기/쓰기 액세스를 위해 WAL 모드로 SQLite 사용
- 실행 중인 작업을 실패로 표시하는 정상 종료 구현
- 작업 처리 전 외부 의존성에 대한 헬스 체크 추가
- 디버깅을 위해 전체 컨텍스트와 함께 모든 LLM 오류 로깅
- 중복 읽기를 피하기 위해 짧은 TTL로 파일 내용 캐싱 고려