AI Engineer Roadmap: Xây dựng Ứng dụng Đa phương thức với LlamaIndex

LlamaIndex không phải một chatbot framework. Nó là framework cho bài toán nạp dữ liệu, chia nhỏ, đánh index và truy xuất. Khi dữ liệu có ảnh, PDF scan và bảng biểu, giá trị của nó nằm ở chỗ biến các tài liệu hỗn hợp thành node có metadata và provenance, rồi cho bạn kiểm soát từng bước của pipeline.

Bài này tập trung vào kiến trúc: một tài liệu đa phương thức đi qua những tầng nào, chọn cách biểu diễn ảnh nào, và đo chất lượng truy xuất ra sao. Các đoạn code là khung khái niệm; API của LlamaIndex vẫn ở nhánh 0.x nên một số đường dẫn import có thể đổi giữa các minor version.

Cập nhật 2026

  • LlamaIndex core 0.14.25, Workflows 2.26.1, giấy phép MIT. Đây là framework trưởng thành nhưng chưa lên 1.0, nên đừng giả định API ổn định tuyệt đối.
  • Workflows dùng Workflow, @step và typed event; đây là cách viết pipeline có checkpoint và resume, thay cho việc nối chuỗi bằng tay.
  • LlamaIndex hỗ trợ MCP tools, workflow checkpoint/resume, và xuất trace qua LangSmith hoặc OTel.
  • Embedding đa phương thức đã thực dụng hơn: Gemini Embedding 2 nhận text/image/audio/video/PDF với 128–3072 chiều; Cohere Embed v5.0 nhận text + image/PDF với context 128K.

Kiến trúc một pipeline đa phương thức

Luồng dữ liệu có bốn tầng, và mỗi tầng có một loại lỗi riêng:

Tài liệu gốc (PDF, ảnh, trang web)
        |
        v
  Reader  ->  Document + metadata (nguồn, trang, loại)
        |
        v
  Parser  ->  Node (text, image, hoặc cặp text+image)
        |
        v
  Index   ->  vector + (tùy chọn) lexical index
        |
        v
  Retriever -> Workflow/QueryEngine -> LLM -> câu trả lời kèm citation

Điểm quan trọng: truy xuất và tổng hợp là hai bài toán khác nhau. Retriever chỉ cần tìm đúng node; LLM đa phương thức mới là thứ đọc ảnh và viết câu trả lời. Trộn hai việc này làm khó đo: khi câu trả lời sai, bạn không biết lỗi ở khâu tìm hay khâu đọc.

Ba cách biểu diễn ảnh

Không có cách nào đúng cho mọi trường hợp. Chọn theo loại truy vấn bạn cần hỗ trợ:

Cách biểu diễn Hợp với Giới hạn
ImageDocument độc lập, embed bằng model đa phương thức Thư viện ảnh, tìm ảnh giống ảnh Không tận dụng văn bản xung quanh; khó giải thích kết quả
TextNode + metadata trỏ tới ảnh Báo cáo, tài liệu có chú thích Truy vấn chỉ dựa trên text; ảnh không tự tìm được
Node kết hợp text + ảnh (caption rồi embed) Hỏi đáp tài liệu, trích dẫn nguồn Tốn một lần gọi VLM cho mỗi ảnh; caption có thể sai

Với tài liệu doanh nghiệp, cách thứ ba thường là mặc định thực dụng: dùng một vision-language model để tạo mô tả cho ảnh, gắn mô tả đó vào node văn bản cùng provenance (file, trang, hộp bao), rồi embed phần text. Khi truy vấn, retriever tìm node theo text; lúc tổng hợp, bạn có thể gửi kèm ảnh gốc cho model đa phương thức để nó tự đọc.

Hai lưu ý về cách này. Thứ nhất, caption là dữ liệu dẫn xuất: nếu ảnh thay đổi, caption cũ phải được tạo lại, nên hãy lưu hash của ảnh trong metadata. Thứ hai, đừng embed caption và embed ảnh vào cùng một index nếu hai vector đến từ hai model khác nhau; không gian vector không tương thích và điểm tương đồng sẽ vô nghĩa.

Ingestion pipeline

LlamaIndex tách phần nạp và phần biến đổi. SimpleDirectoryReader đọc thư mục theo phần mở rộng; IngestionPipeline chạy các transformation và có thể cache theo hash của node để tránh xử lý lại. Đây là chỗ bạn nên đặt chi phí một lần thay vì lặp lại mỗi lần index.

# File: app/ingest.py
# pip install "llama-index-core==0.14.25"
from llama_index.core import SimpleDirectoryReader, IngestionPipeline, Settings
from llama_index.core.node_parser import SentenceSplitter

Settings.chunk_size = 512
Settings.chunk_overlap = 64

reader = SimpleDirectoryReader(
    "data",
    required_exts=[".pdf", ".png", ".jpg"],
    recursive=True,
)
documents = reader.load_data()

