PyTorch로 브라질 입법 언어 모델 구축 및 실행

LLM Legislativo Brasileiro란 무엇인가?

LLM Legislativo Brasileiro는 브라질 입법 문서에 특화된 인과 언어 모델을 구축하기 위한 엔드투엔드 연구 및 엔지니어링 프로젝트입니다. 브라질 하원과 연방 상원의 공식 자료를 감사 가능한 오픈 데이터셋으로 구성한 다음, PyTorch로 Transformer 디코더를 처음부터 학습합니다.

이 프로젝트는 사전 학습된 가중치, 폐쇄형 API 또는 Hugging Face Trainer와 같은 고수준 학습 추상화를 사용하지 않습니다. 설계의 핵심은 오픈 사이언스, 재현성, SHA-256 무결성 검사, 그리고 학습·검증·테스트 데이터 간의 엄격한 인과적 격리입니다.

이 모델은 연구 및 교육용 결과물입니다. 인과 언어 모델은 법률, 개정안, 요약 및 법률 조항을 환각할 수 있으므로 사실에 기반한 법률 자문이나 규범적 의사결정을 위한 도구로 취급해서는 안 됩니다.

주요 기능

• 하원과 상원 자료를 포함한 360GiB 이상의 공식 원시 데이터
• 법안, 헌법 개정안, 보고서, 의견서, 대체안, 최종안 및 회의 기록 등 930,000개 이상의 문서와 실질적 버전
• Hugging Face Hub에서 공개된 5개의 데이터셋 릴리스. 원시 아카이브, 추출 텍스트 및 선별된 Apache Parquet 데이터를 포함합니다.
• 학습 분할만 사용해 학습한 8,192토큰 바이트 수준 BPE 토크나이저
• PyTorch로 구현한 명시적 인과 Transformer 디코더. 6개 레이어, 6개 어텐션 헤드, 384차원 은닉 표현 및 512토큰 컨텍스트 윈도우로 구성됩니다.
• 토큰 임베딩 레이어와 출력 프로젝션 레이어 간 가중치 공유
• 전체 유효 타깃 수에 기반한 정확한 그래디언트 누적. 서로 다른 시퀀스 간 패딩으로 인한 가중치 오류를 방지합니다.
• 입법 계열 식별자를 기반으로 한 결정론적 80/10/10 데이터 분할. 관련 문서가 학습과 테스트 경계를 넘지 않도록 합니다.
• safetensors 형식의 공개 모델 가중치와 토크나이저, 구성, 메트릭 및 독립 실행형 추론 코드

데이터 및 학습 파이프라인 이해하기

저장소는 프로젝트를 전문화된 단계로 나눕니다. 공식 하원 및 상원 목록은 복원력 있고 멱등적인 프로세스를 통해 수집 및 다운로드됩니다. 원시 파일은 Git 외부에 보관하고, 경량 메타데이터, 스키마 및 구성 파일은 버전 관리합니다.

macOS에서는 네이티브 Swift 추출 어댑터가 텍스트가 포함된 문서에 PDFKit을 사용합니다. 스캔된 페이지나 텍스트 밀도가 충분하지 않은 페이지는 Apple Vision OCR로 전달됩니다. 그런 다음 igraph로 구축한 전역 입법 계열 그래프와 정확한 SHA-256 중복 제거, 구절 포함 탐지를 사용해 R에서 결과 텍스트를 선별합니다.

동일한 입법 절차와 연결된 각 법안, 개정안, 보고서, 의견서 및 대체안에는 동일한 family_id가 부여됩니다. 해당 식별자의 결정론적 해시가 전체 계열을 학습, 검증 또는 테스트 중 하나에 할당합니다. 이를 통해 관련 버전이 평가 분할 사이에 유출되는 것을 방지합니다.

분할이 완료되면 Python 토큰화 단계에서 학습 데이터만 사용해 8,192토큰의 바이트 수준 BPE 어휘를 학습합니다. 포르투갈어 악센트, §, º, ª, Art.와 같은 입법 기호, 숫자 및 기타 특수 문자를 지원합니다. 토큰화된 데이터는 512토큰 윈도우용 인덱스와 함께 바이너리 샤드에 기록됩니다.

저장소 설정

1. 프로젝트 복제

이 저장소에는 Python 3.9 이상이 필요합니다. 저장소를 복제하고 프로젝트 디렉터리로 이동합니다.

git clone https://github.com/BaruqueRodrigues/llm-legislativo.git
cd llm-legislativo

2. 가상 환경 생성

가상 환경을 사용하면 프로젝트 종속성을 시스템의 다른 부분과 격리할 수 있습니다.

python3 -m venv .venv
source .venv/bin/activate

