Z: Lớp tìm kiếm local-first kết nối con người và AI agents

Z (gọi tắt là zg, tên đầy đủ zvec-grep) là một công cụ tìm kiếm mã nguồn mở mới, được xây dựng với triết lý "local-first" — mọi thứ từ chỉ mục đến mô hình nhúng đều chạy ngay trên máy của bạn. Điểm đặc biệt của zg là khả năng hợp nhất ba phương pháp tìm kiếm khác nhau — chính xác (ripgrep), từ khóa (BM25) và ngữ nghĩa (vector) — vào một giao diện dòng lệnh thống nhất, phục vụ đồng thời cho cả người dùng cuối lẫn AI agents.

Dự án được giới thiệu trên Hacker News thu hút sự chú ý của cộng đồng lập trình viên nhờ cách tiếp cận thông minh: thay vì ép agent đọc toàn bộ mã nguồn, zg cung cấp các đoạn trích dẫn có xếp hạng mức độ liên quan và kèm vị trí nguồn rõ ràng. Điều này giúp giảm đáng kể số lần gọi công cụ, giảm lượng token tiêu thụ và quan trọng hơn — giảm nhiễu thông tin trong ngữ cảnh làm việc của agent.

Điểm đánh giá và trạng thái CI của dự án

Vì sao zg lại hữu ích?

Zg được thiết kế với năm lợi ích chính, đáp ứng cả nhu cầu của con người và máy móc:

• Sẵn sàng cho cả người và agent: Cài đặt một lần, đánh chỉ mục một lần, sau đó có thể dùng từ terminal hoặc để agent sử dụng trên macOS, Linux và Windows.
• Tìm kiếm vượt ra ngoài từ khóa: Khám phá dữ liệu theo ngữ nghĩa, xếp hạng theo độ liên quan, và xác minh lại bằng văn bản chính xác hoặc regex khi cần.
• Tìm kiếm đa định dạng: Hỗ trợ tìm kiếm trên mã nguồn, tài liệu và dữ liệu có cấu trúc trong khi vẫn giữ được cấu trúc và vị trí nguồn.
• Tốn ít công sức và ngữ cảnh hơn: Kết quả được xếp hạng, gắn nguồn rõ ràng, giúp bề mặt thông tin chính xác với ít cuộc gọi công cụ, ít token và ít nhiễu hơn.
• Local mặc định: Tệp, chỉ mục và mô hình cục bộ nằm trên máy của bạn; dữ liệu chỉ được gửi đến mô hình nhúng từ xa khi bạn cho phép.

Tìm kiếm liên ngành — từ truyện trinh thám đến kiến trúc mã nguồn

Để cho thấy sức mạnh của mình, zg được ra mắt với một "kệ sách" gồm cuốn Alice ở xứ sở thần tiên và The Memoirs of Sherlock Holmes. Sau khi đánh chỉ mục hai văn bản này bằng mô hình nhúng cục bộ potion-retrieval-32m, zg có thể trả lời các câu hỏi mang tính suy luận như: "Một sinh vật vô hình đã để lại vài dấu vết. Thám tử đã suy ra điều gì?"

Với human, gõ lệnh zg query --human "An unseen creature left a few marks..." — zg sẽ lập tức trả về các đoạn văn từ truyện Sherlock Holmes, được xếp hạng cao hơn hẳn so với các đoạn từ Alice.

Với agent, zg được tích hợp vào OpenCode. Điều thú vị là agent tự lựa chọn sử dụng zg mà không cần câu lệnh nào nhắc đến tên công cụ — chỉ với câu hỏi trên, OpenAI Codex đã gọi hàm zvec_grep_search của zg, tìm đến đúng tệp sherlock-holmes.txt và trả lời chi tiết về suy luận của Holmes trong The Adventure of the Crooked Man.

Demo tính năng zg tìm kiếm kho sách

Điểm mạnh được chứng minh qua benchmark thực tế

Zg không chỉ dừng lại ở việc chạy demo sách — dự án công bố kết quả benchmark bài bản trên các dự án mã nguồn mở mã nguồn lớn, hữu ích cho người Việt muốn đánh giá khả năng tìm kiếm trong codebase phức tạp:

• Pylint (Python): Tìm ra mẫu kiến trúc phân biệt khởi tạo thuộc tính có chú thích kiểu và không chú thích dựa trên cách xử lý nút AST.
• Matplotlib: Truy vết FontInfo và luồng dữ liệu qua nhiều giai đoạn render toán học, ghép chính xác dữ liệu và luồng điều khiển giữa các tệp.
• Django: Kết nối ràng buộc unique của username với ORM transaction và bulk operations của formset — một câu hỏi về thiết kế phân tán.

Các benchmark được thực hiện theo cặp A/B, giữ nguyên mọi biến số ngoài yếu tố zg. Zg hoạt động tốt nhất khi bằng chứng nằm rải rác trên nhiều tệp, nhiều mô-đun và vị trí đích không được xác định trước — đặc biệt hữu ích cho các câu hỏi về call-chain, luồng dữ liệu và kiến trúc.

Kiến trúc linh hoạt cho cả CLI, server và MCP

Zg được thiết kế để tích hợp nhiều chế độ sử dụng:

• Agent integrations: Hỗ trợ sẵn Codex, Claude Code, Qwen Code, Qoder, Cursor và OpenCode.
• CLI guide: Dùng cho tìm kiếm trực tiếp, đánh chỉ mục và quản lý không gian làm việc.
• MCP (Model Context Protocol): Cung cấp các công cụ cho agent với cơ chế bảo mật rõ ràng.
• Server và execution modes: Linh hoạt giữa lệnh một lần và server chạy nền.
• Nhiều mô hình nhúng: Lựa chọn mô hình phù hợp với tốc độ, chất lượng tìm kiếm, quyền riêng tư và cấu hình phần cứng.

Cách trải nghiệm zg ngay hôm nay

Để dùng thử zg, bạn chỉ cần máy cài Node.js 22 trở lên và chạy các lệnh sau:

# Cài đặt công cụ
npm install -g @zvec/zvec-grep

# Tạo thư mục làm việc và tải dữ liệu mẫu
mkdir zg-mystery && cd zg-mystery
curl --retry 3 --retry-all-errors --progress-bar -fL \
-o alice-in-wonderland.txt https://raw.githubusercontent.com/GITenberg/Alice-s-Adventures-in-Wonderland_11/master/11.txt \
-o sherlock-holmes.txt https://raw.githubusercontent.com/GITenberg/The-Memoirs-of-Sherlock-Holmes_834/master/834.txt

# Đánh chỉ mục bằng mô hình nhúng cục bộ
zg index --embedding local/potion-retrieval-32m

Nếu môi trường có OpenCode, cấu hình zg làm công cụ tìm kiếm cho agent:

zg install --target opencode --yes
opencode run --model opencode/nemotron-3-ultra-free \
"An unseen creature left a few marks. What did the detective infer? Cite local evidence."

Dự án zg là một ví dụ rõ ràng về xu hướng tương lai của tìm kiếm thông tin trong kỷ nguyên AI: thay vì tìm kiếm thô cứng by keyword, công cụ thế hệ mới sẽ hiểu ngữ nghĩa, xếp hạng theo liên quan và hoạt động liền mạch cho cả người dùng cuối lẫn các tác tử AI. Với triết lý local-first, zg cũng là một lựa chọn thú vị cho các đội ngũ phát triển và cá nhân quan tâm đến quyền riêng tư dữ liệu khi làm việc với dữ liệu nhạy cảm. Dự án phân phối theo giấy phép Apache 2.0 và hoan nghênh đóng góp từ cộng đồng.