Xây dựng và chạy mô hình ngôn ngữ lập pháp Brazil bằng PyTorch

LLM Legislativo Brasileiro là gì?

LLM Legislativo Brasileiro là một dự án nghiên cứu và kỹ thuật toàn diện nhằm xây dựng mô hình ngôn ngữ nhân quả chuyên biệt cho các tài liệu lập pháp Brazil. Dự án tổ chức tài liệu chính thức từ Hạ viện và Thượng viện Liên bang thành các bộ dữ liệu mở có thể kiểm toán, sau đó huấn luyện một bộ giải mã Transformer hoàn toàn từ đầu bằng PyTorch.

Dự án không sử dụng trọng số được huấn luyện trước, API đóng hoặc các lớp trừu tượng huấn luyện cấp cao như Hugging Face Trainer. Thiết kế này nhấn mạnh khoa học mở, khả năng tái lập, kiểm tra tính toàn vẹn bằng SHA-256 và sự tách biệt nhân quả nghiêm ngặt giữa dữ liệu huấn luyện, xác thực và kiểm thử.

Mô hình này là một sản phẩm nghiên cứu và giáo dục. Không nên xem đây là công cụ tư vấn pháp lý có tính xác thực hoặc công cụ đưa ra quyết định quy phạm, vì các mô hình ngôn ngữ nhân quả có thể bịa ra luật, sửa đổi, bản tóm tắt và quy định pháp lý.

Tính năng chính

• Hơn 360 GiB dữ liệu thô chính thức, bao gồm các bộ sưu tập của Hạ viện và Thượng viện.
• Hơn 930.000 tài liệu và phiên bản nội dung, chẳng hạn như dự luật, sửa đổi hiến pháp, báo cáo, ý kiến, văn bản thay thế, văn bản cuối cùng và biên bản phiên họp.
• Năm bản phát hành bộ dữ liệu công khai trên Hugging Face Hub, bao phủ các kho lưu trữ thô, văn bản đã trích xuất và dữ liệu Apache Parquet được tuyển chọn.
• Bộ mã hóa BPE cấp byte gồm 8.192 token, được huấn luyện độc quyền trên phần dữ liệu huấn luyện.
• Bộ giải mã Transformer nhân quả rõ ràng được triển khai bằng PyTorch, với sáu lớp, sáu đầu attention, biểu diễn ẩn 384 chiều và cửa sổ ngữ cảnh 512 token.
• Chia sẻ trọng số giữa các lớp nhúng token và chiếu đầu ra.
• Tích lũy gradient chính xác dựa trên tổng số mục tiêu hợp lệ, tránh lỗi gán trọng số do padding giữa các chuỗi không đồng nhất.
• Phân chia dữ liệu xác định 80/10/10 dựa trên mã định danh nhóm lập pháp, ngăn các tài liệu liên quan vượt qua ranh giới giữa dữ liệu huấn luyện và kiểm thử.
• Trọng số mô hình công khai ở định dạng safetensors, đi kèm bộ mã hóa, cấu hình, chỉ số đánh giá và mã suy luận độc lập.

Tìm hiểu dữ liệu và quy trình huấn luyện

Kho mã phân tách dự án thành các giai đoạn chuyên biệt. Danh mục chính thức của Hạ viện và Thượng viện được thu thập và tải xuống thông qua các quy trình bền vững, có thể chạy lặp lại an toàn. Các tệp thô nằm ngoài Git, còn siêu dữ liệu nhẹ, lược đồ và tệp cấu hình được quản lý phiên bản.

Trên macOS, một bộ điều hợp trích xuất Swift gốc sử dụng PDFKit cho các tài liệu có văn bản nhúng. Các trang được quét hoặc có mật độ văn bản không đủ sẽ được chuyển đến Apple Vision OCR. Sau đó, văn bản kết quả được tuyển chọn trong R bằng cách khử trùng lặp SHA-256 chính xác, phát hiện nội dung đoạn văn bao hàm nhau và xây dựng đồ thị nhóm lập pháp toàn cục bằng igraph.

Mỗi đề xuất, sửa đổi, báo cáo, ý kiến và văn bản thay thế liên quan đến cùng một quy trình lập pháp sẽ nhận cùng một family_id. Một hàm băm xác định của mã định danh đó sẽ gán toàn bộ nhóm vào dữ liệu huấn luyện, xác thực hoặc kiểm thử. Điều này ngăn các phiên bản liên quan rò rỉ qua các tập đánh giá.

Sau khi phân vùng, giai đoạn token hóa bằng Python huấn luyện một từ vựng BPE cấp byte gồm 8.192 token chỉ sử dụng dữ liệu huấn luyện. Bộ mã hóa hỗ trợ dấu tiếng Bồ Đào Nha, các ký hiệu lập pháp như §, º, ª và Art., cũng như chữ số và các ký tự đặc biệt khác. Dữ liệu đã token hóa được ghi vào các phân mảnh nhị phân cùng chỉ mục cho các cửa sổ 512 token.

