Tencent WeKnora

1. WeKnora là gì?

WeKnora là một nền tảng mã nguồn mở của Tencent giúp biến một kho tài liệu (PDF, Word, Excel, ảnh, trang web…) thành một trợ lý hỏi đáp: bạn nạp tài liệu vào, rồi đặt câu hỏi bằng lời thường và nhận câu trả lời có kèm trích dẫn nguồn. Cách làm này thường gọi là RAG (tìm kiếm rồi để mô hình AI trả lời dựa trên tài liệu của bạn). Ngoài ra WeKnora còn có chế độ "tác nhân" (agent) làm việc nhiều bước và tự sinh một trang wiki từ tài liệu.

Nói thẳng để bạn khỏi mất thời gian: đây là công cụ dành cho lập trình viên và người quản trị hệ thống, không phải một ứng dụng bấm-là-chạy. Không có file cài .exe hay .dmg. Cách chạy chính thức là dùng Docker và dòng lệnh, và bạn cần tự cung cấp một mô hình AI (chạy cục bộ bằng Ollama, hoặc một khóa API của dịch vụ như OpenAI). Bản để bàn (desktop) có giao diện đang được nhắc tới nhưng chưa phát hành, phải tự dựng từ mã nguồn.

Hợp với bạn nếu:

• Bạn quen dùng dòng lệnh và Docker, muốn tự dựng một hệ thống hỏi đáp trên kho tài liệu của mình.
• Bạn cần dữ liệu ở lại trong hạ tầng của mình, không gửi lên dịch vụ bên ngoài.

Chưa hợp nếu:

• Bạn chỉ muốn một ứng dụng cài xong là dùng ngay trên điện thoại hay máy Windows.
• Bạn chưa từng dùng dòng lệnh và không muốn cài Docker.

2. Cần chuẩn bị gì?

• Máy tính chạy được Docker: Linux, macOS, hoặc Windows (trên Windows, Docker Desktop thường dùng WSL2, một lớp chạy Linux bên trong Windows). Tài liệu chính thức không liệt kê hệ điều hành được hỗ trợ; máy chủ thật thường dùng Linux.
• Cấu hình tối thiểu để thử: tài liệu ghi nên bắt đầu từ 4 nhân CPU và 8 GB RAM (bộ phân tích tài liệu khá tốn RAM), cộng thêm ổ đĩa tăng theo lượng tài liệu của bạn. Mức 8 GB chưa tính bản thân mô hình AI nếu bạn chạy cục bộ.
• Docker và Docker Compose v2: phần mềm để tải và chạy các thành phần của WeKnora. Tải tại https://www.docker.com/
• Git: công cụ tải mã nguồn về. Tải tại https://git-scm.com/
• Một mô hình AI (bắt buộc): cần ít nhất một mô hình trò chuyện và một mô hình vector (embedding). Có hai hướng:
  • Ollama (chạy AI ngay trên máy, miễn phí): tải tại https://ollama.com/
  • Hoặc một khóa API của dịch vụ tương thích OpenAI (như OpenAI, DeepSeek…). Cách này có thể mất tiền theo dịch vụ.

3. Cài đặt từng bước

Cách chuẩn là dùng Docker Compose. Toàn bộ làm trong cửa sổ dòng lệnh.

Bước 1: Tải mã nguồn về

git clone https://github.com/Tencent/WeKnora.git
cd WeKnora

Thấy gì là đúng: một thư mục tên WeKnora được tạo và bạn đang đứng trong đó.

Bước 2: Tạo file cấu hình

WeKnora đọc cấu hình từ một file tên .env. Sao chép file mẫu:

cp .env.example .env

Mở file .env bằng trình soạn thảo bất kỳ và điền các mục bắt buộc: tên và mật khẩu cơ sở dữ liệu (DB_USER, DB_PASSWORD, DB_NAME), mật khẩu Redis (REDIS_PASSWORD), cùng hai khóa bí mật JWT_SECRET và SYSTEM_AES_KEY. Hai khóa này để trống trong file mẫu và bạn phải tự tạo một lần rồi giữ lại. Trên Linux/macOS có thể sinh nhanh bằng:

openssl rand -hex 32

Dùng chuỗi kết quả cho JWT_SECRET. Với SYSTEM_AES_KEY cần đúng 32 byte, tạo bằng openssl rand -hex 16.

Lưu ý: Hãy lưu lại SYSTEM_AES_KEY. Nếu sau này bạn đổi khóa này, các thông tin đã mã hóa (như khóa API đã lưu) sẽ không giải mã được nữa.

Bước 3: Tải ảnh và khởi động

docker compose pull
docker compose up -d
docker compose ps

Lệnh cuối liệt kê các thành phần đang chạy. Chờ đến khi tất cả chuyển sang trạng thái "healthy" hoặc "running".

Thấy gì là đúng: danh sách các dịch vụ (frontend, app, postgres, redis…) ở trạng thái đang chạy.

Bước 4: Mở giao diện

Mở trình duyệt vào http://localhost. Lần đầu bạn sẽ thấy trang đăng nhập (hệ thống không có tài khoản mặc định); khi bản cài cho phép đăng ký công khai, trang có thêm thẻ đăng ký để bạn tự tạo tài khoản. Máy chủ backend nằm ở http://localhost:8080; bạn có thể kiểm tra nó sẵn sàng chưa bằng cách mở http://localhost:8080/health, thấy trả về {"status":"ok"} là đạt.

Bước 5 (tùy chọn): Bật thêm thành phần

