AI 튜토리얼

중국어 AI 텍스트 탐지기 튜토리얼: 로컬 추론, 모델 학습 및 결과 검증

이 튜토리얼에서는 Chinese Guba AI Detector 설치, 로컬 모델 구성, CSV 텍스트 일괄 탐지, 출력 필드 이해, 합법적인 데이터 사용 허가 취득 후 모델 학습 및 검증 방법을 소개합니다.

2026년 9월 18일약 12분 소요

프로젝트 소개

Chinese Guba AI Detector는 중국어 AI 텍스트 이진 분류 도구입니다. 이 프로젝트는 hfl/chinese-roberta-wwm-ext를 기반으로 하며 C-ReD 말뭉치를 사용해 미세 조정되었고, 과거 구바 텍스트의 연구 목적 측정에 사용되었습니다. 현재 저장소에는 학습, 추론, 테스트 스크립트와 관련 설명 문서가 공개되어 있습니다.

이 도구는 로컬에서 모델을 로드하며 외부 API를 호출하지 않습니다. 특히 현재 저장소에는 학습 완료 가중치와 토크나이저 파일이 제공되지 않으므로, 사용자가 직접 합법적으로 모델을 확보하여 지정된 디렉터리에 넣어야 합니다.

중요한 제한: 이 모델은 C-ReD 공식 모델이 아니며, 이번 미세 조정에는 구바 게시물이 사용되지 않았고 금융 포럼 분야의 사람이 수행한 주석 테스트도 거치지 않았습니다. 모델 점수는 텍스트의 실제 작성자 신원을 증명하지 않으며, 개인 신원 판정이나 콘텐츠 처벌의 유일한 근거로 사용해서는 안 됩니다.

주요 기능

UTF-8 CSV의 중국어 텍스트를 AI 텍스트와 사람 작성 텍스트로 이진 분류합니다.
AI 클래스의 softmax 점수와 임계값 기반 분류 결과를 출력합니다.
기본적으로 帖子内容文本을 읽으며, 사용자 지정 텍스트 열과 종목 코드 열도 지원합니다.
股吧代码를 6자리 텍스트로 정규화하고 앞자리 0을 유지합니다.
입력 파일의 다른 열을 보존하며 텍스트 내용을 임의로 변경하지 않습니다.
임시 파일과 원자적 교체를 통해 출력 파일 손상 위험을 줄입니다.
무결성 검사, 덮어쓰기 재계산 및 단일 프로세스 쓰기 보호를 지원합니다.
학습, 단위 테스트 및 공개 콘텐츠 감사 스크립트를 제공합니다.

설치 및 실행 환경

1. Python과 PyTorch 준비

프로젝트 테스트 환경은 Python 3.10입니다. 독립적인 가상 환경을 사용하는 것이 좋습니다. CPU 또는 CUDA 장치에 따라 먼저 PyTorch 공식 안내에 따라 장치에 맞는 PyTorch 2.5.1을 설치하세요.

Windows PowerShell에서 저장소 루트 디렉터리로 이동한 다음 가상 환경을 생성하고 활성화합니다.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

CPU에서도 추론할 수 있지만 CUDA GPU가 일반적으로 더 빠릅니다. 메모리가 부족하면 먼저 --batch-size를 기본값 또는 큰 값에서 8이나 4로 낮추세요.

2. 로컬 모델 준비

합법적으로 확보한 학습 완료 모델을 models/detector에 넣습니다. 해당 디렉터리에는 다음 파일이 있어야 합니다.

model.safetensors
config.json
tokenizer.json
tokenizer_config.json
special_tokens_map.json
vocab.txt

이 가중치와 토크나이저 파일은 공개 저장소에 포함되어 있지 않습니다. 디렉터리가 완전하지 않으면 추론 스크립트가 모델을 정상적으로 로드할 수 없습니다.

첫 번째 탐지 실행

1. 입력 CSV 준비

입력 파일은 UTF-8 CSV여야 합니다. 기본 텍스트 열 이름은 帖子内容文本이고, 기본 종목 코드 열 이름은 股吧代码입니다. 저장소에서 제공하는 예시는 모두 가상의 텍스트이며 실제 사용자, 실제 게시물 또는 사람이 지정한 AI 정답 레이블을 포함하지 않습니다.

