Câu hỏi thường gặp

Bảo mật dữ liệu và tuân thủ

Có dữ liệu nào rời khỏi hạ tầng của tôi không?

Không — kể cả khi trích xuất PDF. Bank Statement Parser hoạt động như một thư viện stateless. Toàn bộ quá trình xử lý -- phân tích, ẩn danh PII, trích xuất tệp nén -- diễn ra trong bộ nhớ runtime cục bộ của bạn. Pipeline PDF hybrid sử dụng Ollama cho suy luận LLM cục bộ — không dùng cloud API. Trình phân tích XML được tăng cường với no_network=True, chặn mọi truy cập ra bên ngoài ở cấp parser. Dữ liệu tài chính của bạn không bao giờ rời khỏi môi trường của bạn.

Ẩn danh PII hoạt động như thế nào?

Các trường nhạy cảm được che trước khi chúng đến logic ứng dụng của bạn. Trình phân tích nhận dạng tên người nợ, tên chủ nợ, IBAN và địa chỉ bưu chính, thay thế bằng ***REDACTED*** trong đầu ra console và chế độ streaming.

• Ẩn danh được bật mặc định trong đầu ra CLI và chế độ streaming.
• Xuất tệp (CSV, JSON, Excel) giữ nguyên dữ liệu gốc để xử lý downstream.
• Bật hiển thị dữ liệu đầy đủ với --show-pii trên CLI hoặc redact_pii=False trong API.

Quá trình trích xuất có xác định không?

Có cho các định dạng có cấu trúc -- đầu ra giống byte mỗi lần chạy. Với cùng một tệp đầu vào, các trình phân tích xác định (CAMT, PAIN.001, CSV, OFX, QFX, MT940) luôn tạo ra cùng một kết quả. Không có tính ngẫu nhiên, không suy luận mô hình, không lấy mẫu heuristic.

Với pipeline PDF hybrid, các đường dẫn trích xuất dựa trên LLM có thể tạo ra biến thể nhỏ giữa các lần chạy. Do đó mọi kết quả trích xuất PDF đều được xác minh bằng Golden Rule (opening + credits − debits == closing) và các sai lệch được gắn cờ có thể xem xét tương tác.

CI đảm bảo tính xác định với 718 bài kiểm tra ở 100% độ phủ nhánh, bao gồm fuzzing dựa trên thuộc tính qua Hypothesis.

Dự án tuân theo những tiêu chuẩn tuân thủ nào?

Dự án duy trì tài liệu phù hợp với ISO 13485 với khả năng truy xuất đầy đủ:

• Sổ đăng ký rủi ro được định lượng với điểm mức độ nghiêm trọng/xác suất và đánh giá rủi ro tồn dư.
• Kế hoạch xác minh và xác nhận với 19 bước kiểm soát trong 5 giai đoạn.
• Quy trình kiểm soát thay đổi với đánh giá tác động và giao thức khôi phục.
• Sổ đăng ký SOUP bao gồm tất cả phụ thuộc với mức độ rủi ro và theo dõi EOL.
• Ma trận truy xuất nguồn gốc ánh xạ đầu vào thiết kế đến triển khai và xác minh.

Mỗi bản phát hành bao gồm CycloneDX SBOM, checksum SHA-256, và chứng thực nguồn gốc bản dựng GitHub.

Hiệu suất và khả năng mở rộng

Bank Statement Parser nhanh như thế nào?

Ngưỡng hiệu suất được xác thực trong CI trên mỗi commit:

Tốc độ trích xuất PDF phụ thuộc vào đường dẫn: deterministic (dưới giây), text-LLM (vài giây), vision-LLM (vài giây mỗi trang).

Tệp lớn được xử lý như thế nào?

Streaming với bộ nhớ giới hạn -- đã kiểm tra với 50.000 giao dịch mỗi tệp. Sử dụng parse_streaming() để xử lý tệp XML theo từng phần. Mỗi giao dịch được trả về dạng dictionary; các phần tử được xóa sau khi xử lý để ngăn tăng trưởng bộ nhớ. Bộ nhớ không tăng theo kích thước tệp -- bài kiểm tra 50K giao dịch (25+ MB) sử dụng ít hơn 2 lần bộ nhớ so với bài kiểm tra 10K giao dịch.

Với các tệp vượt quá 50 MB (ví dụ: các lô PAIN.001 host-to-host với 100K+ thanh toán), trình phân tích streaming qua tệp tạm thời với loại bỏ namespace theo chunk -- toàn bộ tài liệu không bao giờ được nạp vào bộ nhớ.