pipeline = IngestionPipeline(
    transformations=[
        SentenceSplitter(chunk_size=512, chunk_overlap=64),
    ]
)
nodes = pipeline.run(documents=documents, show_progress=True)
print(len(documents), len(nodes))

Đường dẫn import của ImageDocument và các extractor metadata nên được kiểm tra lại với bản 0.14.25 bạn cài, vì LlamaIndex đã đổi cấu trúc package nhiều lần. Đừng viết code dựa trên một bài blog cũ mà không chạy python -c "import ..." trước.

Với PDF, phần khó không phải đọc file mà là hiểu bố cục. Ba lựa chọn theo thứ tự chi phí:

  • Trích text thuần — rẻ nhất, nhưng mất bảng và biểu đồ, và thứ tự đọc có thể sai với bố cục nhiều cột.
  • Parse theo layout — giữ được vùng bảng, vùng ảnh; cần một parser có hiểu bố cục, và vẫn phải kiểm tra thủ công trên mẫu.
  • Render từng trang thành ảnh — giữ được mọi thứ nhìn thấy, nhưng chi phí token tỉ lệ số trang. Chỉ dùng cho tài liệu mà bố cục là thông tin, ví dụ báo cáo tài chính.

Một mẹo đã được đo và công bố: contextual retrieval của Anthropic (2024) thêm ngữ cảnh riêng cho từng chunk trước khi embed và index từ khóa, giảm 35% lỗi top-20, 49% khi thêm BM25, 67% khi thêm reranking. Bạn có thể làm điều tương tự mà không cần dịch vụ ngoài: thêm một câu mô tả “chunk này nằm ở mục nào của tài liệu nào” vào trước nội dung trước khi embed.

Truy xuất đa phương thức

Với văn bản, hybrid search là mặc định hợp lý: BM25 hoặc lexical search bắt được mã đơn hàng, tên riêng, số liệu mà embedding thường bỏ sót; vector search bắt được cách diễn đạt khác. Qdrant 1.20.0 có prefetch và RRF/DBSF native; Elasticsearch 9.5.x có RRF; pgvector 0.8.7 không có fusion native nên bạn phải tự RRF ở tầng ứng dụng. Chroma 1.5.9 chỉ có substring/regex, không phải BM25 — đừng dùng nó như lexical index.

Với ảnh, ba chiến lược hay dùng:

  • Caption + text embedding — dễ nhất, tương thích mọi vector store, nhưng chất lượng phụ thuộc caption.
  • Multimodal embedding — Gemini Embedding 2 hoặc Cohere Embed v5.0 cho phép query bằng ảnh hoặc tìm ảnh bằng text trong cùng không gian. Đây là lựa chọn khi người dùng chụp ảnh và hỏi “cái này là gì”.
  • Hai index riêng rồi fuse — index text và index ảnh, hợp nhất kết quả bằng RRF. Linh hoạt nhưng phải chuẩn hóa điểm số và đo recall của từng nhánh.

Dù chọn cách nào, hãy đo recall@k trước rồi mới thêm reranker. Reranker tăng precision, không tạo ra tài liệu chưa được retrieve. Nếu đáp án đúng không nằm trong 20 ứng viên đầu, một cross-encoder như Cohere rerank-v5.0 hay Voyage rerank-3 không cứu được.

Workflow thay cho query engine một lớp

VectorStoreIndex.as_query_engine() đủ cho prototype, nhưng không đủ khi bạn cần kiểm tra chất lượng từng bước. Workflows 2.26.1 cho phép tách retrieve, lọc, tổng hợp thành các step có kiểu dữ liệu rõ ràng và checkpoint.

# File: app/qa_workflow.py
# Khung khái niệm cho LlamaIndex Workflows 2.26.1.
from pydantic import BaseModel
from llama_index.core.workflow import Workflow, StartEvent, StopEvent, step


class Retrieved(BaseModel):
    nodes: list
    query: str


class MultimodalQA(Workflow):
    def __init__(self, retriever, llm, **kwargs):
        super().__init__(**kwargs)
        self.retriever = retriever
        self.llm = llm

    @step
    async def retrieve(self, ev: StartEvent) -> Retrieved:
        nodes = await self.retriever.aretrieve(ev.query)
        return Retrieved(nodes=nodes, query=ev.query)

    @step
    async def synthesize(self, ev: Retrieved) -> StopEvent:
        context = "\n\n".join(n.node.get_content() for n in ev.nodes)
        answer = await self.llm.acomplete(
            f"Câu hỏi: {ev.query}\n\nNgữ cảnh:\n{context}"
        )
        return StopEvent(result=str(answer))

Phần trên là khung, không phải API chính thức: tên event, kiểu trả về và cách truyền retriever phụ thuộc phiên bản. Điều đáng giữ là cấu trúc: mỗi bước có input/output kiểu rõ ràng, nên bạn có thể chèn một bước kiểm tra (ví dụ từ chối trả lời khi số node retrieved quá ít) mà không viết lại toàn bộ.

