45 lines
3.0 KiB
Markdown
45 lines
3.0 KiB
Markdown
# 파파고 번역 요청 길이 분할 PRD
|
|
|
|
| 항목 | 내용 |
|
|
|---|---|
|
|
| 상태 | 구현·기능 범위 검증 완료 |
|
|
| 작성일 | 2026-11-09 |
|
|
| 범위 승인 | 사용자: 파파고 번역만 요청당 길이 제한에 맞춰 분할 호출 |
|
|
| 구현 계획 | [plan-task.md](plan-task.md) |
|
|
|
|
## 목적과 범위
|
|
|
|
현재 `PapagoTranslationService`는 각 필드를 한 번에 전송하여 5,000자를 넘으면 번역에 실패한다.
|
|
서비스 내부에서 긴 원문을 순서대로 분할 호출하고 결과를 하나로 합쳐 기존 호출자가 그대로 사용하게 한다.
|
|
AWS 추가, 언어 감지, DB 구조, 워커 재시도 정책, 공개 API, 새 의존성은 변경하지 않는다.
|
|
|
|
## 요구사항
|
|
|
|
| ID | 요구사항과 수용 기준 |
|
|
|---|---|
|
|
| PC-001 | 각 HTTP 요청의 `text`는 최대 5,000 UTF-16 코드 단위이다. 5,000 이하는 한 번, 5,001 이상은 여러 번 호출한다. |
|
|
| PC-002 | 분할은 원문 순서와 모든 문자를 보존하며 유효한 서로게이트 쌍을 끊지 않는다. 요청 텍스트를 결합하면 원문과 정확히 같다. |
|
|
| PC-003 | 각 입력 텍스트의 번역 조각을 순서대로 구분자 없이 결합하여 기존 `TranslateResult`의 텍스트별 대응을 유지한다. |
|
|
| PC-004 | 어느 조각이든 HTTP 오류 또는 빈 번역 결과이면 부분 번역을 성공 결과로 반환하지 않는다. 기존 워커가 실패로 판단할 빈 결과를 반환하고 이후 조각은 호출하지 않는다. |
|
|
| PC-005 | 빈 입력 목록, 동일 언어, 미지원 언어의 기존 무호출 동작 및 짧은 텍스트 호출 형식을 유지한다. |
|
|
|
|
## 기술 결정과 한계
|
|
|
|
- 공식 문서는 요청당 최대 5,000 characters를 명시하지만 Unicode 계산 방식은 명시하지 않는다.
|
|
구현은 보수적으로 UTF-16 길이를 제한하고 서로게이트 경계만 조정한다.
|
|
- 길이 기준 고정 분할을 사용한다. 문장 분석, 문맥 품질 보정, 조각 캐시, 병렬 호출은 이번 범위가 아니다.
|
|
- 모든 조각 성공 후에만 기존 전체 원문 기준 번역 캐시에 저장할 수 있도록 한다.
|
|
- 분할 시 HTTP 호출 수가 증가하며 중간 실패 후 기존 워커 재시도에서는 앞선 조각도 다시 호출될 수 있다.
|
|
- 원문과 자격증명을 오류 로그나 문서에 기록하지 않는다.
|
|
|
|
## 검증 기준
|
|
|
|
- 실제 서비스의 HTTP 요청 경계에서 5,000/5,001/10,001자, 한글, 이모지, 여러 입력, 중간 오류와 빈 응답을 검증한다.
|
|
- 기존 번역 워커·스케줄러 회귀 테스트와 `bootJar`를 실행한다. 전체 테스트는 저장소 정책대로 사용자 실행이다.
|
|
- 실제 유료 Papago 호출 대신 가짜 자격증명과 로컬 HTTP 서버를 사용하며 실서비스 번역 품질 검증과 구분한다.
|
|
|
|
## 근거
|
|
|
|
- [Papago Text Translation 요청 규격](https://api.ncloud-docs.com/docs/en/ai-naver-papagonmt-translation)
|
|
- [Papago 오류 코드](https://api.ncloud-docs.com/docs/en/ai-naver-papagonmt): `N2MT08`, `text parameter exceeds max length`.
|