Thiết lập kho mã

1. Sao chép dự án

Kho mã yêu cầu Python 3.9 trở lên. Hãy sao chép kho mã và truy cập thư mục dự án:

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

2. Tạo môi trường ảo

Sử dụng môi trường ảo giúp các phần phụ thuộc của dự án được tách biệt khỏi phần còn lại của hệ thống:

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

3. Cài đặt gói

Cài đặt kho mã ở chế độ editable để các thay đổi đối với mã nguồn cục bộ có hiệu lực ngay lập tức:

pip install -e .

Kho mã bao gồm một gói Python tại src/legislm/, các tệp khóa cho môi trường cơ sở và CPU, siêu dữ liệu tái lập R, cấu hình khai báo, notebook, tập lệnh dòng lệnh và một bộ kiểm thử.

Xác thực cài đặt

Trước khi thử suy luận mô hình hoặc huấn luyện quy mô lớn, hãy chạy các kiểm thử tự động cục bộ trên CPU:

pytest tests/ -q

README ghi nhận hơn 135 kiểm thử đơn vị và kiểm thử hợp đồng, bao phủ hành vi mô hình, khả năng lưu trữ, token hóa và đánh giá. Một lần chạy thành công xác nhận các giao diện cốt lõi hoạt động mà không cần toàn bộ kho dữ liệu hàng trăm gigabyte hoặc GPU A100.

Nạp mô hình đã phát hành

Mô hình đã huấn luyện có sẵn tại kho BaruqRodrigues/llm-legislativo. Ví dụ sau tải xuống trọng số và bộ mã hóa, tái tạo kiến trúc và nạp state dictionary 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

# Download the model artifacts
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"
)

# Recreate the tokenizer and model configuration
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)

# Load the trained parameters
state_dict = load_file(weights_path)
model.load_state_dict(state_dict)
model.eval()

Tạo văn bản lập pháp

Sau khi tải mô hình, hãy mã hóa một lời nhắc lập pháp bằng tiếng Bồ Đào Nha và gọi phương thức tạo văn bản của mô hình. Ví dụ này sử dụng phần mở đầu ngắn của một dự luật và yêu cầu tạo tối đa 64 token mới.

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()))

Mô hình sử dụng độ dài ngữ cảnh tối đa là 512 token. Trong ví dụ này, temperature=0.7 kiểm soát mức độ biến thiên khi lấy mẫu, còn top_k=40 giới hạn việc lấy mẫu ở 40 ứng viên có xác suất cao nhất. Hãy điều chỉnh các giá trị này khi thử nghiệm, đồng thời nhớ rằng văn bản được tạo ra là kết quả thống kê chứ không phải nội dung pháp lý đã được kiểm chứng.

Khám phá các bộ dữ liệu công khai

Dự án công bố nhiều giai đoạn của kho ngữ liệu trên Hugging Face Hub:

• corpus-legislativo-pretraining: bản phát hành hợp nhất đã được tuyển chọn ở định dạng Parquet, gồm các tập huấn luyện, xác thực và kiểm tra được tổ chức theo họ.
• camara-corpus-raw: các kho lưu trữ TAR thô của Hạ viện và tệp kê khai SHA-256.
• camara-corpus-text: các nội dung trích xuất có cấu trúc từ văn bản Hạ viện, kèm xác minh chất lượng.
• senado-corpus-raw: danh mục và dữ liệu chính của Thượng viện Liên bang.
• senado-corpus-text: các tài liệu và trang Thượng viện đã được tuyển chọn ở định dạng Parquet dạng cột.

Các bản phát hành này cho phép kiểm tra dự án ở nhiều thời điểm khác nhau trong quy trình, từ kho lưu trữ nguồn và văn bản đã trích xuất đến các ma trận huấn luyện cuối cùng.

Tái lập hoặc mở rộng quá trình huấn luyện

Phần triển khai huấn luyện nằm trong src/legislm/training/, còn việc token hóa và tạo shard nằm trong src/legislm/tokenization/. Các cấu hình được lưu trong configs/, còn quy trình Google Colab được cung cấp trong notebooks/ và src/legislm/colab/.

Lần chạy huấn luyện được công bố sử dụng môi trường NVIDIA A100-SXM4-40GB và hoàn tất 173,209 lần cập nhật tối ưu trong khoảng 20 giờ. Quá trình này xử lý khoảng 1.25 tỷ token bằng AdamW, bộ lập lịch cosine với giai đoạn khởi động tuyến tính 2,000 bước, độ chính xác hỗn hợp FP16 và cơ chế lưu checkpoint thông qua Google Drive.

