Giới thiệu dự án
Adaptive-RAG chăm sóc khách hàng thương mại điện tử là một dự án chăm sóc khách hàng thông minh dành cho các câu hỏi chính sách có nhiều điều kiện, tập trung giải quyết các vấn đề như thiếu bằng chứng, câu trả lời không có căn cứ và các câu hỏi phức tạp không thể được truy xuất đầy đủ chỉ trong một lần. Backend được xây dựng bằng FastAPI và LangGraph, frontend sử dụng React. Hệ thống có thể dựa trên ý định của người dùng và độ phức tạp của câu hỏi để tự động lựa chọn giữa trả lời trực tiếp, truy xuất kiến thức, truy xuất bổ sung, thực thi công cụ, xác nhận thủ công và từ chối trả lời.
Dự án phù hợp cho việc trình diễn cục bộ, học quy trình Adaptive RAG và kiểm chứng kỹ thuật. Dự án hỗ trợ trích dẫn nguồn chính sách, truy vấn đơn hàng minh họa, thao tác chờ xác nhận, ghi nhớ phiên và phản hồi SSE, nhưng dữ liệu đơn hàng và logistics không phải dữ liệu nghiệp vụ thực tế.
API hiện trực tiếp chấp nhận
user_iddo client truyền vào nhưng chưa xác thực danh tính thực tế. Không triển khai trực tiếp dự án lên Internet công cộng khi chưa tích hợp xác thực danh tính đáng tin cậy, TLS và kiểm soát truy cập.
Cách hệ thống xử lý một yêu cầu
Sau khi người dùng gửi câu hỏi qua trang Web hoặc HTTP API, yêu cầu lần lượt đi qua lớp bảo vệ đầu vào, nhận diện ý định và định tuyến theo độ phức tạp. Hệ thống sau đó chọn nhánh xử lý phù hợp, cuối cùng tạo câu trả lời, kiểm tra độ trung thực, cập nhật bộ nhớ phiên và trả về các trích dẫn.
Người dùng → Web / HTTP API → Lớp bảo vệ đầu vào
→ Nhận diện ý định → Định tuyến độ phức tạp
├─ Trả lời trực tiếp
├─ Truy xuất → Xếp hạng lại → Truy xuất bổ sung nếu cần
├─ Lập kế hoạch → Thực thi công cụ / Xác nhận thủ công
└─ Từ chối trả lời
→ Tạo câu trả lời và kiểm tra độ trung thực → Bộ nhớ phiên → Câu trả lời và trích dẫnNhận diện ý định có thể sử dụng DeepSeek mặc định hoặc chuyển sang TypeSafe Jev. Lưu ý rằng Jev chỉ thay thế nút phân loại ý định; các nút LLM khác như đánh giá độ phức tạp, viết lại truy vấn, lập kế hoạch tác vụ, tạo câu trả lời, kiểm tra độ trung thực và tóm tắt bộ nhớ vẫn do DeepSeek đảm nhiệm.
Năng lực cốt lõi
- Định tuyến thích ứng: Kết hợp ý định nghiệp vụ và độ phức tạp của câu hỏi để chọn trả lời trực tiếp, truy xuất một lượt, truy xuất nhiều lượt, thực thi công cụ hoặc từ chối trả lời.
- Truy xuất kết hợp: Kết hợp triệu hồi BM25 và vector dày đặc, sử dụng RRF để hợp nhất kết quả và có thể bật xếp hạng lại bằng Cross-Encoder.
- Tăng cường bằng chứng: Hỗ trợ viết lại truy vấn, truy xuất bổ sung khi bằng chứng chưa đủ, kiểm tra độ trung thực của câu trả lời và tự sửa lỗi.
- Backend hai loại ý định: Mặc định sử dụng DeepSeek, đồng thời có thể nhận diện 14 loại ý định nghiệp vụ được định nghĩa trước thông qua giao diện choice có cấu trúc của Jev.
- Xử lý tài liệu: Hỗ trợ trực tiếp Markdown; sau khi cài đặt các dependency tùy chọn và công cụ hệ thống, có thể phân tích tài liệu PDF, Office và OCR.
- Chia đoạn có cấu trúc: Văn bản thông thường mặc định sử dụng cửa sổ 500 ký tự với phần chồng lấn 60 ký tự; bảng được nhận diện sẽ được tách thành các đoạn riêng, đồng thời giữ lại siêu dữ liệu như tiêu đề, chương và nguồn.
- Công cụ nghiệp vụ: Cung cấp các công cụ minh họa cho đơn hàng, bao gồm kiểm tra quyền hạn, cơ chế hạ cấp, xác nhận thủ công và tính bất biến; cũng có thể tích hợp các công cụ MCP.
- Năng lực kỹ thuật: Bao gồm nén bộ nhớ phiên, nhật ký có cấu trúc, chỉ số Prometheus, kiểm tra tình trạng và kiểm thử tự động.
Chuẩn bị môi trường chạy
Yêu cầu cơ bản
- Python 3.11 trở lên.
- Nếu cần chạy frontend Web, sử dụng Node.js 20.19+ hoặc 22.12+ và chuẩn bị npm.
- Chế độ cục bộ mặc định sử dụng SQLite và thành phần truy xuất trong bộ nhớ, không yêu cầu khởi động Docker trước.
Các bước cài đặt trên Windows PowerShell
Sau khi clone repository và chuyển vào thư mục gốc của dự án, hãy tạo môi trường ảo, cài đặt dependency phát triển, sao chép tệp cấu hình và tạo dữ liệu minh họa:
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
Copy-Item .env.example .env
.\.venv\Scripts\python.exe -m scripts.seed_demoNếu thư mục gốc dự án đã có .env, hãy giữ nguyên tệp đó và bỏ qua lệnh sao chép. Sau đó khởi động FastAPI:
.\.venv\Scripts\python.exe -m uvicorn app.asgi:app --reload --host 127.0.0.1 --port 8000macOS và Linux
Trên macOS hoặc Linux, bạn có thể tạo và kích hoạt môi trường ảo, sau đó thực hiện các lệnh cài đặt tương ứng:
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
python -m scripts.seed_demo
python -m uvicorn app.asgi:app --reload --host 127.0.0.1 --port 8000Cấu hình mô hình và dịch vụ cục bộ
Mở .env trong thư mục gốc của dự án. Các cấu hình sau cần được ưu tiên kiểm tra:
DEEPSEEK_API_KEY: Bật quy trình DeepSeek và phân loại ý định mặc định. Việc gọi API thực tế có thể phát sinh chi phí.INTENT_BACKEND: Có thể đặt thànhdeepseekmặc định hoặcjevtùy chọn.JEV_API_KEY: Cần thiết khi bật phân loại ý định bằng Jev.JEV_MODEL: Giá trị mặc định hiện tại của dự án làjev-1.13.0.DATABASE_URL: Mặc định sử dụngsqlite+aiosqlite:///./data/local/app.db.KNOWLEDGE_DIR: Giá trị mặc định làknowledge; các tài liệu kiến thức trong đó sẽ được nạp vào cơ sở dữ liệu khi khởi động.LOCAL_EMBEDDING_ENABLED: Kiểm soát chức năng vector ngữ nghĩa cục bộ.CROSS_ENCODER_ENABLED: Kiểm soát chức năng xếp hạng lại cục bộ.REDIS_URLvàQDRANT_URL: Cấu hình các dịch vụ bộ nhớ đệm và vector bên ngoài tùy chọn.
Nếu không cấu hình khóa DeepSeek, hệ thống vẫn có thể sử dụng logic trình diễn ngoại tuyến, nhưng chất lượng câu trả lời sẽ khác chế độ mô hình thực tế. Có thể xem toàn bộ biến trong Tài liệu tham khảo cấu hình và Tệp môi trường mẫu.
Khởi động giao diện trò chuyện React
Giữ tiến trình backend đang chạy và mở một terminal khác để chuyển vào thư mục frontend:
cd frontend
npm ci
npm run devTruy cập http://127.0.0.1:5173 để mở trang trò chuyện. Máy chủ phát triển sẽ chuyển tiếp các yêu cầu /api đến cổng 8000 trên máy cục bộ.
Frontend hỗ trợ trích dẫn nguồn, danh sách phiên cục bộ và thẻ xác nhận thao tác. Sau khi câu trả lời hoàn tất kiểm tra, backend sẽ gửi nội dung theo từng đoạn qua SSE. Nếu chạy npm run build để tạo frontend/dist, FastAPI sẽ cung cấp trang frontend từ đường dẫn gốc khi phát hiện thư mục này.
Sử dụng cơ bản: Tư vấn chính sách đổi trả
Trước tiên, hãy xác nhận trạng thái dịch vụ:
Dưới đây sử dụng PowerShell để gửi một câu hỏi chứa nhiều điều kiện chính sách đến giao diện trò chuyện:
$payload = @{
message = "Cốc giữ nhiệt đặt riêng đã quá bảy ngày nhưng có vấn đề về chất lượng, có thể trả lại không?"
user_id = "u_demo"
} | ConvertTo-Json
Invoke-RestMethod `
-Uri "http://127.0.0.1:8000/api/v1/chat" `
-Method Post `
-ContentType "application/json; charset=utf-8" `
-Body ([System.Text.Encoding]::UTF8.GetBytes($payload))Hệ thống trước tiên sẽ nhận diện ý định liên quan đến đổi trả, sau đó dựa trên độ phức tạp của câu hỏi để quyết định có truy xuất tài liệu chính sách hay không. Nếu bằng chứng ban đầu chưa đủ, quy trình có thể viết lại truy vấn và thực hiện truy xuất bổ sung; sau khi tạo câu trả lời, hệ thống cũng kiểm tra xem câu trả lời có trung thành với bằng chứng được truy xuất hay không và trả về các trích dẫn nguồn khả dụng.
Ngoài HTTP API, bạn cũng có thể chạy lệnh sau trong khi backend đang hoạt động để sử dụng client terminal:
python -m app.cliSử dụng cơ bản: Truy vấn và thao tác với đơn hàng minh họa
scripts.seed_demo sẽ tạo rõ ràng các đơn hàng minh họa. Việc khởi động API không tự động ghi các dữ liệu này, vì vậy không được bỏ qua bước khởi tạo dữ liệu trong lần chạy đầu tiên. Người dùng minh họa là u_demo, các đơn hàng khả dụng gồm:
ORD10001: Đã giao cho đơn vị vận chuyển, sản phẩm là tai nghe chống ồn.ORD10002: Đã ký nhận, sản phẩm là cốc giữ nhiệt đặt riêng.ORD10003: Đã thanh toán nhưng chưa giao, sản phẩm là áo phông.
Ví dụ, nhập Hủy đơn hàng ORD10003 trên trang trò chuyện. Khi thực hiện thao tác cần xác nhận, hệ thống có thể trả về pending_action. Yêu cầu xác nhận phải gửi lại session_id trong phản hồi và đặt pending_action.action_id vào confirm_action_id. Trang Web sẽ sử dụng thẻ xác nhận để hỗ trợ hoàn tất quy trình này.
Thao tác chờ xác nhận mặc định được lưu trong tiến trình máy chủ trong 15 phút. Sau khi dịch vụ khởi động lại hoặc yêu cầu được chuyển sang một tiến trình khác, có thể cần khởi tạo lại thao tác. Tham khảo Tài liệu tham khảo API để biết các trường và định dạng giao diện cụ thể.
Cấu hình nâng cao: Bật nhận diện ý định bằng Jev
Để chuyển nút phân loại ý định sang TypeSafe Jev, hãy thêm hoặc sửa các cấu hình sau trong .env cục bộ:
INTENT_BACKEND=jev
JEV_API_KEY=your_jev_api_key
JEV_ENDPOINT=https://api.typesafe.ai/v1/systemone
JEV_MODEL=jev-1.13.0
JEV_TIMEOUT_SECONDS=10
JEV_MAX_RETRIES=2
JEV_INTENT_APPLY_OVERLAY=true
DEEPSEEK_API_KEY=your_deepseek_api_keySau khi lưu, hãy khởi động lại backend. Jev được tích hợp thông qua giao diện HTTP và không cần cài đặt SDK chuyên dụng. Kết quả trả về sẽ được kiểm tra bằng Pydantic rồi chuyển đổi thành kết quả phân loại thống nhất.
Khi thiếu khóa Jev, yêu cầu thất bại hoặc phản hồi không hợp lệ, hệ thống sẽ quay về IntentClassifier hiện có. Chuỗi fallback ưu tiên sử dụng DeepSeek đã cấu hình; khi ngoại tuyến hoặc lời gọi mô hình thất bại, hệ thống tiếp tục sử dụng phân loại theo quy tắc. Các lỗi có thể thử lại sử dụng cơ chế backoff theo cấp số nhân, và trong triển khai hiện tại, JEV_MAX_RETRIES biểu thị số lần thử tối đa.
JEV_INTENT_APPLY_OVERLAY kiểm soát việc hiệu chỉnh theo quy tắc sau khi Jev phân loại thành công và mặc định được bật. Tùy chọn này không kiểm soát lớp phủ của bộ phân loại fallback. Để khôi phục phân loại ý định mặc định, chỉ cần đổi INTENT_BACKEND về deepseek.
Cấu hình nâng cao: tăng cường truy xuất và phân tích tài liệu
Cài đặt các dependency vector cục bộ và xếp hạng lại
.\.venv\Scripts\python.exe -m pip install -e ".[rerank]"Dependency rerank được dùng cho mô hình vector dense cục bộ và Cross-Encoder. Mô hình vector mặc định là BAAI/bge-small-zh-v1.5, mô hình xếp hạng lại mặc định là BAAI/bge-reranker-base. Khi tải lần đầu, hệ thống có thể tải trọng số mô hình; nếu mô hình không khả dụng, hệ thống sẽ chuyển sang chế độ dự phòng, vì vậy hiệu quả không thể tương đương với cấu hình đầy đủ.
Cài đặt dependency mở rộng để phân tích tài liệu
.\.venv\Scripts\python.exe -m pip install -e ".[docs]"Dependency docs được dùng cho trình phân tích tài liệu Unstructured. Khi xử lý tệp PDF, OCR và Office, bạn cũng có thể cần cài đặt Poppler, Tesseract cùng gói ngôn ngữ tiếng Trung và LibreOffice. Xem hướng dẫn phân tích và truy xuất để biết yêu cầu chi tiết.
ID của các đoạn tri thức được tạo dựa trên đường dẫn tài liệu và số thứ tự đoạn. Khi đường dẫn và kết quả phân đoạn không thay đổi, việc nạp lại có thể giữ nguyên ID; sau khi di chuyển tệp, chỉnh sửa nội dung hoặc thay đổi chiến lược chia đoạn, các tham chiếu lịch sử không được đảm bảo tiếp tục trỏ đến cùng nội dung.
Khởi động đầy đủ dịch vụ bằng Docker
Nếu muốn chạy đồng thời API, PostgreSQL, Redis, Qdrant và frontend Web đã build, trước tiên hãy chuẩn bị .env cục bộ, sau đó chạy:
docker compose up --buildSau khi khởi động, truy cập http://127.0.0.1:8000. Mật khẩu cơ sở dữ liệu và ánh xạ cổng trong Compose chỉ dành cho bản demo cục bộ. Trước khi triển khai công khai, bắt buộc thay thế mật khẩu demo, hạn chế các cổng cơ sở dữ liệu và bộ nhớ đệm, bật xác thực danh tính đáng tin cậy cùng TLS, đồng thời xây dựng phương án lưu trữ bền vững và vận hành đáng tin cậy.
Kiểm thử, kiểm tra tĩnh và đánh giá
Chạy kiểm thử backend và kiểm tra chất lượng tại thư mục gốc của dự án:
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check app eval tests
.\.venv\Scripts\python.exe -m mypy
.\.venv\Scripts\python.exe -m eval.runner --task retrievalCác lệnh kiểm thử và build frontend cần được thực thi trong thư mục frontend:
npm test
npm run buildCấu hình kiểm thử sẽ cô lập khóa mô hình cục bộ và sử dụng cơ sở dữ liệu kiểm thử. Trước khi thực hiện riêng đánh giá mô hình thực, hãy kiểm tra cấu hình mô hình và mạng, vì việc gọi mô hình bên ngoài có thể phát sinh chi phí.
So sánh phân loại ý định giữa Jev và DeepSeek
Sau khi cấu hình khóa cục bộ cho hai mô hình, có thể chạy so sánh trên cùng mẫu dữ liệu và cùng điều kiện lớp phủ:
.\.venv\Scripts\python.exe -m eval.compare_intent --backend both --limit 10 --no-overlay --output data/local/intent-comparison.jsonBáo cáo bao gồm độ chính xác, độ trễ P50 và P95, số lần chuyển sang chế độ dự phòng và số lần áp dụng quy tắc. --no-overlay sẽ tắt hiệu chỉnh quy tắc của cả hai bộ phân loại, giúp quan sát kết quả phân loại của riêng mô hình; xóa tham số này để so sánh hiệu quả sau khi thêm lớp phủ.
Tập dữ liệu ý định hiện tại thuộc bộ phát triển, độ chính xác bao gồm các mẫu chuyển sang chế độ dự phòng và không thể được xem trực tiếp là năng lực khái quát hóa của mô hình Jev độc lập. Các đánh giá trước đây cũng không có nghĩa phiên bản hiện tại đã được xác minh lại, càng không cấu thành bảo đảm về hiệu quả kinh doanh thực tế.
Khuyến nghị kỹ thuật thực tiễn
- Trước tiên xác minh quy trình ở chế độ cục bộ mặc định: SQLite và các thành phần truy xuất trong bộ nhớ đủ để hoàn thành bản demo cơ bản, không cần triển khai cơ sở dữ liệu bên ngoài và dịch vụ vector ngay từ đầu.
- Phân biệt mô hình ý định và mô hình quy trình: Chuyển sang Jev không thay thế các node DeepSeek khác. Nếu muốn chạy quy trình trực tuyến đầy đủ, vẫn cần cấu hình DeepSeek.
- Dùng các endpoint health để tìm lỗi:
/api/v1/healthdùng để kiểm tra tiến trình, còn/api/v1/readyphù hợp hơn để xác nhận các dependency đã sẵn sàng. - Thận trọng khi thay đổi chiến lược chia đoạn: Thay đổi đường dẫn, nội dung văn bản hoặc tham số chia đoạn đều có thể ảnh hưởng đến ID đoạn và các tham chiếu lịch sử.
- Không phụ thuộc vào trạng thái xác nhận trong tiến trình: Các thao tác chờ xác nhận mặc định chỉ có hiệu lực trong 15 phút và có thể bị mất do khởi động lại hoặc chuyển đổi giữa nhiều tiến trình.
- Bảo vệ dữ liệu nhạy cảm: Không đưa
.env, khóa thực, cơ sở dữ liệu cục bộ, nhật ký, tài liệu người dùng tải lên hoặc tài liệu riêng tư vào GitHub. - Kiểm tra việc truyền dữ liệu ra bên ngoài: Khi sử dụng mô hình bên ngoài hoặc MCP từ xa, cần xác nhận nội dung yêu cầu không chứa thông tin người dùng không được phép truyền ra ngoài.
- Lập kế hoạch cập nhật cơ sở tri thức: Hệ thống hiện tại sẽ nạp toàn bộ dữ liệu khi khởi động và chưa cung cấp quy trình xóa gia tăng hoàn chỉnh.
Tổng quan nhanh về thư mục dự án
app/api: API HTTP và SSE.app/agents: đồ thị thực thi LangGraph và các node quy trình.app/retrieval: phân tích, chia đoạn, truy hồi, hợp nhất và xếp hạng lại.app/providers: bộ điều hợp mô hình và dịch vụ vector.app/tools: công cụ nghiệp vụ, đăng ký công cụ và kiểm soát quyền.app/mcp: tích hợp công cụ MCP.app/memory: bộ nhớ phiên và nén.app/guardrails: kiểm tra đầu vào và câu trả lời.app/observability: nhật ký và chỉ số.frontend: giao diện trò chuyện React và TypeScript.knowledge: tài liệu tri thức chính sách.testsvàeval: kiểm thử tự động, dữ liệu đánh giá và trình thực thi.
Tóm tắt
Hệ thống trình diễn chăm sóc khách hàng thương mại điện tử Adaptive-RAG thể hiện một quy trình kỹ thuật tương đối hoàn chỉnh: trước tiên nhận diện ý định và đánh giá độ phức tạp, sau đó tùy nhu cầu kết hợp truy xuất hỗn hợp, bổ sung bằng chứng qua nhiều lượt, gọi công cụ, xác nhận thủ công và kiểm tra độ trung thực. Bạn có thể bắt đầu bằng SQLite, đơn hàng demo và logic ngoại tuyến để trải nghiệm nhanh, rồi từng bước bật DeepSeek, Jev, mô hình vector cục bộ, Cross-Encoder, tính năng phân tích tài liệu mở rộng và dịch vụ Docker.
Trước khi đưa vào nghiệp vụ thực tế, vẫn cần ưu tiên bổ sung xác thực danh tính, tích hợp hệ thống đơn hàng thực, lưu trữ bền vững trạng thái xác nhận, bảo trì gia tăng cơ sở tri thức, quản lý khóa và bảo mật mạng cấp production. Dự án sử dụng MIT License; xem thêm kiến trúc và quy trình vận hành, thiết kế truy xuất và giới hạn và lộ trình để biết chi tiết về kiến trúc và các hạn chế.