Tệp ZIP được xử lý an toàn như thế nào?

iter_secure_xml_entries() xác nhận từng thành viên trước khi trích xuất:

• Giới hạn kích thước mục nhập (mặc định 10 MB mỗi mục)
• Tổng giới hạn kích thước không nén (mặc định 50 MB)
• Giới hạn tỷ lệ nén (mặc định 100:1) để ngăn ZIP bomb
• Từ chối mục nhập mã hóa

Không có tệp nào được ghi vào đĩa. Các byte XML chuyển trực tiếp đến parser qua from_bytes().

Tôi có thể phân tích song song nhiều tệp không?

Có. Sử dụng parse_files_parallel() phân phối công việc trên ProcessPoolExecutor:

from bankstatementparser import parse_files_parallel

results = parse_files_parallel([
    "statements/jan.xml",
    "statements/feb.xml",
    "statements/mar.xml",
])
for r in results:
    print(r.path, r.status, len(r.transactions), "rows")

Với nhập PDF hàng loạt, sử dụng scan_and_ingest() xử lý toàn bộ cây thư mục với tự động chống trùng lặp.

Định dạng hỗ tr���

Hỗ trợ những định dạng sao kê ngân hàng nào?

Đị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
PDF	Sao kê kỹ thuật số và sao kê quét	.pdf	smart_ingest()

Pipeline PDF hybrid hoạt động như thế nào?

Pipeline hybrid (v0.0.5+) tự động định tuyến PDF qua ba đường dẫn trích xuất:

• Đường dẫn A (Deterministic): Bảng PDF có cấu trúc được phân tích trực tiếp — miễn phí, nhanh nhất, không cần LLM.
• Đường dẫn B (Text-LLM): PDF kỹ thuật số có bố cục phức tạp được trích xuất qua LLM cục bộ (LiteLLM/Ollama).
• Đường dẫn C (Vision-LLM): Sao kê quét hoặc photocopy được xử lý bằng mô hình vision đa phương thức.

Mọi kết quả trích xuất đều được xác minh bằng Golden Rule (opening + credits − debits == closing). Các sai lệch có thể được xem xét tương tác với --type review.

Trình phân tích có xử lý các biến thể CAMT.053 theo ngân hàng không?

Có -- thiết kế không phụ thuộc namespace. Trình phân tích loại bỏ namespace XML trước khi xử lý, xử lý mọi biến thể CAMT.053 (camt.053.001.02, camt.053.001.04, hoặc wrapper ngân hàng độc quyền) mà không cần cấu hình namespace cụ thể. Truy vấn XPath nhắm vào cấu trúc phần tử, không phải URI namespace.

Với các ngân hàng bọc CAMT trong envelope tùy chỉnh, sử dụng from_string() hoặc from_bytes() để nạp trực tiếp tài liệu bên trong.

Tôi có thể ánh xạ tiêu đề cột CSV tùy chỉnh vào schema chuẩn không?

Có -- tự động chuẩn hóa, không cần cấu hình. CsvStatementParser nhận ra các biến thể tiêu đề phổ biến: "Date", "Transaction Date", "Booking Date" đều ánh xạ đến trường date. "Amount", "Value", "Sum" ánh xạ đến amount. Các cột tín dụng/ghi nợ tách biệt (ví dụ: "Credit" và "Debit") được phát hiện và kết hợp thành một số tiền có dấu tự động.

Định dạng đầu ra là gì?

Tất cả parser đều tạo pandas DataFrames chuẩn hóa với kiểu cột nhất quán:

Định dạng	Cột chính
CAMT	Amount, Currency, DrCr, Debtor, Creditor, Reference, ValDt, BookgDt, AccountId
PAIN.001	PmtInfId, PmtMtd, InstdAmt, Currency, CdtrNm, EndToEndId, MsgId, CreDtTm, NbOfTxs
CSV/OFX/QFX/MT940	date, description, amount (chuẩn hóa)

Bạn cũng có thể xuất sang CSV, JSON, Excel, Polars DataFrames, hledger, hoặc beancount journal.

Tính năng PDF và LLM

Pipeline hybrid hỗ trợ những mô hình LLM nào?

Pipeline sử dụng LiteLLM làm lớp trừu tượng mô hình, với bridge Ollama trực tiếp cho prompt vision. Các mô hình khuyến nghị:

• Trích xuất văn bản: Bất kỳ mô hình nào tương thích LiteLLM (cục bộ hoặc remote).
• Trích xuất vision: ollama/minicpm-v (khuyến nghị) cho PDF quét.
• Phân loại: Bất kỳ mô hình nào tương thích LiteLLM.

