Vnstock Logo

Đọc báo cáo tài chính từ tệp PDF

Mở rộngvnstock_mcp v1.1.0

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-mcp 1.0.0, công cụ research_statements mang tên research_bctc và mẫu statements_deep_dive mang tên bctc_deep_dive. Script tái lập tạo bằng 1.0.0 (gọi vnstock_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ênLà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ệchKhông tự gán mã chỉ tiêu, không tự sửa số cho khớp
vnstock-mcpNhậ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 RustKhô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

Text
 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 được

Cà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_typeMẫu biểu
DNDoanh nghiệp (mẫu B01-DN, B02-DN, B03-DN)
TCTDTổ chức tín dụng (B02/TCTD, B03/TCTD, B04/TCTD)
CTCKCông ty chứng khoán (B01-CTCK…)
DNPNTDoanh 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_typedigital_text (có lớp chữ đọc được), scanned_image (bản quét) hoặc hybrid
pages_mappingTrang đầ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_summariesTừ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ùng mode="text".
  • scanned_image hoặc hybrid: mode="images" xuất ảnh PNG (mặc định 150 DPI) cho trợ lý AI đọc bằng thị giác.
  • pages nhận danh sách hoặc chuỗi "4-10,15". Đặt use_printed_pages=true cùng page_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.

JSON
{
  "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ỏ.
  • code ché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ì để "".
  • name ché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ỳ đó.
  • unit theo 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ặc separate (riêng).

Nhãn kỳ:

Báo cáoNhãn
Bảng cân đốiNgày: 30.09.2026, 31.12.2025
Kết quả kinh doanhMộ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:

  1. 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à 270 theo Thông tư 200 nhưng 280 theo 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ỳ.
  2. Đố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.
  3. Á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.
  4. 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ộtVí dụÝ nghĩa
period, period_type2026-Q3, quarterKỳ đã chuẩn hoá: quarter, cumulative (luỹ kế), annual
statementbalance_sheetBáo cáo
code, item_name_vi280, TỔNG CỘNG TÀI SẢNMã và tên như in
vas_codeBS_TOTAL_ASSETSMã chỉ tiêu VAS của vnstock, giống nhau ở mọi công ty, mọi thông tư
level, parent_code2, BS_OWNERS_EQUITYVị trí trong cây chỉ tiêu
value_vnd, unit1.62e15, VNĐSố đã quy về đồng (lãi trên cổ phiếu: dong_per_share)
mapped_byline_codeNhậ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áoThường doLà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ầmXem lại mã và tên; dòng riêng thật thì để nguyên
CODE_NAME_CONFLICTMã số và tên dòng chỉ hai chỉ tiêu khác nhauĐọc lại mã trên trang
CODE_TABLE_VS_REGIMEBảng mã khớp số liệu nhất không phải bảng của văn bản dự kiếnKiể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_UNTRUSTEDMã số của tài liệu không hợp bảng mã nàoKiể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_HISTORY kè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_id chỉ 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ứỞ đâuDùng để
JSON chép từ PDFNơ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_codecall_id trong phiên; data/ sau research_saveTính chỉ số, ghép kỳ, so sánh công ty
Kết quả kiểm toánTrong 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_savePhân tích, ghép với giá
Hồ sơ Markdownreports/Đọc nhanh
Script Pythonscripts/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:

  1. 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.
  2. 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.
  3. Đị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.
  4. 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.
  5. Đọ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õ:

Text
Đọ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.com trong 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 minh NT_*; 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