ANIS TRANS

1. 설치

항목	내용
Python	3.9 이상 (3.10~3.12 권장). Windows는 python.org 설치 때 "Add python.exe to PATH"를 켜 주세요. 독립 실행판은 필요 없습니다.
디스크	설치 후 약 0.6GB (GPU용 cuBLAS를 받으면 +1.1GB)
메모리	CPU 실행 시 약 1GB
GPU (선택)	NVIDIA GPU + 드라이버. CUDA 12 툴킷이 없으면 설치 때 --gpu 옵션을 씁니다.

Python 설치판 (Windows · macOS · Linux)

압축을 푼 폴더에서 설치 스크립트를 실행합니다. 폴더 안에 .venv 가상환경을 만들고 필요한 패키지(ctranslate2, sentencepiece)를 받습니다. 시스템 Python은 건드리지 않습니다.

# Linux / macOS
cd anis-trans-0.1
./install.sh
./install.sh --gpu      # NVIDIA GPU를 쓰는데 CUDA 12 툴킷이 없을 때

# Windows: install.cmd 를 두 번 클릭하거나
cd anis-trans-0.1
install.cmd
install.cmd --gpu

Linux 독립 실행판

tar -xzf anis-trans-0.1-linux-x86_64.tar.gz
cd anis-trans-0.1-linux-x86_64
./anis-trans --info

설치가 잘 됐는지는 anis-trans --info로 확인합니다. 아래 예시는 anis-trans로 적었습니다. 압축을 푼 폴더에서 실행할 때 Linux·macOS는 ./anis-trans, Windows PowerShell은 .\anis-trans로 입력하세요.

2. 명령줄(CLI)

# 단문 번역: 방향은 자동 판별 (가나가 있으면 일→한, 한글이 있으면 한→일)
anis-trans "今日は雨が降ってるね。"
anis-trans "오늘 저녁은 뭐 먹을까?"

# 방향 고정
anis-trans -d ja-ko "東京"
anis-trans -d ko-ja "선배, 얼굴색이 안 좋아요."

# 앞뒤 문맥을 함께 주면 말투·지시어를 더 잘 맞춥니다
anis-trans --prev "先輩、顔色悪いですよ。" --next "ああ、少し寝不足なだけだ。" "大丈夫？"

# 파일 일괄 번역: 한 줄 = 한 문장
anis-trans -f script_ja.txt -o out.txt
anis-trans -f script_ja.txt --context-lines 2,1 -o out.txt   # 앞 2줄·뒤 1줄을 문맥으로
anis-trans -f script_ja.txt --with-source                    # 원문<TAB>번역

# 인자 없이 실행하면 대화형 모드
anis-trans

옵션	설명	기본값
-d, --direction	auto, ja-ko, ko-ja	auto
--prev, --next	앞·뒤 문맥 문장 (여러 번 지정 가능)	없음
--context-lines 앞,뒤	파일 번역 때 이웃한 줄을 문맥으로 넣음	0,0
--line-type	대사, 독백, 나레이션, 선택지, 시스템	대사
-f, -o	입력 파일(.txt, .jsonl), 출력 파일	표준입출력
--device	auto, cpu, cuda	auto
--threads	CPU 스레드 수 (0이면 자동)	0

3. 브라우저 화면(GUI)

anis-trans-gui          # Windows: anis-trans-gui.cmd 두 번 클릭
anis-trans --gui        # 같은 동작

실행하면 기본 브라우저에 http://127.0.0.1:7870/이 열립니다. macOS는 ANIS Trans GUI.command를 두 번 클릭해도 됩니다.

• 문장 번역: 방향(자동·일→한·한→일), 줄 종류, 앞뒤 문맥을 정해 번역합니다. 단축키는 Ctrl+Enter(맥은 ⌘+Enter)입니다.
• 일괄 번역: .txt/.jsonl 파일을 번역하고 결과를 .txt·.jsonl·원문+번역 .tsv로 받습니다.
• 장치: 오른쪽 위에서 자동·CPU·GPU를 고릅니다. 입력한 문장은 컴퓨터 밖으로 나가지 않습니다.