3. 패키지 설치

로컬 소스 변경 사항을 즉시 사용할 수 있도록 저장소를 편집 가능 모드로 설치합니다.

pip install -e .

이 저장소에는 src/legislm/ 아래의 Python 패키지, 기본 및 CPU 환경용 잠금 파일, R 재현성 메타데이터, 선언적 구성 파일, 노트북, 명령줄 스크립트 및 테스트 모음이 포함되어 있습니다.

설치 검증

모델 추론이나 대규모 학습을 시도하기 전에 CPU에서 자동화된 테스트를 로컬로 실행합니다.

pytest tests/ -q

README에는 모델 동작, 지속성, 토큰화 및 평가를 다루는 135개 이상의 단위 및 계약 테스트가 설명되어 있습니다. 테스트가 성공적으로 실행되면 수백 GiB 규모의 전체 코퍼스나 A100 GPU 없이도 핵심 인터페이스가 작동하는지 확인할 수 있습니다.

릴리스된 모델 불러오기

학습된 모델은 BaruqRodrigues/llm-legislativo 저장소에서 사용할 수 있습니다. 다음 예제는 가중치와 토크나이저를 다운로드하고, 아키텍처를 재구성한 뒤 safetensors 상태 사전을 불러옵니다.

import torch
from huggingface_hub import hf_hub_download
from safetensors.torch import load_file
from legislm.model.gpt import GPTModel
from legislm.model.config import ModelConfig
from tokenizers import Tokenizer

# 모델 아티팩트 다운로드
weights_path = hf_hub_download(
    repo_id="BaruqRodrigues/llm-legislativo",
    filename="model.safetensors"
)
tokenizer_path = hf_hub_download(
    repo_id="BaruqRodrigues/llm-legislativo",
    filename="tokenizer.json"
)

# 토크나이저와 모델 구성 재생성
tokenizer = Tokenizer.from_file(tokenizer_path)
config = ModelConfig(
    vocab_size=8192,
    context_length=512,
    d_model=384,
    n_layers=6,
    n_heads=6,
    tie_embeddings=True
)
model = GPTModel(config)

# 학습된 파라미터 로드
state_dict = load_file(weights_path)
model.load_state_dict(state_dict)
model.eval()

입법 텍스트 생성

모델이 로드되면 포르투갈어 입법 프롬프트를 인코딩하고 모델의 생성 메서드를 호출합니다. 이 예제에서는 짧은 법안 도입부를 사용하고 최대 64개의 새 토큰을 요청합니다.

prompt = "PROJETO DE LEI Nº , DE 2026\n\nDispõe sobre"
input_ids = torch.tensor(
    [tokenizer.encode(prompt).ids],
    dtype=torch.long
)

with torch.no_grad():
    output_ids = model.generate(
        input_ids,
        max_new_tokens=64,
        temperature=0.7,
        top_k=40,
        eos_token_id=2
    )

print(tokenizer.decode(output_ids[0].tolist()))

이 모델의 최대 컨텍스트 길이는 512토큰입니다. 이 예제에서 temperature=0.7은 샘플링 변동성을 제어하고, top_k=40은 샘플링 대상을 확률이 가장 높은 40개 후보로 제한합니다. 실험할 때 이 값을 조정할 수 있지만, 생성된 텍스트는 검증된 법률 콘텐츠가 아니라 통계적 출력이라는 점을 기억해야 합니다.

공개 데이터셋 살펴보기

이 프로젝트는 Hugging Face Hub에 말뭉치의 여러 처리 단계를 공개합니다.

• corpus-legislativo-pretraining: 가족별로 구성된 학습, 검증, 테스트 분할을 포함하는 Parquet 형식의 통합 큐레이션 릴리스입니다.
• camara-corpus-raw: 브라질 하원 원시 TAR 아카이브와 SHA-256 매니페스트입니다.
• camara-corpus-text: 품질 검증이 적용된 브라질 하원 텍스트 구조화 추출본입니다.
• senado-corpus-raw: 브라질 연방상원의 인벤토리와 기본 데이터입니다.
• senado-corpus-text: 열 지향 Parquet 형식으로 제공되는 큐레이션된 상원 문서와 페이지입니다.

이 릴리스들을 통해 원본 아카이브와 추출된 텍스트부터 최종 학습 행렬에 이르기까지 파이프라인의 여러 단계에서 프로젝트를 검토할 수 있습니다.

학습 재현 또는 확장

학습 구현은 src/legislm/training/에 있으며, 토큰화와 샤드 생성은 src/legislm/tokenization/에 있습니다. 구성은 configs/에 저장되어 있고, Google Colab 워크플로는 notebooks/와 src/legislm/colab/에 제공됩니다.