WeKnora có các gói tính năng bật thêm khi cần, ví dụ đồ thị tri thức (Neo4j) hay lưu trữ đối tượng (MinIO):

docker compose --profile neo4j --profile minio pull
docker compose --profile neo4j --profile minio up -d

4. Dùng lần đầu

Sau khi đăng ký và đăng nhập, quy trình cơ bản là: tạo kho tri thức → chọn mô hình → nạp tài liệu → hỏi.

Bước 1: Tạo kho tri thức và chọn mô hình

Vào trang "Kho tri thức", tạo một kho mới. Một hộp thoại hướng dẫn sẽ yêu cầu chọn mô hình trò chuyện (LLM) và mô hình vector (Embedding). Nếu dùng Ollama chạy trên máy, địa chỉ để container gọi tới Ollama là http://host.docker.internal:11434. Bấm nút "Test" trong hộp thoại để chắc chắn kết nối mô hình thành công, rồi lưu.

Bước 2: Nạp tài liệu

Vào kho vừa tạo, kéo thả file hoặc dán đường dẫn trang web. Tài liệu được xử lý ở chế độ nền, trạng thái chạy lần lượt qua pending → processing → finalizing → completed. File scan hoặc file lớn sẽ lâu hơn.

Bước 3: Đặt câu hỏi

Vào trang trò chuyện, chọn kho tri thức rồi gõ câu hỏi. Hệ thống tìm các đoạn liên quan và sinh câu trả lời; bấm vào phần trích dẫn để xem đoạn gốc.

Thấy gì là đúng: câu trả lời hiển thị kèm các trích dẫn bấm mở được, nghĩa là chuỗi nạp tài liệu và hỏi đáp đã chạy thông.

5. Lỗi thường gặp và cách sửa

• docker: command not found hoặc lệnh docker không chạy. Nguyên nhân: chưa cài Docker hoặc Docker chưa khởi động. Cách sửa: cài Docker từ https://www.docker.com/ và mở Docker Desktop trước khi chạy lệnh.
• Compose báo lỗi vì thiếu file .env. Nguyên nhân: dịch vụ app đọc từ .env, nếu file không tồn tại sẽ lỗi. Cách sửa: chạy lại cp .env.example .env rồi điền các mục bắt buộc.
• Trang http://localhost không mở được hoặc lỗi kết nối. Nguyên nhân: các container chưa chạy xong hoặc cổng bị chiếm. Cách sửa: chạy docker compose ps xem đã "healthy" chưa; xem nhật ký bằng docker compose logs --tail=200 app.
• Đăng nhập trả về trang lỗi 404. Nguyên nhân đã ghi trong tài liệu: dịch vụ tìm kiếm SearXNG (nếu bật) đang dùng chung cổng 8080 với backend. Cách sửa: giữ SearXNG ở cổng khác (ví dụ 8888), đừng để trùng cổng của app.
• Tài liệu nạp vào mà cứ "đang xử lý" mãi. Nguyên nhân: bộ giải tài liệu hoặc mô hình vector chưa kết nối được. Cách sửa: kiểm tra kết nối mô hình trong phần cài đặt kho; xem log docker compose logs --tail=200 docreader.
• Đổi mô hình vector rồi kết quả tìm kém. Nguyên nhân: các vector cũ và mới không khớp nhau. Cách sửa: cần dựng lại chỉ mục (reindex) cho kho sau khi đổi mô hình embedding.

6. Gỡ cài đặt và cập nhật

• Dừng dịch vụ: trong thư mục WeKnora chạy docker compose down. Muốn xóa luôn cả dữ liệu, thêm -v (docker compose down -v) — thao tác này xóa hết dữ liệu, hãy cân nhắc.
• Cập nhật lên bản mới: đặt WEKNORA_VERSION trong .env thành phiên bản muốn dùng (hoặc để latest), rồi:

docker compose pull
docker compose up -d

Lưu ý: Trước khi lên bản mới, hãy đọc phần "upgrade notes" của phiên bản đó trên trang tài liệu chính thức, vì một số bản có thay đổi phá vỡ tương thích.

7. Câu hỏi hay gặp

• Có mất tiền không? Bản thân WeKnora miễn phí, mã nguồn mở (giấy phép MIT). Nhưng nếu bạn dùng mô hình AI qua khóa API trả phí thì phần đó tính tiền theo dịch vụ. Dùng Ollama chạy cục bộ thì không mất phí mô hình.
• Có cần mạng không? Cần mạng để tải mã nguồn và ảnh Docker lần đầu. Sau đó, nếu dùng mô hình cục bộ (Ollama), hệ thống có thể chạy trong mạng nội bộ.
• Dữ liệu có bị gửi đi đâu không? Nếu bạn tự dựng và dùng mô hình cục bộ thì dữ liệu ở lại trong hạ tầng của bạn. Nếu dùng khóa API bên ngoài, nội dung câu hỏi và tài liệu liên quan sẽ được gửi tới dịch vụ đó để tạo câu trả lời.
• Máy yếu có chạy được không? Tài liệu ghi nên bắt đầu từ khoảng 8 GB RAM. Nếu muốn nhẹ hơn, tài liệu chính thức có nhắc bản "Lite" chạy một tệp duy nhất với SQLite, phù hợp máy cấu hình thấp.
• Xem hướng dẫn chi tiết ở đâu? Trang tài liệu chính thức: https://weknora.weixin.qq.com/docs/ và kho mã nguồn https://github.com/Tencent/WeKnora. Bản mới nhất khi viết bài là v0.8.2 (24/9/2026).