LlamaIndex: framework RAG cho ứng dụng LLM
run-llama/llama_index
LlamaIndex là framework Python để kết nối các large language model với dữ liệu riêng của bạn — PDF, API, SQL — thông qua data connector, index và query engine. Nên dùng khi bạn xây tính năng tìm kiếm hoặc hỏi-đáp retrieval-augmented trên một nguồn dữ liệu thật và không muốn tự viết lại pipeline chunk-embed-store-retrieve. Nên bỏ qua nếu ứng dụng chỉ gọi một LLM provider duy nhất mà không có dữ liệu ngoài nào cần truy xuất.
LlamaIndex là gì?
LlamaIndex là framework Python mã nguồn mở mà chính README của nó gọi là một "data framework" để xây dựng ứng dụng LLM trên nền dữ liệu riêng hoặc theo lĩnh vực cụ thể. Nó cung cấp data connector cho các nguồn như PDF, API và SQL, cấu trúc hóa dữ liệu thành index, và một lớp retrieval/query trả về câu trả lời được bổ sung ngữ cảnh thay vì câu trả lời model đoán mò. Một API cấp cao xử lý ingest-và-query chỉ trong vài dòng code, cùng API cấp thấp hơn cho ai cần kiểm soát nhiều hơn.
Vì sao LlamaIndex ra đời
Một LLM được huấn luyện trên dữ liệu web công khai không biết gì về wiki nội bộ, các file PDF sản phẩm, hay dữ liệu trong bảng SQL của bạn — và việc dán thẳng dữ liệu đó vào prompt thì không mở rộng được quá vài trang. README của repo nói thẳng về khoảng trống này: bổ sung dữ liệu riêng cho một LLM tổng quát để nó trả lời dựa trên dữ liệu đó thay vì đoán từ dữ liệu pretraining. LlamaIndex được xây dựng để làm lớp hạ tầng ingest-đến-retrieval cho đúng khoảng trống này — connector kéo dữ liệu vào, index cấu trúc hóa dữ liệu, lớp query đưa các đoạn liên quan trở lại prompt — chứ không phải một framework xây agent tổng quát hay một dịch vụ host model.
Các tính năng chính của LlamaIndex
- ✓Data connector để ingest dữ liệu từ API, PDF, tài liệu, SQL và nhiều định dạng khác, theo đúng danh sách nguồn dữ liệu README liệt kê.
- ✓Nhiều cấu trúc index và graph khác nhau để tổ chức dữ liệu đã ingest sao cho một LLM có thể query được.
- ✓Một retrieval/query engine nhận prompt của LLM và trả về ngữ cảnh đã truy xuất cộng với câu trả lời được bổ sung tri thức, chứ không phải một completion thô.
- ✓Hai cách cài đặt: gói khởi đầu `llama-index` gộp sẵn core cùng một số integration được chọn trước, hoặc `llama-index-core` cộng thêm từng integration package riêng lẻ — có hơn 300 package được liệt kê trên LlamaHub — cho LLM, embedding và vector store provider bạn tự chọn.
- ✓Import được đặt namespace rõ ràng để nhận biết ngay: `llama_index.core.xxx` là core package, còn `llama_index.xxx.yyy` không có `core` là một integration package.
- ✓API phân lớp — một lối đi cấp cao ingest và query một thư mục file chỉ trong khoảng 5 dòng code, cùng các API cấp thấp hơn để thay data connector, index, retriever, query engine hoặc reranking module.
- ✓Persist dữ liệu ra đĩa qua `StorageContext` — lưu một index vào `./storage` và load lại sau này thay vì dựng lại từ đầu mỗi lần chạy.
- ✓LlamaParse, một nền tảng riêng cho agentic OCR và parsing tài liệu trên hơn 130 định dạng, cùng các công cụ Extract, Index, Split và document-agent có cấu trúc — dùng độc lập hoặc tích hợp vào framework LlamaIndex.
Bắt đầu với LlamaIndex
Có hai lối đi, đều qua pip. Với phần lớn dự án, `pip install llama-index` cho bạn gói khởi đầu — core LlamaIndex cộng một tập integration được chọn sẵn, không cần cấu hình thêm. Nếu muốn tự chọn LLM, embedding và vector store provider, hãy cài `llama-index-core` rồi chỉ thêm những integration package cần dùng — ví dụ chính từ README là `pip install llama-index-core llama-index-llms-openai llama-index-llms-ollama llama-index-embeddings-huggingface`, chọn từ hơn 300 package được liệt kê trên LlamaHub. Với setup dùng OpenAI, bạn cần set biến môi trường `OPENAI_API_KEY` trước khi viết bất kỳ code LlamaIndex nào. Cả hai lối đi đều là package Python thuần; README không nhắc tới trình cài đặt CLI riêng hay dependency hệ thống nào khác.
Xây dựng ứng dụng LLM đầu tiên của bạn
Vòng lặp cốt lõi chỉ gồm bốn bước: load một thư mục file bằng `SimpleDirectoryReader`, dựng `VectorStoreIndex` từ các document đó, biến index thành `query_engine`, rồi gọi `.query()` với một câu hỏi — ví dụ chính trong README chạy mặc định với OpenAI. Đổi `Settings.llm` sang `Ollama` và `Settings.embed_model` sang một embedding model của HuggingFace để chạy cùng pipeline đó với một model host tại local thay thế — đây chính là ví dụ thay thế README đưa ra. Mặc định một index chỉ tồn tại trong bộ nhớ; gọi `index.storage_context.persist()` để ghi nó ra `./storage` trên đĩa, rồi load lại sau này bằng `load_index_from_storage()` với một `StorageContext` được dựng lại, thay vì phải index lại toàn bộ document mỗi lần chạy.
Điểm mạnh
- ✓Quickstart trong README thực sự chỉ có năm dòng và chạy được ngay — `SimpleDirectoryReader` cộng `VectorStoreIndex` cộng `query_engine.query()` — không cần dựng thêm boilerplate để có câu trả lời đầu tiên.
- ✓Không bị khóa vào OpenAI: cùng đoạn code index đó chạy được với một model Ollama tự host kết hợp embedding model của HuggingFace, theo đúng ví dụ thay thế trong README.
- ✓Các API cấp thấp hơn để lộ riêng từng phần — data connector, index, retriever, query engine, reranking module — nên bạn không bị bó buộc vào cấu hình mặc định khi dự án lớn hơn nhu cầu ban đầu.
- ✓Giấy phép MIT, nên không phải lo vấn đề copyleft khi đóng gói nó vào sản phẩm thương mại.
- ✓Persist ra đĩa chỉ cần một dòng gọi (`index.storage_context.persist()`), nên bạn không bị buộc phải index lại cùng bộ document mỗi lần restart tiến trình.
Những điều cần cân nhắc trước khi dùng LlamaIndex
- △Chính README tự ghi chú rằng nó cập nhật chậm hơn phần documentation chính thức, nên coi đây là bản đồ sơ lược chứ không phải nguồn chính xác nhất cho API hiện tại.
- △Mô hình core cộng integration nghĩa là để chạy được, bạn cần chọn đúng tổ hợp package trong hơn 300 lựa chọn trên LlamaHub trước khi viết bất kỳ code ứng dụng nào — một bước quyết định thêm mà một script wrapper OpenAI một file không đòi hỏi bạn phải làm.
- △LlamaParse — phần xử lý OCR và parsing tài liệu nghiêm túc trong hệ sinh thái này — là một nền tảng riêng, cần đăng ký và API key riêng, không có sẵn chỉ bằng cách cài framework mã nguồn mở.
- △Index mặc định chỉ nằm trong bộ nhớ; việc persist ra đĩa là tùy chọn và phải làm thủ công (`persist()` / `load_index_from_storage()`), nên không có gì bền vững cho tới khi bạn tự thiết lập việc đó.
- △README có ghi một bước xác minh build-provenance cho thư mục `_static` đóng gói sẵn bên trong `llama-index-core` — đáng biết, vì đây không phải điều thường phải kiểm tra khi cài một package Python.
Các framework phát triển LLM khác
Câu hỏi thường gặp về LlamaIndex
LlamaParse là một nền tảng riêng, hướng tới doanh nghiệp, từ đội ngũ LlamaIndex, dùng cho agentic OCR, parsing tài liệu trên hơn 130 định dạng, trích xuất có cấu trúc và document agent. Bạn có thể dùng LlamaParse cùng framework mã nguồn mở LlamaIndex hoặc chạy độc lập.
Chạy `pip install llama-index` để có gói khởi đầu gồm core cộng một tập integration đóng gói sẵn, hoặc cài `llama-index-core` cộng từng integration package riêng từ LlamaHub nếu bạn muốn tự chọn LLM, embedding và vector store provider.
Metadata GitHub của LlamaIndex ghi Python là ngôn ngữ chính, và mọi ví dụ code trong README — cài đặt, index, query, persist — đều viết bằng Python. Việc hỗ trợ ngôn ngữ khác không được nêu rõ trong nguồn thông tin đang có.
LlamaIndex được phân phối theo giấy phép MIT, theo thông tin trên repository GitHub của dự án.
Có — ví dụ chính trong README thay OpenAI bằng Ollama chạy model Llama 3.1 local, kết hợp với một embedding model của HuggingFace, vẫn dùng chung đoạn code VectorStoreIndex.
LlamaIndex nhận đóng góp cho cả core lẫn các integration package, theo hướng dẫn trong CONTRIBUTING.md. Integration mới cần thực sự kết nối có ý nghĩa với các thành phần framework hiện có, và maintainer có quyền từ chối những integration không đáp ứng điều đó.
Trường hợp sử dụng tốt nhất
- •Hỏi-đáp trên knowledge base nội bộ — trỏ một data connector vào tài liệu, PDF hoặc bản export wiki của bạn rồi query qua LLM.
- •Tìm kiếm retrieval-augmented khi câu trả lời cần trích dẫn đúng một bảng SQL hoặc phản hồi API cụ thể thay vì dữ liệu huấn luyện của model.
- •Chuyển sang dùng LLM tự host thay vì OpenAI — ví dụ chính trong README chạy cùng một index với Ollama và model Llama 3.1 chạy local.
- •Pipeline trích xuất tài liệu nặng, nơi LlamaParse xử lý OCR và parsing trước khi framework index kết quả đầu ra.
- •Dựng nhanh prototype chatbot RAG bằng API cấp cao 5 dòng, sau đó chuyển xuống API retriever/query-engine cấp thấp hơn khi cần kiểm soát nhiều hơn.
Nên dùng — và nên bỏ qua
Hãy thử LlamaIndex nếu bạn đang xây dựng bất kỳ thứ gì cần LLM trả lời dựa trên một nguồn dữ liệu cụ thể — tài liệu nội bộ, một database SQL, một thư mục PDF — và muốn dùng sẵn data connector cùng cấu trúc index thay vì tự viết vòng lặp ingest-chunk-embed-retrieve. Nên bỏ qua nếu bạn chỉ đang làm một wrapper chat đơn giản quanh một LLM provider duy nhất, không có dữ liệu ngoài nào cần truy xuất — phần chi phí chọn package sẽ không mang lại gì trong trường hợp đó — hoặc nếu bạn cần OCR tài liệu vượt ngoài việc load file cơ bản, vì đó là phạm vi của LlamaParse, một sản phẩm riêng.