TL;DR: Bank Statement Parser là thư viện Python mã nguồn mở giúp phân tích bảy định dạng sao kê ngân hàng (CAMT.053, PAIN.001, CSV, OFX, QFX, MT940 và PDF) thành pandas DataFrames. Pipeline PDF hybrid với xác minh số dư, REST API, làm giàu dữ liệu, xuất sổ cái, thông lượng 27K+ tx/s.
Bank Statement Parser là thư viện Python mã nguồn mở giúp phân tích sao kê ngân hàng từ bảy định dạng thành pandas DataFrames có cấu trúc. Phần lõi xác định xử lý các định dạng có cấu trúc cục bộ mà không cần kết nối mạng. Pipeline PDF hybrid tùy chọn chuyển qua LLM cục bộ (qua Ollama) cho các sao kê kỹ thuật số và sao kê quét.
Dành cho ai?
- Nhóm ngân quỹ đang chuyển đổi từ MT940 sang CAMT.053, cần trình phân tích xử lý cả định dạng cũ và mới trong quá trình chuyển đổi, cộng thêm sao kê PDF từ các ngân hàng không cung cấp xuất dữ liệu có cấu trúc.
- Nhà phát triển fintech xây dựng pipeline đối chiếu, báo cáo hoặc kế toán, muốn một phụ thuộc duy nhất với xác minh số dư, phân loại, và xuất sổ cái tích hợp sẵn.
- Nhóm tuân thủ cần ẩn danh PII mặc định, đầu ra xác định, và xác minh Golden Rule phát hiện sai lệch trước khi dữ liệu vào sổ cái.
- Người dùng kế toán plaintext muốn tự động nhập từ sao kê PDF ngân hàng trực tiếp vào sổ nhật ký hledger hoặc beancount.
- Bất kỳ ai từ chối gửi dữ liệu tài chính nhạy cảm đến SaaS bên thứ ba khi một công cụ mã nguồn mở cục bộ có thể thực hiện công việc đó.
Định dạng hỗ trợ
| Định dạng | Tiêu chuẩn | Loại tệp | Parser/Phương thức |
|---|---|---|---|
| CAMT.053 | ISO 20022 Sao kê ngân hàng gửi khách hàng | .xml |
CamtParser |
| PAIN.001 | ISO 20022 Khởi tạo chuyển khoản | .xml |
Pain001Parser |
| CSV | Xuất dữ liệu ngân hàng tổng hợp | .csv |
CsvStatementParser |
| OFX | Open Financial Exchange | .ofx |
OfxParser |
| QFX | Quicken Financial Exchange | .qfx |
QfxParser |
| MT940 | Tiêu chuẩn SWIFT | .mt940, .sta |
Mt940Parser |
| Sao kê kỹ thuật số và sao kê quét | .pdf |
smart_ingest() |
Tất cả định dạng đều tạo ra pandas DataFrames chuẩn hóa với tên cột nhất quán, giúp xử lý downstream không phụ thuộc vào định dạng.
Khả năng chính
- Pipeline PDF Hybrid:
smart_ingest()chuyển PDF qua ba đường dẫn — trích xuất bảng xác định, text-LLM, hoặc vision-LLM — với tự động xác minh số dư Golden Rule. - Tự động nhận dạng định dạng:
detect_statement_format()nhận dạng định dạng;create_parser()khởi tạo trình phân tích phù hợp. - Xác minh số dư: Kiểm tra Golden Rule (
opening + credits − debits == closing) với trạng thái VERIFIED/DISCREPANCY/FAILED. - Xác minh đa tiền tệ:
verify_balance_multi_currency()nhóm giao dịch theo tiền tệ để xác minh độc lập. - REST API: Microservice FastAPI với các endpoint
/ingestvà/healthcho triển khai production. - Làm giàu dữ liệu: Phân loại giao dịch bằng LLM với schema tùy chỉnh (mặc định 13 danh mục Plaid).
- Xem xét tương tác: Duyệt qua các sai lệch với hành động accept/edit/skip/delete qua
--type review. - Xuất sổ cái:
to_hledger()vàto_beancount()cho quy trình kế toán plaintext. - Quét hàng loạt:
scan_and_ingest()xử lý cây thư mục với tự động chống trùng lặp liên tệp. - Ánh xạ tài khoản: Quy tắc ánh xạ tài khoản dựa trên regex từ cấu hình JSON cho xuất sổ cái.
- Phân tích streaming: Xử lý tệp lớn (50 MB+, 50K+ giao dịch) với bộ nhớ giới hạn bằng
parse_streaming(). - Xử lý song song: Phân tích nhiều tệp đồng thời với
parse_files_parallel()sử dụng ProcessPoolExecutor. - Chống trùng lặp:
transaction_hashidempotent (dấu vân tay MD5) cho nhập dữ liệu gia tăng an toàn. - Phân tích trong bộ nhớ:
from_string()vàfrom_bytes()cho quy trình SFTP và API không cần I/O đĩa. - Xử lý ZIP an toàn:
iter_secure_xml_entries()với giới hạn tỷ lệ nén, giới hạn kích thước mục nhập, và từ chối mục nhập mã hóa. - Xuất dữ liệu: CSV, JSON, Excel (
.xlsx), Polars DataFrames, hledger, và beancount journals.
Bảo mật và quyền riêng tư
- Ẩn danh PII: Tên, IBAN và địa chỉ được che mặc định trong đầu ra CLI. Bật hiển thị với
--show-pii. - Bảo vệ XXE: Phân tích XML sử dụng
resolve_entities=False,no_network=True,load_dtd=False. - Bảo vệ ZIP Bomb: Giới hạn tỷ lệ nén (mặc định 100:1), giới hạn kích thước mục nhập (10 MB), từ chối mục nhập mã hóa.
- Ngăn chặn Path Traversal: Danh sách chặn mẫu nguy hiểm và phân giải symlink.
- Bảo mật chuỗi cung ứng: Phụ thuộc khóa hash SHA-256, CycloneDX SBOM, chứng thực nguồn gốc bản dựng.
- Chỉ LLM cục bộ: Pipeline PDF hybrid sử dụng Ollama cho suy luận cục bộ — không gửi dữ liệu đến cloud API.
Hiệu suất
| Chỉ số | Giá trị |
|---|---|
| Thông lượng CAMT.053 | 27.000+ tx/s |
| Thông lượng PAIN.001 | 52.000+ tx/s |
| Độ trễ mỗi giao dịch (CAMT) | 37 micro giây |
| Độ trễ mỗi giao dịch (PAIN.001) | 19 micro giây |
| Thời gian đến kết quả đầu tiên | < 2 ms |
| Mở rộng bộ nhớ (1K-50K tx) | Không đổi (streaming) |
| Độ phủ kiểm tra | 100% độ phủ nhánh |
| Bài kiểm tra | 718 trên 29 tệp kiểm tra |
Bắt đầu xây dựng
Bắt đầu với hướng dẫn cài đặt và ví dụ ❯
"Kho lưu trữ GitHub"