Khi node chứa ảnh, bước synthesize cần gửi cả ảnh cho model đa phương thức, không chỉ text. Nếu bạn chỉ gửi caption, bạn đang đánh giá caption chứ không đánh giá khả năng đọc ảnh của model. Hãy chọn rõ: pipeline “caption-first” hay “image-at-synthesis”. Hai thiết kế này có ngân sách và độ trễ khác nhau.

Đánh giá pipeline

Một pipeline đa phương thức không thể đánh giá bằng cảm giác. Tối thiểu bạn cần:

  • Tập câu hỏi có đáp án và nguồn đúng — 50–100 câu, phân tầng theo loại: text thuần, bảng, ảnh, câu hỏi cần kết hợp hai trang. Ghi rõ trang và node kỳ vọng.
  • Recall@k và MRR — đo riêng khâu retrieval. Đây là chỉ số duy nhất cho biết index của bạn có chứa thông tin hay không.
  • Groundedness/faithfulness — câu trả lời có bám vào ngữ cảnh retrieved hay không. Ragas 0.4.3 và DeepEval 4.3.3 đều có metric loại này; cả hai nên pin phiên bản vì metric đổi theo bản.
  • Chi phí mỗi câu trả lời — input, cached input, output và reasoning token tính riêng. Ảnh làm input phình nhanh; theo dõi riêng để biết chi phí đến từ đâu.

Nếu dùng LLM-as-judge, đừng chấm một chiều. Judge có position bias, verbosity bias và self-preference; điểm không được calibrate. Cách giảm: đổi thứ tự cặp so sánh, rubric có neo cụ thể, dùng judge khác họ model, và hiệu chỉnh trên một tập người chấm. Đừng dùng judge một mình để chặn các quyết định an toàn.

Pitfall

  • Trộn không gian vector. Caption embed bằng model text và ảnh embed bằng model ảnh không so sánh được. Nếu muốn tìm ảnh bằng text, dùng một model đa phương thức thật.
  • Index lại toàn bộ mỗi lần sửa một file. Dùng hash nội dung trong metadata và cache transformation; nếu không, chi phí VLM sẽ tăng tuyến tính theo số lần chạy.
  • Không lưu provenance. Mỗi node phải biết file, trang, phiên bản parser. Không có provenance thì không thể trích dẫn, không thể debug, và không thể xóa đúng dữ liệu khi có yêu cầu.
  • Đánh giá trên ảnh sạch. Dữ liệu thật là ảnh nghiêng, mờ, chụp bằng điện thoại. Tập eval phải có ít nhất 20% mẫu xấu, nếu không bạn đang đo một hệ thống khác với hệ thống chạy thật.
  • Tin vào OCR tuyệt đối. OCR sai số, mã sản phẩm, dấu tiếng Việt. Với trường quan trọng, kiểm tra bằng regex hoặc đối chiếu nguồn thứ hai.

LlamaIndex hay LangChain?

Nhu cầu Chọn Lý do
Nhiều tài liệu, retrieval là trung tâm LlamaIndex Reader, node parser, index, retriever có sẵn
Agent có tool, nhiều provider LangChain/LangGraph Vòng lặp agent, middleware, checkpointer
Pipeline cố định, cần kiểm soát từng bước LlamaIndex Workflows Step có kiểu, checkpoint, resume
Prototype nhanh một index Cả hai Vài dòng đã chạy; chọn theo hệ sinh thái bạn đã có

Đừng chọn theo độ nổi tiếng. Chọn theo nơi phát sinh lỗi nhiều nhất trong dự án của bạn: nếu lỗi nằm ở dữ liệu và truy xuất, LlamaIndex cho ít code hơn; nếu lỗi nằm ở điều phối và quyền hạn của agent, LangGraph cho ít code hơn.

Nhìn trước 2027

Hai thay đổi sẽ ảnh hưởng trực tiếp. Thứ nhất, embedding đa phương thức ngày càng phổ biến, nên “caption rồi embed text” có thể trở thành lựa chọn dự phòng thay vì mặc định. Thứ hai, các parser bố cục tài liệu đang tốt lên, làm giảm nhu cầu render toàn bộ PDF thành ảnh. Cả hai đều giảm chi phí, nhưng đều làm pipeline phụ thuộc nhiều hơn vào một model cụ thể — hãy giữ lớp adapter để đổi.

Checklist

  • Pin llama-index-core==0.14.25 và Workflows 2.26.1; kiểm tra import trước khi viết code.
  • Chọn rõ một trong ba cách biểu diễn ảnh và ghi lý do trong README.
  • Lưu provenance (file, trang, hash, phiên bản parser) trong metadata của mọi node.
  • Đo recall@k trên 50 câu hỏi trước khi thêm reranker hoặc đổi embedding.
  • Đặt ngân sách riêng cho chi phí caption ảnh và theo dõi nó như một dòng chi phí độc lập.

Bài liên quan