2. 일괄 추론 실행

모델 준비가 완료되면 저장소 루트 디렉터리에서 실행합니다.

python scripts/predict.py --model-dir models/detector --input examples/synthetic_posts.csv --output outputs/demo.csv --batch-size 32

이 명령은 models/detector에서 로컬 모델을 로드하고 예시 CSV를 읽은 후 탐지 결과를 outputs/demo.csv에 기록합니다. 전체 탐지 과정에서 외부 API를 호출하지 않습니다.

3. 출력 필드 이해

출력 파일은 원래 열을 유지하고 다음 필드를 추가합니다.

是否AI生成: 반올림하지 않은 모델 점수가 임계값 이상이면 1, 그렇지 않으면 0입니다. 빈 텍스트는 빈 상태로 유지됩니다.
AI生成概率: AI 클래스의 softmax 점수입니다. 이 점수는 확률 보정을 거치지 않았으므로 실제 확률로 바로 간주할 수 없습니다.
AI检测模型: 공개 모델 식별자이며 로컬 모델 경로는 기록하지 않습니다.
AI检测阈值: 기본값은 0.7입니다. 이는 프로젝트 설정값이며 논문에서 최적이라고 인정된 임계값이 아닙니다.
AI检测状态: ok는 탐지가 완료되었음을, empty_text는 입력 텍스트가 비어 있음을 의미합니다.

사용자 지정 CSV 열 사용

텍스트 열 이름이 text이고 종목 코드 열 이름이 id인 경우 다음과 같이 명시할 수 있습니다.

python scripts/predict.py --model-dir models/detector --input input.csv --output outputs/result.csv --text-column text --stock-column id

입력 파일에 종목 코드 열이 없으면 빈 문자열을 전달합니다.

python scripts/predict.py --model-dir models/detector --input input.csv --output outputs/result.csv --text-column text --stock-column ""

종목 코드 열이 있으면 프로그램은 이를 6자리 텍스트로 정규화하고 앞자리 0을 유지합니다. 입력 파일의 다른 열은 텍스트 그대로 보존됩니다.

덮어쓰기, 검증 및 병렬 처리

전체 결과 다시 생성

추론 결과는 먼저 임시 파일에 기록한 후 성공하면 대상 파일을 원자적으로 교체합니다. 동일한 명령을 다시 실행할 때 입력, 모델, 매개변수 및 전체 출력의 검증값이 모두 일치하는 경우에만 기존 결과를 건너뜁니다.

기존 결과를 무시하고 전체 파일을 다시 생성하려면 --overwrite를 추가합니다.

python scripts/predict.py --model-dir models/detector --input examples/synthetic_posts.csv --output outputs/demo.csv --batch-size 32 --overwrite

처리 중단 및 병렬 작업

중단 후 프로그램은 기존 행 수를 근거 없이 이어 쓰지 않고 해당 파일의 처음부터 다시 계산합니다. 동일한 출력 경로에는 한 번에 하나의 프로세스만 쓸 수 있습니다. 병렬 처리하려면 각 프로세스에 서로 다른 입력 파일과 출력 파일을 할당해야 합니다.

길이 제한 및 결과 해석

기본적으로 각 텍스트에는 최대 256개의 토큰을 입력하며 초과한 부분은 잘립니다. 토큰 수는 한자 수와 같지 않으므로 이 제한을 256자로 이해해서는 안 됩니다.

원래 연구에서 일부 구바 본문은 약 203자의 수집된 조각만 포함했으므로, 탐지 대상이 원문 본문의 일부에 불과할 수 있습니다. 결과를 해석할 때는 텍스트 잘림, 분야 차이 및 문맥 누락을 함께 고려해야 합니다.

AI生成概率는 보정되지 않은 softmax 점수이며, 기본 임계값 0.7은 프로젝트 설정일 뿐입니다. 임계값을 변경하면 이진 분류 결과가 달라지지만, README는 어떤 임계값도 논문으로 검증된 최적값이라고 선언하지 않습니다.

C-ReD 데이터로 모델 학습

라이선스 전제