Để thực hiện các thí nghiệm có thể tái lập, hãy giới hạn tokenizer trong tập huấn luyện, giữ nguyên quy trình phân chia xác định theo họ, đồng thời bảo toàn các tệp kê khai SHA-256 và siêu dữ liệu checkpoint của kho mã. Những chi tiết này rất cần thiết để tránh rò rỉ dữ liệu và so sánh kết quả một cách công bằng.

Đánh giá kết quả chính xác

Dự án định nghĩa một giao thức đánh giá byte_nll_v1 được chuẩn hóa trên một tập kiểm tra độc lập gồm 71,069 tài liệu và khoảng 482 triệu byte. Các kết quả được báo cáo gồm loss trung bình 2.1065 cho mỗi mục tiêu hợp lệ, perplexity token 8.2197 và perplexity từ 65.6509.

Kết quả cấp byte đã chuẩn hóa là 0.7297 nat trên mỗi byte, tương đương 1.0528 bit trên mỗi byte. Các giá trị được báo cáo là 0.7049 nat trên mỗi byte đối với tập dữ liệu Hạ viện và 0.8817 đối với tập dữ liệu Thượng viện. Khi so sánh các thí nghiệm trong tương lai, hãy sử dụng cùng logic phân chia và định nghĩa đánh giá thay vì chỉ dựa vào perplexity token.

Bố cục kho mã

Các thư mục chính cho biết nơi cần tìm khi sửa đổi hoặc nghiên cứu hệ thống:

• R/: kiểm kê dữ liệu chính thức, tải xuống, tích hợp trích xuất và tuyển chọn.
• src/legislm/: mã tokenizer, mô hình, huấn luyện, lưu trữ Colab và đánh giá.
• schemas/: các hợp đồng dữ liệu Arrow và JSON Schema.
• configs/: cấu hình dữ liệu, tuyển chọn, huấn luyện và Colab.
• notebooks/: quy trình Google Colab thử nghiệm và đầy đủ.
• scripts/: các điểm vào dòng lệnh có thể thực thi.
• tests/: các bài kiểm thử đơn vị và kiểm thử hợp đồng.
• docs/: tài liệu quy chuẩn, hợp đồng và báo cáo.

Mẹo thực tiễn nâng cao

• Bắt đầu với các bài kiểm thử: Việc xác thực trên CPU là cách ít tốn kém để xác nhận cài đặt trước khi tải xuống các tập dữ liệu lớn hoặc yêu cầu tài nguyên GPU.
• Duy trì ranh giới giữa các nhóm: không bao giờ tạo các phân chia ngẫu nhiên ở cấp tài liệu nếu bạn muốn kết quả có thể so sánh với dự án, vì các phiên bản từ cùng một quy trình lập pháp có thể liên quan chặt chẽ với nhau.
• Huấn luyện bộ mã hóa token sau khi phân chia: việc tính toán thống kê từ vựng trên dữ liệu xác thực hoặc kiểm thử sẽ làm ảnh hưởng đến các biện pháp kiểm soát rò rỉ dữ liệu của dự án.
• Theo dõi các đích hợp lệ: khi sử dụng các chuỗi được đệm, hãy cộng dồn entropy chéo theo tổng số đích hợp lệ qua các lô vi mô.
• Giữ các tệp tạo tác bên ngoài Git: kho mã cố ý quản lý phiên bản cho siêu dữ liệu và lược đồ thay vì các tệp nhị phân thô, trọng số mô hình và bộ nhớ đệm.
• Sử dụng các bản phát hành công khai để kiểm tra: các tập dữ liệu thô, đã trích xuất và được tuyển chọn trên Hub cho phép bạn khảo sát từng giai đoạn của quy trình mà không cần tái tạo toàn bộ quá trình thu thập.
• Diễn giải nội dung sinh một cách thận trọng: ngôn ngữ lập pháp được sinh có thể trông hợp lý nhưng vẫn chứa các tham chiếu hoặc điều khoản bịa đặt.

Kết luận

LLM Legislativo Brasileiro trình bày một quy trình hoàn chỉnh, có thể kiểm toán, từ các kho lưu trữ lập pháp chính thức đến một mô hình ngôn ngữ nhân quả chuyên biệt. Sau khi cài đặt gói và chạy các bài kiểm thử, bạn có thể tải bộ mã hóa token và mô hình PyTorch đã phát hành, sinh văn bản, kiểm tra các tập dữ liệu công khai, đồng thời nghiên cứu phương pháp tuyển chọn và huấn luyện chống rò rỉ dữ liệu của kho mã. Mã nguồn được cấp phép MIT cùng các tệp tạo tác được công bố công khai cung cấp nền tảng hữu ích cho nghiên cứu về mô hình hóa ngôn ngữ lập pháp tiếng Bồ Đào Nha.