Đọc báo cáo tài chính từ tệp PDF
Mục lục
Báo cáo tài chính công bố dạng PDF là bảng in cho người đọc, không phải bảng số cho máy tính. Trang này mô tả cách vnstock-mcp cùng trợ lý AI biến một tệp PDF trên máy bạn thành bảng số đã chuẩn hoá và đã kiểm tra, dùng được cho tính chỉ số, ghép nhiều kỳ và so sánh giữa các công ty.
Ở
vnstock-mcp1.0.0, công cụresearch_statementsmang tênresearch_bctcvà mẫustatements_deep_divemang tênbctc_deep_dive. Script tái lập tạo bằng 1.0.0 (gọivnstock_mcp.bctc) vẫn chạy ở bản mới.
Ai làm việc gì
Chu trình chia việc cho ba bên, mỗi bên làm phần mình làm tốt nhất:
| Bên | Làm gì | Không làm gì |
|---|---|---|
| Trợ lý AI (Claude, ChatGPT, Gemini, Antigravity…) | Đọc trang PDF (chữ hoặc ảnh), chép từng dòng số như in, đọc lại trang khi kiểm toán báo lệch | Không tự gán mã chỉ tiêu, không tự sửa số cho khớp |
vnstock-mcp | Nhận diện loại tệp và trang của từng báo cáo, chọn bảng mã theo mẫu biểu, ánh xạ từng dòng về từ điển VAS, kiểm tra phương trình kế toán, tách quý từ số luỹ kế. Phần nhận diện, ánh xạ và kiểm toán chạy trong lõi Rust | Không đọc ảnh, không đoán số thiếu |
vnstock_quant (qua quant_fa) | Tính chỉ số tài chính từ bảng đã chuẩn hoá | Không tính trên bảng còn lệch kiểm toán |
Cách chia này có lý do. Việc gán mã chỉ tiêu và kiểm toán cần cùng một bộ quy tắc ở mọi lần chạy, nên nằm trong lõi. Phần trợ lý AI làm chỉ là chép, nên ai cũng kiểm lại được trên trang gốc.
Chu trình bảy bước
Tệp PDF/ZIP trên máy
│
├─ 1. research_statements(method="guide") khung đọc theo loại hình, danh mục thuyết minh
├─ 2. research_pdf(method="inspect") loại tệp, trang của từng báo cáo, độ lệch trang
├─ 3. research_pdf(method="extract") chữ, bảng hoặc ảnh của đúng các trang đó
│
├─ 4. Trợ lý AI chép số ──► tệp JSON số như in, chưa có mã chỉ tiêu
│
├─ 5. research_statements(method="standardize") bảng dài có vas_code + kết quả kiểm toán
│ └─ lệch? đọc lại trang gốc, sửa JSON, chạy lại bước 5
│
├─ 6. quant_fa(data=<call_id của bước 5>) chỉ số tài chính
└─ 7. research_statements(method="profile") hồ sơ Markdown
research_save, research_journal lưu bảng, xuất script Python chạy lại đượcCài phần đọc PDF kèm theo: vnstock-mcp[pdf] (gồm pdfplumber, pypdf, pypdfium2).
Bước 1. Có tệp trên máy
Các công cụ nhận đường dẫn tệp trên máy (PDF, hoặc ZIP chứa PDF) và không nhận URL. Bạn tải báo cáo về, hoặc nhờ trợ lý AI tải bằng công cụ của chính nó, rồi đưa đường dẫn tệp.
Loại hình (company_type) theo mẫu biểu in trên báo cáo, không theo ngành của công ty:
company_type | Mẫu biểu |
|---|---|
DN | Doanh nghiệp (mẫu B01-DN, B02-DN, B03-DN) |
TCTD | Tổ chức tín dụng (B02/TCTD, B03/TCTD, B04/TCTD) |
CTCK | Công ty chứng khoán (B01-CTCK…) |
DNPNT | Doanh nghiệp bảo hiểm (B01-DNPNT…) |
research_statements(method="guide") trả khung đọc riêng cho từng loại hình và danh mục thuyết minh trọng yếu (NT_*) nên chú ý.
Bước 2. Khảo sát tệp
research_pdf(method="inspect", path=...) đọc nhanh các trang đầu và trả:
| Trường | Ý nghĩa |
|---|---|
pdf_type | digital_text (có lớp chữ đọc được), scanned_image (bản quét) hoặc hybrid |
pages_mapping | Trang đầu của balance_sheet, income_statement, cash_flow, footnotes_start, nhận theo tiêu đề và số mẫu biểu |
page_offset | Độ lệch giữa số trang in và số trang trong tệp: physical_page = printed_page + page_offset. Bằng null khi không đọc được số trang in nào, thường gặp ở bản quét |
page_summaries | Từng trang: số ký tự, có đọc được chữ không, báo cáo nhận ra trên trang, vài dòng đầu |
Với bản quét, lớp chữ thường là chữ nhận dạng sai nên pages_mapping có thể trống. Khi đó trợ lý AI xuất ảnh vài trang đầu (bìa, mục lục) để tìm trang của ba báo cáo chính.
Bước 3. Lấy nội dung trang
research_pdf(method="extract", path=..., pages=[...], mode=...):
digital_text:mode="tables"lấy bảng; bảng vỡ cột thì dùngmode="text".scanned_imagehoặchybrid:mode="images"xuất ảnh PNG (mặc định 150 DPI) cho trợ lý AI đọc bằng thị giác.pagesnhận danh sách hoặc chuỗi"4-10,15". Đặtuse_printed_pages=truecùngpage_offsetđể dùng số trang in trên mục lục.
Ảnh và bản đệm nằm trong thư mục nghiên cứu (~/vnstock_research/pdf_images/, pdf_cache/).
Bước 4. Chép số thành JSON
Trợ lý AI chép ba báo cáo chính thành một tệp JSON. Đây là bản chép nguyên văn: có mã số in trên báo cáo, tên dòng và số, nhưng chưa có mã chỉ tiêu của vnstock. Mã chỉ tiêu do bước 5 gán.
{
"metadata": {
"symbol": "ABC", "sector": "DN", "scope": "consolidated",
"unit": "TRIEU_VND", "form": "B01a-DN/HN", "form_basis": "Thông tư 99/2025/TT-BTC",
"fiscal_year_end": "31/12", "notes": []
},
"balance_sheet": [{"code": "280", "name": "TỔNG CỘNG TÀI SẢN", "30.09.2026": 1234, "31.12.2025": 1100}],
"income_statement": [{"code": "10", "name": "3. Doanh thu thuần về bán hàng và cung cấp dịch vụ",
"Q3_2026": 150, "Q3_2025": 120, "9M_2026": 400, "9M_2025": 330}],
"cash_flow": [{"code": "20", "name": "Lưu chuyển tiền thuần từ hoạt động kinh doanh",
"9M_2026": 90, "9M_2025": 70}]
}Quy tắc chép:
- Mỗi dòng có số là một phần tử, theo thứ tự in, kể cả dòng tổng. Dòng tiêu đề không có số thì bỏ.
codechép đúng cột "Mã số" ("01","111","223a"). Báo cáo không có cột mã số (ngân hàng hay gặp) thì để"".namechép nguyên văn, giữ cả số thứ tự đầu dòng.- Số là số nguyên theo đơn vị in. Số trong ngoặc là số âm. Ô
-hoặc trống thì bỏ khoá kỳ đó. unittheo dòng "Đơn vị tính":VND,NGHIN_VND,TRIEU_VND,TY_VND. Lãi trên cổ phiếu giữ đơn vị đồng, không nhân hệ số.scope:consolidated(hợp nhất) hoặcseparate(riêng).
Nhãn kỳ:
| Báo cáo | Nhãn |
|---|---|
| Bảng cân đối | Ngày: 30.09.2026, 31.12.2025 |
| Kết quả kinh doanh | Một quý Q3_2026; luỹ kế từ đầu năm 9M_2026 (6 tháng 6M_2026); cả năm 2025 |
| Lưu chuyển tiền tệ | Giữa niên độ luôn là luỹ kế: 9M_2026; cả năm 2025 |
Năm tài chính không kết thúc 31/12 thì ghi fiscal_year_end (ví dụ "31/03").
Bước 5. Chuẩn hoá và kiểm toán
research_statements(method="standardize", data=<đường dẫn JSON hoặc chuỗi JSON>, symbol=..., company_type=..., format="long") làm bốn việc trong lõi Rust:
- Chọn bảng mã cho từng báo cáo. Cùng một chỉ tiêu có thể mang mã khác nhau tuỳ văn bản: tổng tài sản là
270theo Thông tư 200 nhưng280theo Thông tư 99. Lưu chuyển tiền tệ trực tiếp và gián tiếp cũng dùng hai bộ mã khác nhau. MCP chấm điểm từng bảng mã trên chính số liệu của tài liệu rồi chọn bảng khớp nhất. Tỷ số hoà thì theo văn bản áp dụng cho kỳ. - Đối chiếu văn bản áp dụng. Từ kỳ báo cáo và phạm vi (riêng hay hợp nhất), MCP tra mốc hiệu lực của các thông tư về mẫu biểu, ví dụ báo cáo của năm tài chính bắt đầu từ 01/01/2026 theo Thông tư 99/2025/TT-BTC. Bảng mã chọn được mà lệch văn bản dự kiến thì có cảnh báo, vì doanh nghiệp chuyển đổi mẫu không đều.
- Ánh xạ từng dòng về mã chỉ tiêu VAS (
vas_code): theo mã số trước, theo tên khi mã không có hoặc mâu thuẫn, chỉ nhận khi không nhập nhằng. - Kiểm toán số học: phương trình kế toán (tổng tài sản bằng tổng nguồn vốn, tiền cuối kỳ của lưu chuyển tiền tệ khớp bảng cân đối…), tổng con bằng cha, và đẳng thức của mẫu biểu.
Đầu ra là bảng dài, mỗi ô số là một dòng:
| Cột | Ví dụ | Ý nghĩa |
|---|---|---|
period, period_type | 2026-Q3, quarter | Kỳ đã chuẩn hoá: quarter, cumulative (luỹ kế), annual |
statement | balance_sheet | Báo cáo |
code, item_name_vi | 280, TỔNG CỘNG TÀI SẢN | Mã và tên như in |
vas_code | BS_TOTAL_ASSETS | Mã chỉ tiêu VAS của vnstock, giống nhau ở mọi công ty, mọi thông tư |
level, parent_code | 2, BS_OWNERS_EQUITY | Vị trí trong cây chỉ tiêu |
value_vnd, unit | 1.62e15, VNĐ | Số đã quy về đồng (lãi trên cổ phiếu: dong_per_share) |
mapped_by | line_code | Nhận theo mã số hay theo tên |
Mã chỉ tiêu tra được bằng research_vas(category="balance_sheet", company_type="DN"). Dòng tóm tắt (provenance) của kết quả cho biết trạng thái kiểm toán, tỷ lệ khớp, bảng mã đã chọn, phương pháp lưu chuyển tiền tệ và văn bản áp dụng cho kỳ.
format="wide" cho bảng tỷ đồng theo quý, quen thuộc khi đọc. format="long" giữ mọi kỳ và là đầu vào của quant_fa.
Đọc cảnh báo
Mọi cảnh báo đều phải được đọc lại trên trang gốc. Chép sai thì sửa JSON rồi chạy lại bước 5. Báo cáo in đúng như vậy thì giữ nguyên số, ghi vào metadata.notes.
| Cảnh báo | Thường do | Làm gì |
|---|---|---|
Phép kiểm lệch (MISMATCH) | Chép sai một số, sót dòng, sai dấu | Đọc lại các dòng của phép kiểm đó |
Dòng chưa khớp (UNMAPPED) | Dòng riêng của công ty, tên lạ, mã chép nhầm | Xem lại mã và tên; dòng riêng thật thì để nguyên |
CODE_NAME_CONFLICT | Mã số và tên dòng chỉ hai chỉ tiêu khác nhau | Đọc lại mã trên trang |
CODE_TABLE_VS_REGIME | Bảng mã khớp số liệu nhất không phải bảng của văn bản dự kiến | Kiểm lại mẫu biểu in trên báo cáo; thường là công ty chuyển mẫu sớm hoặc muộn |
CODE_TABLE_UNTRUSTED | Mã số của tài liệu không hợp bảng mã nào | Kiểm lại cột mã số; quant_fa sẽ từ chối bảng này |
Bước 6. Tính chỉ số
quant_fa(data=<call_id của bước 5>) tính chỉ số bằng vnstock_quant, cùng mã RT_* với chỉ số tính từ dữ liệu Open API. Tra tên và cách tính bằng quant_catalog(module="fa"). Những điều cần biết:
- Bảng còn lệch kiểm toán hoặc có bảng mã không tin được thì bị từ chối, để chỉ số không tính trên số sai.
- Biên lợi nhuận, ROE, ROA, vòng quay (
period="quarter") tính trên 4 quý gần nhất. Một báo cáo quý chỉ có quý đó và cùng quý năm trước, nên các chỉ số này trảINSUFFICIENT_HISTORYkèm cảnh báo nói rõ còn thiếu quý nào. Chỉ số từ bảng cân đối (thanh toán, đòn bẩy) vẫn tính được. - Quý được tách từ hai kỳ luỹ kế liền nhau: quý 3 = luỹ kế 9 tháng trừ luỹ kế 6 tháng; quý 4 = cả năm trừ luỹ kế 9 tháng. Chỉ tách khi năm tài chính trùng năm dương lịch.
- Báo cáo riêng không có dòng lợi ích cổ đông không kiểm soát: lợi nhuận của cổ đông công ty mẹ lấy bằng lợi nhuận sau thuế, kèm cảnh báo.
Bước 7. Hồ sơ, lưu và tái lập
research_statements(method="profile", data=...)ghi hồ sơ Markdown vào~/vnstock_research/reports/<MÃ>_<kỳ>_Analysis.md.research_save(call_id=..., name=...)ghi trọn bảng dài và bảng chỉ số ra~/vnstock_research/data/.call_idchỉ sống trong phiên: không lưu thì đóng ứng dụng là mất.research_journal(method="script", save=true)ghép cả phiên thành script Python trong~/vnstock_research/scripts/để bạn tự chạy lại.
Sau chu trình bạn có gì
| Thứ | Ở đâu | Dùng để |
|---|---|---|
| JSON chép từ PDF | Nơi trợ lý AI ghi tệp | Đầu vào chạy lại bước 5 bất cứ lúc nào, kể cả khi từ điển đã cập nhật |
Bảng dài có vas_code | call_id trong phiên; data/ sau research_save | Tính chỉ số, ghép kỳ, so sánh công ty |
| Kết quả kiểm toán | Trong kết quả bước 5 và hồ sơ | Biết số nào đã kiểm, số nào còn nghi |
Chỉ số RT_* | call_id; data/ sau research_save | Phân tích, ghép với giá |
| Hồ sơ Markdown | reports/ | Đọc nhanh |
| Script Python | scripts/ | Tự chạy lại, tự sửa |
Giữ tệp JSON ở thư mục ổn định của bạn. Thư mục nháp của ứng dụng AI có thể bị dọn, khi đó script tái lập không còn tệp để đọc.
Dùng tiếp bảng đã số hoá
Vì mỗi dòng đã mang vas_code chung, bảng từ PDF ghép được với mọi phần khác của vnstock-mcp:
- Ghép nhiều kỳ. Số hoá thêm các quý trước và báo cáo năm để có đủ 4 quý cho biên lợi nhuận, ROE theo 4 quý gần nhất, và để xem xu hướng.
- Lấp kỳ còn thiếu. Báo cáo vừa công bố, công ty nhỏ, hoặc báo cáo riêng khi bạn chỉ có số hợp nhất.
- Định giá. Lấy lợi nhuận, vốn chủ sở hữu, cổ tức từ bảng làm đầu vào cho
quant_valuation(P/E hợp lý, chiết khấu cổ tức), đặt cạnh giá từmarket_equity. - So sánh cùng ngành. Nhiều công ty cùng loại hình, kể cả khác thông tư, so được từng chỉ tiêu.
- Đọc thuyết minh. Chép thêm thuyết minh theo danh mục
NT_*của bước 1 (nợ vay theo kỳ hạn, doanh thu theo mảng, khoản bất thường) để xem chất lượng lợi nhuận.
Mẫu yêu cầu cho trợ lý AI
Trên ứng dụng hỗ trợ MCP Prompts, chọn statements_deep_dive. Hoặc gõ:
Đọc báo cáo tài chính ở /đường/dẫn/BCTC_Q3_2026.pdf (mã ABC, loại hình DN) bằng vnstock-mcp:
khảo sát tệp, chép ba báo cáo chính thành JSON đúng định dạng của research_statements, chuẩn hoá với
format="long", đọc lại trang gốc cho mọi cảnh báo, tính chỉ số bằng quant_fa, lưu bảng bằng
research_save và xuất script bằng research_journal. Báo lại kết quả kiểm toán và các cảnh báo còn lại.Giới hạn
- Chỉ đọc tệp trên máy, không nhận URL.
- Không có bộ nhận dạng chữ (OCR) riêng. Bản quét được trợ lý AI đọc từ ảnh trang, nên độ đúng của số phụ thuộc vào lần đọc đó; kiểm toán ở bước 5 là để bắt chỗ đọc sai.
- Số trong bảng là bản chép của bạn từ tài liệu bạn có, không phải số do Vnstock cung cấp. Kiểm toán đạt nghĩa là các phép cộng khớp nhau, không có nghĩa là mọi số đều khớp báo cáo gốc.
- Từ điển VAS được tải từ
vnstocks.comtrong phong bì có chữ ký số và chỉ giữ trong bộ nhớ của phiên. Tài khoản có Gói quyền sử dụng Vnstock còn hiệu lực nhận từ điển đầy đủ, gồm danh mục thuyết minhNT_*; các trường hợp khác nhận từ điển rút gọn. Không tải được từ điển thì công cụ báo lỗi, không ánh xạ theo bản dựng sẵn nào. - Kết quả là tư liệu nghiên cứu, không phải khuyến nghị đầu tư.
Bước tiếp theo
- Lưu bảng, nhập tệp riêng và xuất script: Lưu trữ dữ liệu, đọc BCTC và tái lập mã nguồn.
- Tính chỉ số và nối kết quả bằng
call_id: Tính toán định lượng và chạy thử chiến lược.