공개된 학습 실행은 NVIDIA A100-SXM4-40GB 환경에서 수행되었으며 약 20시간 동안 173,209회의 최적화 업데이트를 완료했습니다. AdamW, 2,000단계 선형 워밍업을 적용한 코사인 스케줄러, 혼합 FP16 정밀도, Google Drive를 통한 체크포인트 저장을 사용하여 약 12억 5천만 개의 토큰을 처리했습니다.

재현 가능한 실험을 위해 토크나이저를 학습 분할로 제한하고, 결정론적인 가족 기반 분할 절차를 유지하며, 저장소의 SHA-256 매니페스트와 체크포인트 메타데이터를 보존해야 합니다. 이러한 세부 사항은 데이터 누수를 방지하고 결과를 공정하게 비교하는 데 필수적입니다.

결과를 올바르게 평가

이 프로젝트는 71,069개의 문서와 약 4억 8,200만 바이트로 구성된 독립 테스트 분할에서 표준화된 byte_nll_v1 평가 프로토콜을 정의합니다. 보고된 결과에는 유효한 타깃당 평균 손실 2.1065, 토큰 퍼플렉시티 8.2197, 단어 퍼플렉시티 65.6509가 포함됩니다.

정규화된 바이트 수준 결과는 바이트당 0.7297나트, 즉 바이트당 1.0528비트입니다. 보고된 값은 하원 컬렉션에서 바이트당 0.7049나트, 상원 컬렉션에서 0.8817나트입니다. 향후 실험을 비교할 때는 토큰 퍼플렉시티에만 의존하지 말고 동일한 분할 로직과 평가 정의를 사용해야 합니다.

저장소 구조

주요 디렉터리를 확인하면 시스템을 수정하거나 연구할 때 살펴볼 위치를 파악할 수 있습니다.

• R/: 공식 데이터 인벤토리, 다운로드, 추출 통합 및 큐레이션입니다.
• src/legislm/: 토크나이저, 모델, 학습, Colab 저장 및 평가 코드입니다.
• schemas/: Arrow 및 JSON Schema 데이터 계약입니다.
• configs/: 데이터, 큐레이션, 학습 및 Colab 구성입니다.
• notebooks/: 파일럿 및 전체 Google Colab 워크플로입니다.
• scripts/: 실행 가능한 명령줄 진입점입니다.
• tests/: 단위 테스트 및 계약 테스트입니다.
• docs/: 규범적 문서, 계약 및 보고서입니다.

고급 실전 팁

• 테스트부터 시작하세요: CPU 검증은 대용량 데이터 세트를 다운로드하거나 GPU 리소스를 요청하기 전에 설치를 확인할 수 있는 비용이 적은 방법입니다.
• 분류 경계를 유지하세요: 프로젝트와 비교 가능한 결과를 원한다면 문서 단위의 무작위 분할을 절대 사용하지 마세요. 하나의 입법 과정에서 나온 버전들은 서로 밀접하게 연관될 수 있기 때문입니다.
• 분할 후 토크나이저를 학습하세요: 검증 데이터나 테스트 데이터로 어휘 통계를 산출하면 프로젝트의 데이터 누수 방지 제어가 훼손됩니다.
• 유효한 타깃을 추적하세요: 패딩된 시퀀스를 사용할 때는 마이크로 배치 전체의 유효한 타깃 수를 기준으로 크로스 엔트로피를 누적하세요.
• 아티팩트는 Git 외부에 보관하세요: 이 저장소는 원시 바이너리, 모델 가중치, 캐시가 아니라 메타데이터와 스키마를 의도적으로 버전 관리합니다.
• 검토에는 공개 릴리스를 사용하세요: 원시 데이터 세트, 추출 데이터 세트, 정제된 Hub 데이터 세트를 사용하면 전체 수집 과정을 다시 만들지 않고도 파이프라인의 개별 단계를 조사할 수 있습니다.
• 생성 결과는 신중하게 해석하세요: 생성된 입법 문구는 그럴듯해 보이더라도 허위 인용이나 조항을 포함할 수 있습니다.

결론

LLM Legislativo Brasileiro는 공식 입법 기록 보관소에서 전문 인과 언어 모델에 이르는 완전하고 감사 가능한 경로를 보여 줍니다. 패키지를 설치하고 테스트를 실행한 후에는 공개된 토크나이저와 PyTorch 모델을 불러와 텍스트를 생성하고, 공개 데이터 세트를 검토하며, 데이터 누수에 강한 저장소의 정제 및 학습 방법을 연구할 수 있습니다. MIT 라이선스로 공개된 코드와 아티팩트는 포르투갈어 입법 언어 모델링 연구를 위한 유용한 기반을 제공합니다.