Tất cả mô hình đều có thể chạy 100% cục bộ qua Ollama — không cần API key.

Xác minh Golden Rule là gì?

Mọi kết quả trích xuất PDF đều được xác minh bằng phương trình: opening balance + credits − debits == closing balance. Kết quả được gắn nhãn:

• VERIFIED: Số dư khớp chính xác.
• DISCREPANCY: Số dư không khớp — khuyến nghị xem xét.
• FAILED: Không thể thực hiện xác minh (thiếu dữ liệu số dư).

Tôi có thể tự động phân loại giao dịch không?

Có. Module enrichment (v0.0.6+) cung cấp phân loại giao dịch bằng LLM:

from bankstatementparser.enrichment import Categorizer

categorizer = Categorizer()
enriched = categorizer.categorize_batch(transactions)

Schema mặc định sử dụng 13 danh mục tương thích Plaid. Bạn có thể cung cấp schema danh mục riêng.

Tôi có thể xuất sang hledger hoặc beancount không?

Có (v0.0.8+). Xuất giao dịch sang định dạng sổ nhật ký kế toán plaintext với ánh xạ tài khoản:

from bankstatementparser.export import to_hledger, to_beancount

journal = to_hledger(transactions, account="Assets:Bank:Checking")

Quy trình ngân quỹ

Trình phân tích xử lý sao kê đa tiền tệ như thế nào?

Mỗi giao dịch giữ nguyên tiền tệ gốc -- không có chuyển đổi ngầm. Trường Currency được trích xuất từ thuộc tính XML Ccy cho mỗi giao dịch. Sao kê đa tiền tệ giữ nguyên. Phương thức get_account_balances() trả về số dư đầu kỳ và cuối kỳ mỗi tài khoản với mã tiền tệ gốc.

Từ v0.0.8, verify_balance_multi_currency() nhóm giao dịch theo tiền tệ và chạy Golden Rule độc lập cho mỗi nhóm — hữu ích cho các tài khoản giữ nhiều loại tiền tệ.

Trình phân tích có hỗ trợ cả định dạng đi và đến không?

Có. Pain001Parser xử lý tệp khởi tạo chuyển khoản ISO 20022 PAIN.001 (thanh toán đi). CamtParser xử lý tệp sao kê ngân hàng gửi khách hàng CAMT.053 (báo cáo đến). Cả hai đều hỗ trợ streaming, ẩn danh PII, và xuất sang CSV, JSON, Excel, hledger, và beancount. Sử dụng detect_statement_format() để tự động nhận dạng định dạng.

Điều gì xảy ra khi mục nhập giao dịch không đúng định dạng?

Hành vi phụ thuộc vào chế độ phân tích:

• parse() (chế độ batch) -- Các mục nhập không đúng định dạng thiếu trường bắt buộc (Amount, Currency, hoặc CdtDbtInd) bị bỏ qua kèm cảnh báo log. Phần còn lại của sao kê được phân tích bình thường.
• parse_streaming() (chế độ streaming) -- Lỗi phân tích lan truyền ngay lập tức dạng ngoại lệ. Không mất dữ liệu im lặng. Hành vi fail-fast này là có chủ đích cho quy trình tài chính nơi mọi giao dịch phải được ghi nhận.
• smart_ingest() (PDF hybrid) -- Lỗi trích xuất được ghi nhận trong IngestResult với trạng thái xác minh, cho phép xem xét tương tác.

Chống trùng lặp hoạt động như thế nào?

Mỗi giao dịch được gán transaction_hash idempotent (dấu vân tay MD5) dựa trên các trường chính. Điều này cho phép nhập dữ liệu gia tăng an toàn — xử lý lại cùng một tệp tạo ra cùng hash, nên bản sao được phát hiện tự động.

from bankstatementparser import CamtParser, Deduplicator

parser = CamtParser("statement.xml")
dedup = Deduplicator()
result = dedup.deduplicate(dedup.from_dataframe(parser.parse()))

print(f"Unique: {len(result.unique_transactions)}")
print(f"Exact duplicates: {len(result.exact_duplicates)}")
print(f"Suspected matches: {len(result.suspected_matches)}")

Cài đặt và tương thích

Làm thế nào để cài đặt Bank Statement Parser?

# Cài đặt cơ bản (chỉ trình phân tích xác định)
pip install bankstatementparser

# Pipeline PDF hybrid
pip install 'bankstatementparser[hybrid]'         # Đường dẫn Text-LLM
pip install 'bankstatementparser[hybrid-vision]'   # Đường dẫn Vision-LLM

