397efb86dc
git-subtree-dir: integrations/document-ai git-subtree-split: 9093611c9629c0de3db760878ec9929f50add5ed
102 lines
5.1 KiB
Markdown
102 lines
5.1 KiB
Markdown
# NLLB 번역 시스템 코딩 규칙
|
|
|
|
이 문서는 NLLB 번역 시스템 프로젝트의 코드 일관성과 품질을 유지하기 위한 코딩 규칙을 정의합니다.
|
|
|
|
## 1. 일반 원칙
|
|
|
|
- **언어**: 모든 코드와 주석은 **한국어**로 작성하는 것을 원칙으로 합니다. 단, 외부 라이브러리 이름이나 기술 용어 등은 예외로 합니다.
|
|
- **인코딩**: 모든 파일은 **UTF-8**로 인코딩합니다.
|
|
- **명령형**: 커밋 메시지, 함수/메서드 설명 등은 명령형(`~하기`, `~함`)으로 작성하여 명확성을 높입니다.
|
|
|
|
## 2. 코드 스타일
|
|
|
|
- **들여쓰기**: 공백 4칸을 사용합니다.
|
|
- **최대 줄 길이**: 한 줄은 120자를 넘지 않도록 합니다.
|
|
- **명명 규칙**:
|
|
- **변수**: `snake_case` (예: `translated_text`)
|
|
- **함수/메서드**: `snake_case` (예: `load_models`)
|
|
- **클래스**: `PascalCase` (예: `IntegratedTranslationSystem`)
|
|
- **상수**: `UPPER_SNAKE_CASE` (예: `NAS_MOUNT_POINT`)
|
|
- **주석**:
|
|
- 복잡한 로직이나 중요한 결정 사항에 대해서는 `#`을 사용하여 간결한 주석을 작성합니다.
|
|
- 파일의 목적과 전반적인 설명을 위해 파일 최상단에 `"""독스트링"""`을 작성합니다.
|
|
- **타입 힌팅**: 함수의 인자와 반환 값에는 타입 힌트를 명시하여 코드의 명확성을 높입니다. (예: `def process_document(input_path: str) -> TranslationResult:`)
|
|
|
|
## 3. Python 관련 규칙
|
|
|
|
- **임포트**:
|
|
1. 표준 라이브러리
|
|
2. 서드파티 라이브러리
|
|
3. 로컬 애플리케이션/라이브러리 순으로 그룹화하고, 각 그룹 사이에는 한 줄을 띄웁니다.
|
|
- 예시:
|
|
```python
|
|
import asyncio
|
|
import json
|
|
from pathlib import Path
|
|
|
|
from fastapi import FastAPI
|
|
import torch
|
|
|
|
from .integrated_translation_system import IntegratedTranslationSystem
|
|
```
|
|
- **Docstrings**: 모든 모듈, 함수, 클래스, 메서드에 대해 Google Python 스타일 가이드를 따르는 독스트링을 작성합니다.
|
|
- **오류 처리**: `try...except` 블록을 사용하여 예상되는 오류를 명시적으로 처리하고, 오류 발생 시 로그를 남기거나 적절한 예외를 발생시킵니다.
|
|
|
|
## 4. FastAPI 관련 규칙
|
|
|
|
- **엔드포인트**:
|
|
- URL 경로는 소문자와 하이픈(`-`)을 사용합니다. (예: `/system-status`)
|
|
- 응답 모델을 사용하여 API의 입출력 형식을 명확히 정의합니다.
|
|
- **비동기 처리**: I/O 바운드 작업(파일 읽기/쓰기, 네트워크 요청 등)에는 `async`와 `await`를 적극적으로 사용하여 비동기 처리를 구현합니다.
|
|
- **백그라운드 작업**: 시간이 오래 걸리는 작업(모델 로딩, 번역 등)은 `BackgroundTasks`를 사용하여 사용자 경험을 저해하지 않도록 합니다.
|
|
|
|
## 5. 프로젝트 구조
|
|
|
|
- `config/`: 설정 파일 (예: `settings.json`)
|
|
- `data/`: 원본 데이터 및 학습 데이터
|
|
- `models/`: 학습된 AI 모델 파일
|
|
- `src/`: 핵심 소스 코드
|
|
- `tests/`: 테스트 코드
|
|
- `static/`, `templates/`: FastAPI 웹 인터페이스 파일
|
|
|
|
## 6. 네트워크 설정
|
|
|
|
- **Mac Mini IP**: `192.168.1.122` (AI 번역 서버 호스트)
|
|
- **DS1525+ NAS IP**: `192.168.1.227` (문서 저장소)
|
|
- **NAS 마운트 포인트**: `/Volumes/DS1525+`
|
|
- **서버 포트**: `8080` (FastAPI 웹 서비스)
|
|
- **대시보드 접속**: `http://192.168.1.122:8080/dashboard`
|
|
|
|
### 6.1. API 키 인증
|
|
|
|
관리자용 API(`/api/restart-models`, `/api/clear-cache` 등)를 호출하려면 HTTP 요청 헤더에 API 키를 포함해야 합니다.
|
|
|
|
- **헤더 이름**: `X-API-KEY`
|
|
- **API 키 값**: `config/settings.json` 파일의 `security.api_key` 값을 사용합니다.
|
|
|
|
**cURL 예시:**
|
|
|
|
```bash
|
|
curl -X POST http://192.168.1.122:20080/api/restart-models \
|
|
-H "X-API-KEY: nllb-secret-key-!@#$%"
|
|
```
|
|
|
|
## 7. 서버 운영 및 배포 (macOS)
|
|
|
|
이 서버는 24/7 무중단 운영을 위해 macOS의 `launchd` 서비스를 통해 관리됩니다. 이를 통해 시스템 재부팅 시 자동 시작 및 예기치 않은 종료 시 자동 재시작이 보장됩니다.
|
|
|
|
- **서비스 설정 파일**: `~/Library/LaunchAgents/com.nllb-translation-system.app.plist`
|
|
- 이 파일은 서비스의 실행 방법, 로그 경로, 자동 재시작 여부 등을 정의합니다.
|
|
|
|
- **서비스 제어 명령어**:
|
|
- **시작**: `launchctl start com.nllb-translation-system.app`
|
|
- **중지**: `launchctl stop com.nllb-translation-system.app`
|
|
- **재시작 (설정 파일 수정 후)**:
|
|
1. `launchctl unload ~/Library/LaunchAgents/com.nllb-translation-system.app.plist`
|
|
2. `launchctl load ~/Library/LaunchAgents/com.nllb-translation-system.app.plist`
|
|
|
|
- **로그 확인**:
|
|
- **일반 로그**: `tail -f logs/service.log`
|
|
- **에러 로그**: `tail -f logs/service_error.log`
|
|
|
|
- **주의**: 개발 및 디버깅 시에는 `launchd` 서비스를 중지(`launchctl stop ...`)한 후, 터미널에서 직접 `python src/fastapi_with_dashboard.py`를 실행해야 포트 충돌이 발생하지 않습니다. |