학습 전에 C-ReD 데이터의 합법적인 사용 허가를 직접 확인하고 취득해야 합니다. 상위 저장소에서는 명확한 라이선스를 확인할 수 없으며, 논문을 인용하는 것만으로 데이터 사용 또는 재배포 권한이 부여되지는 않습니다. 이 프로젝트는 C-ReD 데이터를 미러링하지 않으며, 저장소의 MIT 라이선스는 C-ReD 데이터와 그 파생 가중치에 적용되지 않습니다.

학습 의존성 설치

python -m pip install -r requirements-train.txt

학습 시작

합법적으로 확보한 데이터를 data/C-ReD에 넣었다고 가정하면 다음을 실행할 수 있습니다.

python scripts/train.py --data-root data/C-ReD --output-dir models/detector --epochs 3 --batch-size 8 --eval-batch-size 16 --no-fp16

학습 프로그램은 파일 이름에 CReD_가 포함된 CSV를 읽고 그 안의 text 및 label 열을 사용합니다. 원본 데이터 레이블은 0=AI, 1=人工으로 정의되어 있으며, 학습 시 0=人工, 1=AI로 변환됩니다.

학습 프로토콜과 과거 지표는 MODEL_CARD.md에 기록되어 있습니다. 재학습 시 전체 난수 시드로 초기화하지만, 과거 학습에서는 모델 초기화 전에 전역 시드를 명시적으로 설정하지 않았으므로 기존 가중치를 비트 단위로 재현할 수 있다고 보장할 수 없습니다.

테스트 및 배포 감사

모든 단위 테스트를 실행합니다.

python -m unittest discover -s tests -v

단위 테스트는 가상 데이터와 모의 예측을 사용하므로 모델을 다운로드할 필요가 없습니다. 실제 모델의 스모크 테스트는 모델을 로드하여 추론할 수 있음을 보여줄 뿐, 예측 결과가 정확하다는 것을 증명하지는 않습니다.

공개 콘텐츠 감사를 실행합니다.

python scripts/audit_release.py

공개 저장소는 파일 허용 목록과 민감 정보 패턴을 사용해 검사합니다. 구바 원본 CSV, 게시자 ID, 닉네임, IP, 게시물 URL, 논문 패널, 상업 데이터베이스, 캐시, 로그, Notebook 출력, 학습 중간 체크포인트 및 과거 Git 기록은 저장소에 포함되어서는 안 됩니다. 구체적인 비식별화 범위는 PRIVACY.md에서, 배포 절차는 docs/PUBLISHING.md에서 확인할 수 있습니다.

고급 사용 권장 사항

먼저 가상 데이터로 절차를 검증하세요: 환경, 열 이름, 모델 디렉터리 및 출력 경로가 올바른지 확인한 후 자신의 합법적인 데이터를 처리하세요.
메모리가 부족하면 배치 크기를 줄이세요: 먼저 --batch-size 8 또는 --batch-size 4를 시도하세요.
출력 경로를 공유하지 마세요: 병렬 작업은 단일 프로세스 쓰기 제한이 발생하지 않도록 서로 다른 출력 파일을 사용해야 합니다.
실행 매개변수를 저장하세요: 모델, 입력, 매개변수 및 출력 검증값이 결과 재사용에 영향을 주므로 어느 하나라도 변경한 후에는 출력을 다시 확인해야 합니다.
긴 텍스트를 신중하게 해석하세요: 256토큰을 초과하는 내용은 잘리므로 모델이 끝부분을 보지 못할 수 있습니다.
점수를 신원 증명으로 사용하지 마세요: softmax 점수는 보정되지 않았고 프로젝트에는 금융 포럼 분야의 사람이 수행한 주석 검증이 부족합니다.
가중치를 배포하기 전에 라이선스를 확인하세요: 코드와 문서는 MIT 라이선스, 기본 모델은 Apache-2.0을 따르지만 C-ReD 데이터와 파생 가중치는 별도로 허가를 확인해야 합니다.

맺음말

Chinese Guba AI Detector는 CSV 추론, 모델 학습, 단위 테스트 및 배포 감사를 포함하는 로컬 실행형 중국어 AI 텍스트 분류 절차를 제공합니다. 실제로 사용할 때는 먼저 모델 또는 학습 데이터를 합법적으로 확보하고, 출력은 텍스트 작성자 신원을 확정하는 증거가 아니라 연구 목적의 모델 점수로 간주해야 합니다.