# Gói mở rộng
pip install 'bankstatementparser[enrichment]'      # Phân loại giao dịch
pip install 'bankstatementparser[api]'             # Microservice REST API
pip install 'bankstatementparser[polars]'          # Hỗ trợ Polars DataFrame

Phiên bản Python nào được hỗ trợ?

Python 3.10 đến 3.14. Hỗ trợ Python 3.9 đã bị loại bỏ trong v0.0.6 (EOL 2025-10-31). Tất cả phiên bản được kiểm tra trong CI với 718 bài kiểm tra ở 100% độ phủ nhánh.

Các phụ thuộc là gì?

Thư viện lõi có 5 phụ thuộc trực tiếp:

• lxml -- Phân tích XML với tăng cường bảo mật
• pandas -- DataFrames và thao tác dữ liệu
• openpyxl -- Xuất Excel
• pydantic -- Xác thực dữ liệu và mô hình
• defusedxml -- Bảo vệ XXE

Các gói mở rộng tùy chọn thêm: litellm, pypdf, pdfplumber, pypdfium2, fastapi, uvicorn, polars.

Tất cả phụ thuộc đều có phiên bản khóa hash SHA-256. CycloneDX SBOM ánh xạ mọi thành phần runtime.

Có hoạt động trên macOS, Linux và Windows không?

Có. Thư viện hoạt động trên macOS, Linux và Windows (qua WSL). Không có phụ thuộc nền tảng cụ thể.

Có REST API không?

Có (v0.0.8+). Cài đặt với pip install 'bankstatementparser[api]' và chạy:

bankstatementparser-api --port 8000

Các endpoint: POST /ingest (phân tích sao kê) và GET /health (kiểm tra sức khỏe).

Khả năng tái tạo và bảo mật

Làm thế nào để xác minh khả năng tái tạo?

python -m pytest                              # 718 tests, 100% branch coverage
python scripts/verify_locked_hashes.py        # SHA-256 hash verification
git log --show-signature -1                   # Verify commit signature

Những biện pháp bảo mật nào được tích hợp sẵn?

• Bảo vệ XXE: resolve_entities=False, no_network=True, load_dtd=False
• Bảo vệ ZIP Bomb: Giới hạn tỷ lệ nén, giới hạn kích thước mục nhập, 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
• Xác thực đầu vào: Giới hạn kích thước tệp (mặc định 100 MB), xác thực extension/định dạng
• 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
• Commit có chữ ký: Được thực thi trong CI
• Chỉ LLM cục bộ: Pipeline PDF hybrid sử dụng Ollama — không gọi cloud API

Bank Statement Parser so với pyiso20022 như thế nào?

pyiso20022 là bộ công cụ ISO 20022 tổng quát tạo dataclass Python từ schema ISO XML. Nó bao gồm nhiều loại thông báo ISO 20022 (PACS, PAIN, CAMT, ADMI) với xác thực schema. Bank Statement Parser được xây dựng chuyên dụng để phân tích sao kê ngân hàng với hỗ trợ PDF hybrid, xác minh số dư, làm giàu dữ liệu, xuất sổ cái, và API thống nhất trên bảy định dạng bao gồm các định dạng không phải ISO (CSV, OFX, QFX, MT940, PDF). Nếu bạn cần phân tích sao kê ngân hàng thành DataFrames với bảo mật cấp production, sử dụng Bank Statement Parser. Nếu bạn cần làm việc với danh mục thông báo ISO 20022 đầy đủ, sử dụng pyiso20022.

Thời hạn chuyển đổi SWIFT ISO 20022 là khi nào?

SWIFT đã công bố lộ trình chuyển đổi theo giai đoạn:

• Tháng 11/2026: Địa chỉ có cấu trúc và địa chỉ kết hợp trở thành bắt buộc. Các thông báo đa lệnh MT101 sẽ bị từ chối. Quản lý case Giai đoạn 1 bắt đầu.
• Tháng 11/2027: Tất cả tổ chức tài chính phải có khả năng nhận sao kê CAMT.053 nguyên bản. SWIFT sẽ ngừng chuyển đổi MT sang định dạng ISO.
• Tháng 11/2028: Ngừng hoàn toàn MT940, MT942, MT950, MT900 và MT910. Chúng sẽ được thay thế bằng CAMT.052, CAMT.053 và CAMT.054 tương đương.

Bank Statement Parser hỗ trợ cả định dạng MT940 cũ và định dạng CAMT.053/PAIN.001 hiện đại, là lựa chọn lý tưởng cho giai đoạn chuyển tiếp.