docs: add async rule for long-running HTTP tasks

This commit is contained in:
Claude-51124 2025-12-02 02:08:20 +09:00
parent 4acf663593
commit 7f14b107d1

View File

@ -229,7 +229,20 @@ utils
- 호출 횟수 미검토 시 API 할당량 초과(429 에러) 발생 가능
- 단일 프롬프트로 통합 가능한 작업은 반드시 통합하여 호출 횟수 최소화
## 14. 모범 사례 참고
## 14. 장기 작업(LLM/RAG 등) 처리 원칙
**핵심 원칙**: HTTP 요청으로 노출되는 장기 작업(LLM, RAG, 대용량 PDF 처리 등)은 동기식으로 붙잡지 말고, 항상 "즉시 ID 반환 + 비동기 백그라운드 작업 + 후속 조회/웹훅" 패턴으로 설계한다.
### 권장 패턴
- `POST /api/.../start` → 백그라운드 작업 등록, 즉시 `job_id` 또는 `evaluation_id` 반환
- `GET /api/.../{id}` → 상태/결과 조회 (프론트는 폴링 또는 SSE/WebSocket 사용)
- 필요 시 웹훅/이벤트로 완료 알림 (Slack, 이메일 등)
### 금지 사항
- ❌ Nginx `proxy_read_timeout`에 의존해 60초 이상 동기식으로 응답을 붙잡는 설계
- ❌ LLM/RAG/외부 API 호출이 여러 단계로 이어지는 워크플로우를 단일 HTTP 요청에 모두 묶는 방식
## 15. 모범 사례 참고
본 문서는 FastAPI 커뮤니티의 다음 모범 사례를 반영하였습니다: