Hệ thống làm được gì
Tri thức của một dự án nằm rải trên wiki, issue và hàng trăm file đính kèm, viết bằng tiếng Việt, tiếng Anh và tiếng Nhật. Project Notebook gom chúng vào một kho tìm kiếm được và trả lời bằng lời thường, luôn kèm đường dẫn về tài liệu gốc để người hỏi tự kiểm chứng.
Hệ thống trả lời ba loại yêu cầu, và mỗi loại được xử lý bằng một cách riêng vì chúng hỏng theo những kiểu khác nhau.
Câu trả lời có citation
"Đơn hoàn tiền của khách hàng doanh nghiệp cần ai duyệt?" Hệ thống tìm trong tài liệu, đọc khi cần, và viết câu trả lời mà mỗi dữ kiện mang một citation. Phần tài liệu không nêu thì được nói rõ là không nêu.
Đếm và tính chính xác
"Còn bao nhiêu issue đang mở?" hay "Tổng số lỗi trong bảng đo là bao nhiêu?" Con số được lấy bằng một truy vấn trên Jira hoặc một phép tính trên bảng, không ước lượng từ vài đoạn văn.
Nghiên cứu một chủ đề
"Viết báo cáo về tình trạng tính năng X." Hệ thống lập dàn ý, tìm riêng cho từng mục, rồi viết một báo cáo có trích dẫn và danh sách những điều tài liệu chưa trả lời.
Confluence, Jira và file đính kèm
Page, blog post, issue, comment và file đính kèm: Excel, Word, PowerPoint, PDF, Markdown, text, CSV, ảnh và trang scan. Nội dung tự cập nhật mỗi 15 phút.
Web UI và MCP
Cả đội dùng trên trình duyệt. Kỹ sư dùng ngay trong code editor, qua AI coding agent. Hai kênh dùng chung một kho tri thức và một bộ tool.
Theo đúng quyền ở nguồn
Admin cấp quyền theo từng source. Trong mỗi source, page bị hạn chế trên Confluence và issue có security level trên Jira chỉ hiện với đúng những người được đọc chúng.
Kiến trúc
Hệ thống có hai luồng. Luồng nạp tài liệu đưa nội dung từ Confluence và Jira vào Knowledge Base và giữ cho nó luôn mới. Luồng hỏi đáp nhận câu hỏi, tìm đúng đoạn tài liệu mà người hỏi được phép đọc, rồi viết câu trả lời kèm citation.
Hệ thống chạy serverless trong AWS project của công ty, ở một Region. Tài liệu gốc vẫn nằm ở Confluence và Jira. Có một ngoại lệ có chủ đích: chat model được gọi qua Claude API, ngoài AWS project (Phần 11 và Phần 12).
Bản đồ kiến trúc
Chọn một luồng để xem dữ liệu đi qua những thành phần nào. Bấm vào từng thành phần để đọc vai trò của nó.
Vuốt ngang để xem hết bản đồ.
Phần tô xanh là Preparation step và text document: phần hệ thống xây thêm quanh dịch vụ managed.
Nạp tài liệu: giữ trọn nội dung của file đính kèm
Amazon Bedrock Managed Knowledge Bases tự parse và index tài liệu, nên không phải vận hành hạ tầng tìm kiếm. Đổi lại, parser của dịch vụ không có thiết lập nào để chỉnh.
Với file tiếng Việt, phép đo cho thấy parser chỉ giữ đúng khoảng một nửa số từ của pptx, docx, doc và pdf. Phần mất chủ yếu là các từ có dấu. Speaker notes của slide không được index.
Chat model thường vẫn đoán lại được dấu và trả lời đúng. Nhưng tên riêng và thuật ngữ chính xác thì không được khôi phục ổn định, và thông tin không có trong passage nào thì không thể trả lời.
Cùng một slide, ba cách nhìn
Hình minh hoạ, dựng theo tỷ lệ đo được trên file pptx thử nghiệm. Nội dung slide là ví dụ.
Preparation step trước Knowledge Base
Vì không chỉnh được parser, hệ thống đưa cho nó thứ mà nó đọc tốt. KB giữ 100% nội dung của file Markdown. Vậy với mỗi file đính kèm thuộc định dạng parser đọc kém, hệ thống tạo thêm một text document: nội dung của chính file đó, viết lại thành Markdown, đặt cạnh file gốc trong KB.
File gốc không bị thay thế. Text document mang cùng link với file gốc, nên citation trong câu trả lời vẫn mở đúng file trên Jira hoặc Confluence.
Đường đi của một file đính kèm
Năm bước, chạy tự động mỗi 15 phút. Bấm vào từng bước hoặc để hình tự chạy.
Chất lượng của khâu nạp tài liệu
Có hai phép đo. Phép thứ nhất so nội dung KB giữ được với nội dung thật của file. Phép thứ hai hỏi 38 câu, mỗi câu chỉ trả lời được từ một phần của một file: một sheet, một slide, một bảng, một đoạn speaker notes.
Nội dung Knowledge Base giữ được, theo định dạng file
Tỷ lệ từ của file có mặt đúng trong KB. Sáu định dạng đi qua Preparation step.
Xem dạng bảng
38 câu hỏi về file đính kèm
Mỗi chấm là một câu hỏi. Một câu đạt khi câu trả lời có đủ dữ kiện mong đợi và passage của đúng file được tìm thấy.
Các phương án đã cân nhắc
Cách làm trên được chọn sau khi đo nhiều phương án. Mỗi file được gửi vào KB dưới nhiều dạng khác nhau, rồi đo cùng một bộ chỉ số. Chuyển file sang PDF, cách thường được nghĩ đến đầu tiên, không cải thiện gì.
So sánh các dạng gửi vào Knowledge Base
Chọn một định dạng file. Thanh ngang là tỷ lệ từ KB giữ được.
Model đọc ảnh và trang scan
Ảnh và PDF scan không có text để trích, nên cần một vision model đọc. Thanh ngang là tỷ lệ từ có dấu tiếng Việt được đọc đúng. Các model đều chạy trong cùng Region.
Hai cách sử dụng: web UI và MCP
Cùng một kho tri thức được dùng theo hai cách. Web UI dành cho cả đội dự án: mở trình duyệt, hỏi bằng lời thường, đọc câu trả lời và kiểm chứng trên tài liệu gốc. MCP dành cho kỹ sư đang làm việc với một AI coding agent trong code editor: agent tự tra tài liệu dự án ngay trong lúc viết code, không phải chuyển cửa sổ.
Hai cách không phải hai hệ thống. Cả hai đi qua cùng một API, gọi cùng một bộ tool và chịu cùng một lớp phân quyền trên server. Điểm khác nhau là vòng tìm kiếm nhiều bước được điều khiển ở đâu.
Hai đường vào, một kho tri thức
Chọn một cách dùng để xem câu hỏi đi qua những đâu và ai điều khiển việc tìm kiếm.
Vuốt ngang để xem hết sơ đồ.
Ba giá trị chỉ web UI có
Qua MCP, người dùng nhận phần mà coding agent chọn kể lại. Web UI đưa thêm ba thứ mà một kênh chỉ có tool không có.
Kiểm chứng ngay tại chỗ
Bấm một citation để xem nguyên văn đoạn được trích, vị trí của nó trong toàn văn tài liệu, và tài liệu được sửa, được sync lần cuối khi nào. Mỗi bước tìm kiếm của model cũng hiện ra trong lúc chờ.
Tìm và đọc không cần hỏi
Search palette tìm thẳng trong kho tri thức. Reader hiện toàn văn một tài liệu như Knowledge Base đã đọc. Có thể giới hạn các câu hỏi vào đúng một tài liệu, và xem danh sách tài liệu vừa thay đổi.
Tri thức tích luỹ cho cả đội
Người dùng vote từng câu trả lời kèm lý do. Câu trả lời tốt vào library dùng chung và được admin xác nhận; chỉ người được đọc mọi source nó trích mới thấy. Trang KB quality cho admin biết tài liệu còn chưa trả lời được câu hỏi nào.
Ngược lại, MCP có điều web UI không có: coding agent kết hợp tài liệu dự án với source code đang mở, nên dữ kiện từ spec đi thẳng vào code, test và review.
Cách hệ thống trả lời một câu hỏi
Một chatbot tài liệu thông thường tìm một lần rồi trả lời từ những gì tìm được. Cách này hỏng khi dữ kiện nằm ở một tài liệu khác, được viết bằng từ khác, hoặc bằng ngôn ngữ khác với câu hỏi. Vì vậy web UI có bốn chế độ, từ nhanh đến kỹ, và người dùng chọn theo câu hỏi.
Fast
Một lần tìm trong mỗi Knowledge Base, rồi viết câu trả lời. Nhanh nhất; hợp với câu hỏi có đáp án nằm gọn trong một tài liệu.
Deep
Knowledge Base tự tách câu hỏi thành nhiều câu con và tìm cho từng câu. Hợp với câu hỏi rộng có nhiều ý.
Agent
Model tự tìm nhiều lần, đọc cả tài liệu, đếm và tính khi cần, và quyết định khi nào đủ. Hợp với câu hỏi cần ghép dữ kiện từ nhiều tài liệu.
Research
Lập dàn ý, nghiên cứu từng mục song song, rồi viết một báo cáo có trích dẫn. Chậm và tốn hơn một câu trả lời (Phần 8).
Chế độ Agent làm việc như một coding agent dùng MCP: model tự quyết định tìm gì, bằng từ nào, khi nào cần đọc cả một tài liệu và khi nào đã đủ để trả lời. Nó dùng chính bộ tool mà MCP đưa cho coding agent. Một câu đã trả lời ở chế độ khác có nút để hỏi lại ở chế độ Agent.
Một câu hỏi ở chế độ Agent
Sáu bước, từ câu hỏi đến lúc người dùng kiểm chứng. Bấm vào từng bước hoặc để hình tự chạy. Nội dung câu hỏi là ví dụ.
hoàn tiền khách hàng doanh nghiệp phê duyệt5 passage · có quy định phê duyệt, chưa có thời hạnhoàn tiền khách hàng doanh nghiệp phê duyệt5 passageenterprise customer refund deadline4 passage · không có gì mớithời hạn gửi yêu cầu hoàn tiền doanh nghiệpthấy trong speaker notes của một file pptxNhững gì tạo nên chất lượng
Câu trả lời tốt không đến từ riêng model. Nó là kết quả của tám điều cùng có mặt.
- Tìm nhiều lần, bằng nhiều cách nóiTài liệu dự án viết bằng tiếng Việt, tiếng Anh và tiếng Nhật. Model tìm lại bằng từ khác, bằng ngôn ngữ khác, bằng đúng mã hoặc tên riêng, và tìm riêng cho từng phần của câu hỏi.
- Đọc cả tài liệu khi cầnCâu hỏi về mọi bước của một quy trình hay toàn bộ một danh sách không trả lời được từ vài passage. Khi đó model đọc toàn văn tài liệu.
- Đếm bằng truy vấn, không bằng ước lượngSearch chỉ trả về những đoạn gần câu hỏi nhất, không phải tất cả. Câu hỏi "bao nhiêu" được trả lời bằng tool đếm và tính (Phần 7).
- Tìm thẳng vào dữ kiệnMột dữ kiện về tính năng thường được viết ở nơi khác: test plan, design note, release notes, issue. Trước khi kết luận là tài liệu không nêu, model phải tìm chính dữ kiện đó bằng lời khác.
- Chỉ nói điều tài liệu nóiMỗi dữ kiện mang citation về tài liệu gốc. Phần nào tài liệu không trả lời thì câu trả lời nói rõ là tài liệu không nêu, không đoán. Nội dung tài liệu được coi là thông tin, không phải mệnh lệnh cho model.
- Nội dung đã có đủ trong Knowledge BaseTìm giỏi đến đâu cũng không thấy thứ không được index. Preparation step (Phần 3) đưa speaker notes, chữ trong ảnh và text tiếng Việt của file Office vào KB.
- Cùng một bộ tool với MCPWeb UI và MCP chạy cùng một đoạn code cho search, đọc tài liệu, đếm và tính. Một cải tiến ở tool có ngay ở cả hai cách dùng, và hai cách cho kết quả so sánh được.
- Con người khép vòngNgười dùng kiểm chứng qua citation và vote kèm lý do. Câu hỏi mà tài liệu chưa trả lời được hiện trên trang KB quality, để đội dự án biết cần viết thêm gì.
Đếm và tính chính xác
Tìm kiếm theo nghĩa trả về vài đoạn văn gần câu hỏi nhất. Nó không trả về mọi issue, mọi dòng của một bảng hay mọi file của một page. Một trợ lý chỉ có search sẽ đếm trên những gì nó tình cờ thấy và đưa ra một con số trông hợp lý nhưng sai.
Vì vậy, bên cạnh các tool tìm và đọc, model có ba tool tính thay vì tìm. Con số trong câu trả lời do code tính ra trên dữ liệu đầy đủ; model chỉ chọn phép tính và diễn giải kết quả.
Đếm trên Jira
Chạy một truy vấn JQL trên Jira ngay lúc hỏi. Trả về tổng số chính xác, số đếm theo status, assignee, priority, loại, version hoặc label, và danh sách issue. Câu trả lời ghi rõ số liệu được đọc từ Jira vừa xong.
Tính trên bảng
Lọc, đếm, tổng, trung bình, nhỏ nhất, lớn nhất và nhóm theo cột, trên một bảng của một tài liệu: spreadsheet, file CSV, bảng trong page, trong Word hoặc PDF.
Liệt kê đầy đủ
Danh sách đầy đủ tài liệu của một source kèm tổng số chính xác, lọc được theo loại, theo tên và theo page hoặc issue mà file được đính kèm.
Ba phép thử trên dữ liệu thử nghiệm
Mỗi con số được so với nguồn: số Jira tự đếm, tổng tính tay trên file, và số file thật của page.
Research mode: báo cáo có trích dẫn
Một số yêu cầu không phải một câu hỏi mà là một đề bài: tổng hợp tình trạng của một tính năng, so sánh hai phương án, chuẩn bị tài liệu onboarding. Trả lời trong một lượt sẽ nông và thiếu.
Ở chế độ Research, hệ thống làm việc như một người viết báo cáo: lập dàn ý, nghiên cứu từng mục, rồi tổng hợp. Mỗi mục được một vòng tìm kiếm riêng viết, các mục chạy cùng lúc, và mọi citation trong báo cáo dùng chung một bộ số.
Một báo cáo ở chế độ Research
Năm bước trong một lần yêu cầu. Bấm vào từng bước hoặc để hình tự chạy. Nội dung báo cáo là ví dụ.
Chất lượng trả lời và chi phí
Thước đo được chọn là một coding agent dùng MCP: nó tự tìm nhiều lần cho đến khi đủ, và là cách dùng mà kỹ sư đánh giá cao nhất. Phép đo hỏi cùng 79 câu ở cả hai cách dùng, với cùng model và cùng bộ tool tìm và đọc.
Đo trên cùng model, cùng 79 câu hỏi
Claude Sonnet 5.5 ở cả hai cách dùng, cùng bộ tool tìm và đọc. Chọn một cách dùng để xem từng câu hỏi; mỗi chấm là một câu.
Xem dạng bảng
Chi phí model theo loại yêu cầu
Theo giá niêm yết của Claude Sonnet 5.5, đo trên dữ liệu thử nghiệm. Chưa gồm chi phí hạ tầng AWS.
| Loại yêu cầu | Cách xử lý | USD mỗi lần |
|---|---|---|
| Câu hỏi thông thường | Agent: tìm và đọc, trung bình 2,4 lần tra cứu | 0,03 |
| Câu hỏi tính trên bảng | Agent với query_table | 0,08 |
| Câu hỏi đếm trên Jira | Agent với query_jira | 0,10 |
| Báo cáo nghiên cứu | Research: 10–11 lần tra cứu | 0,21–0,26 |
Phân quyền: theo source, rồi theo từng page và issue
Hệ thống không đặt ra một bộ quyền riêng cho tài liệu. Nó áp dụng lại quyền mà đội dự án đã đặt ở Confluence và Jira, qua hai lớp kiểm tra nối tiếp nhau.
Lớp 1 là grant theo source: admin duyệt từng tài khoản và cấp từng source, tức một Confluence space hoặc một nhóm Jira project. Lớp 2 nằm bên trong source đã được cấp: một Confluence page có read restriction, các page con và file đính kèm của nó, cũng như một Jira issue có security level và file đính kèm của nó, chỉ hiện với những người mà restriction nêu tên.
Hai lớp kiểm tra trước khi nội dung tới người đọc
Mọi yêu cầu, từ web UI cũng như từ MCP, đi qua cả hai lớp trên server.
Vuốt ngang để xem hết sơ đồ.
Search, chế độ Agent và Research, danh sách tài liệu, reader, library dùng chung, các tool của MCP, và cả số đếm trên Jira.
Tài liệu bị ẩn không báo "bạn không có quyền". Nó không có trong kết quả, nên không lộ cả việc nó tồn tại.
Source chưa có bảng restriction thì không hiện gì. Khi không đọc được Confluence hoặc Jira, bảng cũ được giữ và admin nhận cảnh báo.
Admin của ứng dụng cũng được kiểm tra như mọi người. Người dùng được khớp với restriction bằng email.
Nguyên tắc thiết kế
Sáu lựa chọn sau giữ rủi ro về dữ liệu và vận hành ở mức thấp.
Thêm, không thay thế
File gốc vẫn ở trong KB. Text document chỉ bổ sung, nên kết quả không bao giờ kém hơn việc chỉ có file gốc, và phần chỉ file gốc mới có (ảnh nằm trong file) vẫn được giữ.
Citation mở file gốc
Text document mang link của file gốc. Người đọc kiểm chứng câu trả lời trên chính tài liệu họ quen, không phải trên một bản sao.
Chỉ đọc
Không có gì được ghi lên Confluence hay Jira. Một cách khác, đính kèm file Markdown ngược lên Confluence page, đã thử và chạy được nhưng không dùng vì nó sửa wiki của đội dự án.
Kho tri thức ở trong một Region
File, text document, Knowledge Base, search và vision model đều nằm trong AWS project của công ty, ở một Region, không có xử lý cross-Region. Ngoại lệ có chủ đích: để viết câu trả lời, câu hỏi và các passage liên quan được gửi tới Claude API.
Tự cập nhật, tự phục hồi
File đổi version thì text document được tạo lại. File bị gỡ thì text document bị xoá. Một file không xử lý được sau ba lần thử vẫn có trong KB như trước, kèm cảnh báo cho người vận hành.
Quyền lấy từ nguồn
Hệ thống áp dụng lại grant theo source và restriction của Confluence, Jira (Phần 10). Text document mang cùng link với file gốc nên chịu cùng quyền. Ai không được đọc file gốc thì không nhận được passage của cả hai, trên web cũng như qua MCP.
Giới hạn còn lại
Kết quả trên chứng minh cơ chế hoạt động. Những điểm sau cần được biết trước khi dùng với dữ liệu thật.
- Dữ liệu thử nghiệm nhỏ và giả lập23 file và 38 câu hỏi về file đính kèm, nội dung tiếng Việt tự tạo. Đủ để so sánh các phương án, chưa đủ để cam kết con số trên tài liệu thật của một dự án.
- Đọc restriction thật chưa được thửSite Atlassian thử nghiệm dùng gói Free, không có page restriction và không dùng được security level. Phần chặn đã được thử với một bảng restriction ghi tay; phần đọc restriction từ Confluence và Jira thì chưa. Phải chạy lại phép thử trên một site có hai tính năng này trước khi dùng thật.
- Điều kiện của phân quyền theo page và issueNgười dùng được khớp bằng email, nên tài khoản ứng dụng và tài khoản Atlassian phải cùng email; tài khoản ẩn email không được cấp quyền đọc. Một restriction mới mất tối đa 15 phút để có hiệu lực. Câu trả lời đã lưu trước khi có restriction vẫn giữ nội dung trong notebook của người đã hỏi.
- Một source đang cấu hình trùng spaceMột source được cấu hình trùng space với source khác, nên người được cấp source này đọc được nội dung của source kia. Đây là lỗi cấu hình, phải sửa trước khi có dữ liệu thật.
- Giới hạn của đếm và tínhquery_jira đọc tối đa 2.000 issue mỗi truy vấn và báo khi còn nhiều hơn. query_table chỉ tính trên bảng còn giữ được dạng bảng; bảng mà PDF hoặc trang scan trả về thành văn xuôi thì không tính được. list_documents hiện 300 tài liệu mỗi lần, kèm tổng số chính xác.
- Giới hạn của Research modeMột báo cáo chạy trong một request 300 giây; mục nào chưa viết xong khi hết giờ được thay bằng một dòng nói rõ điều đó. Báo cáo đầy đủ đến mức tài liệu tìm được cho phép. Chi phí mới được đo trên vài báo cáo.
- Số source trên mỗi Knowledge BaseMột KB có tối đa 5 data source. Mỗi Confluence source dùng 2 (connector và text document), nên khi thêm nhiều space sẽ cần thêm KB.
- File lớnFile trên 20 MB không đi qua Preparation step. Chúng vẫn ở trong KB, với chất lượng của parser.
- Chi phí hạ tầngPhần 9 chỉ nêu chi phí model của từng yêu cầu. Chi phí AWS của hệ thống và chi phí của Preparation step chưa được đo riêng. Vision model chỉ chạy cho ảnh và trang scan, một lần cho mỗi version của file.
- Câu hỏi và passage rời khỏi AWS projectChat model là Claude Sonnet 5.5 qua Claude API, nên câu hỏi và các passage liên quan được gửi ra ngoài Region để viết câu trả lời. Cần một quyết định về bảo mật dữ liệu trước khi dùng với tài liệu thật. Chế độ Fast và Deep đổi được về một model trong Region bằng một setting; chế độ Agent và Research thì không.
- Phép so sánh web UI và MCP79 câu hỏi, mỗi câu chạy một lần, và phía MCP chỉ đo với Claude Code. Phần chấm bằng tay do chính AI coding assistant đã xây hệ thống thực hiện, biết câu trả lời đến từ bên nào, nên không phải chấm mù. Trước khi hướng dẫn cho model được chỉnh một dòng, web UI đạt 76/79. Hai câu được sửa vẫn chưa ổn định: khi chạy lại mỗi câu ba lần, web UI đạt 3/3 và 1/3, Claude Code đạt 3/3 và 2/3. Chênh lệch một hai câu trên 79 nằm trong mức dao động đó.
- Nhật ký câu hỏiĐể có trang KB quality, câu hỏi được lưu 180 ngày, không kèm người hỏi, và admin đọc được; trang này cũng cho admin thấy tên các tài liệu được trích. Cần thông báo điều này cho người dùng trước khi dùng thật.