4. 로컬 API 서버 (Ollama · OpenAI 호환)

Ollama나 OpenAI API를 쓰는 번역 도구·스크립트에서 주소와 모델 이름만 바꾸면 됩니다. 기본 주소는 http://127.0.0.1:11435입니다.

anis-trans-server                    # Windows: anis-trans-server.cmd
anis-trans-server --device cuda      # GPU로 실행

# Ollama 형식
curl http://127.0.0.1:11435/api/generate -d '{"model":"anis-trans:ja-ko","prompt":"今日は雨が降ってるね。","stream":false}'

# OpenAI 형식
curl http://127.0.0.1:11435/v1/chat/completions -H "Content-Type: application/json" \
  -d '{"model":"anis-trans:ko-ja","messages":[{"role":"user","content":"오늘 저녁은 뭐 먹을까?"}]}'

모델 이름	방향
anis-trans	문장마다 자동 판별
anis-trans:ja-ko	일본어 → 한국어
anis-trans:ko-ja	한국어 → 일본어

• 엔드포인트: Ollama /api/generate, /api/chat, /api/tags · OpenAI /v1/chat/completions, /v1/completions, /v1/models
• 채팅 형식은 마지막 user 메시지를 번역하고, 그 앞의 user 메시지(최근 3개)를 앞 문맥으로 씁니다.
• 요청 본문의 anis 객체(Ollama는 options 안도 가능)로 prev, next, direction, line_type을 직접 넣을 수 있습니다.
• 모델 이름을 바꿀 수 없는 도구에는 --accept-any-model을 쓰세요. 다른 기기에서 접속하게 열 때(--host 0.0.0.0)는 --api-key를 함께 쓰세요.

5. CPU / GPU

• --device auto(기본): NVIDIA GPU가 있으면 GPU(float16), 없으면 CPU(int8)로 실행합니다.
• CUDA 12 툴킷이 없는 PC는 install.sh --gpu / install.cmd --gpu로 cuBLAS를 받으면 GPU를 씁니다.
• macOS·AMD GPU·Intel GPU는 CPU로 실행합니다.

6. 입력할 때 알아 둘 것

• 한 문장 안의 줄바꿈은 <br>로 바꿔 넣고, 번역문에서 다시 줄바꿈으로 돌립니다.
• <v1> 같은 게임 변수는 대체로 그대로 남지만, 한 문장에 여러 개면 빠지거나 바뀔 수 있으니 확인하세요.
• 문맥을 합쳐 1,024토큰까지 넣을 수 있습니다. 넘치면 가장 먼 문맥부터 뺍니다.

7. 문제 해결

증상	해결
Windows에서 파이프 결과가 깨짐	명령 프롬프트에서 chcp 65001. 파일 번역(-f, -o)은 영향이 없습니다.
GPU 실행 실패 … libcublas	CUDA 12 툴킷을 설치하거나 --gpu 옵션으로 다시 설치하세요. 당장은 --device cpu로 쓸 수 있습니다.
API 서버가 열리지 않음	포트를 다른 프로그램(예: Ollama)이 쓰고 있습니다. --port로 바꾸세요.
macOS "확인되지 않은 개발자"	폴더에서 xattr -dr com.apple.quarantine .을 실행하거나 오른쪽 클릭 → 열기를 고르세요.
GUI가 열리지 않음	터미널에 표시된 주소(http://127.0.0.1:포트/)를 브라우저에 직접 입력하세요.

더 자세한 옵션은 압축 파일 안의 README.md에 있습니다. 실행 프로그램 소스는 GitHub, 모델 파일은 Hugging Face에도 있습니다.

8. 출처 표시

번역 출처 표기는 자유지만, 가급적 다음과 같이 표시해 주시면 큰 응원이 됩니다.

이 번역에는 ANIS Trans 0.1 (https://krmod.anis.co.kr)이 사용되었습니다.