Sage / Knowledge infrastructure

Thiết kế & hướng dẫn vận hành

Nguồn tri thức chung cho công ty

Một nguồn tri thức.
Đúng quyền truy cập.

Importer đưa dữ liệu có nguồn gốc vào Cognee. BGE-M3 tạo vector nội bộ; LLM phân tích và tổng hợp. MCP đưa ngữ cảnh đến công cụ AI của từng bên, trong phạm vi được cấp.

Đang chạy: lõi Sage localCần bổ sung: importer & cổng teamTài liệu kiến trúc · không phải bảng trạng thái trực tiếp

Embedding

BGE-M3 / 1024

CPU · dense vector · nội bộ

Phân tích & tổng hợp

gpt-6.1-sol

Qua hub.smilesoftware.org

Lưu trữ

Postgres + graph

pgvector · Ladybug · file gốc

MCP hiện tại

Local / 1 danh tính

Chưa mở cho team hoặc đối tác

01 / SYSTEM MAP

Từ nguồn dữ liệu đến câu trả lời

Chọn chế độ để xem ranh giới hiện tại và kiến trúc khi cấp dịch vụ cho nhiều bên. Bấm từng thành phần để xem trách nhiệm.

Tải sơ đồ Draw.io

Đang chạy trên máy hiện tại

Đang chạy

Cognee API

Lõi đã chạy localPhần cần bổ sungMô hình / dịch vụ AIMũi tên: hướng gọi · phản hồi đi ngược chiều

Kiến trúc đích khi cấp MCP cho team

Đã xác minh

Lõi tri thức hoạt động

Nhập tài liệu tiếng Việt, trích xuất graph, tạo vector và truy xuất qua MCP đã chạy đầu-cuối. Dữ liệu và trọng số còn sau khi tạo lại container.

API 127.0.0.1:8000 · MCP 127.0.0.1:8001/mcp. PostgreSQL và Ollama không publish cổng ra host.

Thiết kế đích

Mỗi bên có phạm vi riêng

Importer giữ quyền tại nguồn. Cổng MCP xác thực người gọi và giới hạn tool. Backend Cognee dùng danh tính chỉ được đọc các dataset đã cấp.

Không cấp MCP local đang dùng admin cho cả công ty. Không coi nhãn dự án hoặc lời nhắc cho LLM là cơ chế bảo mật.

Embedding nội bộ không có nghĩa toàn bộ nội dung ở lại máy chủ.Cognee gửi nội dung cần trích xuất/tổng hợp tới LLM qua hub. Ngữ cảnh MCP trả về cũng có thể được AI client gửi tới nhà cung cấp model của bên sử dụng. Hai đường này phải nằm trong chính sách dữ liệu.

02 / INFRASTRUCTURE

CPU đủ để bắt đầu. GPU chưa bắt buộc.

Sage hiện dùng LLM từ hub nên không phải tự host model sinh văn bản. Tài nguyên nội bộ dành cho embedding, graph, PostgreSQL và hàng đợi import.

Máy đang chạy

4 CPU / ~10 GB RAM

Tài nguyên cấp cho Docker VM Colima; dùng để xác minh chức năng.

BGE-M3 đã nạp~1,22 GiB RAM

Trọng số BGE-M3~1,2 GB

Giới hạn embedding2 CPU · 4 GB

GPUKhông có

Số đo từ tài liệu giả lập nhỏ; chưa đo tải dữ liệu công ty.

Máy chủ nội bộ đề xuất

8 vCPU / 16 GB RAM

Mốc cấp phát ban đầu cho một máy chủ Sage dùng chung, cần theo dõi tải thực tế.

SSD ban đầu200 GB

Hệ điều hànhLinux + Docker

Truy cập teamHTTPS · SSO / VPN

BackupMáy / kho riêng

Không cam kết số người dùng hay tài liệu từ cấu hình này; tốc độ còn phụ thuộc hub, độ dài file và số job import.

Khi dữ liệu hoặc tải tăng

Tách embedding & worker

Mở rộng theo điểm nghẽn đã đo, giữ nguyên hợp đồng API.

RAM32 GB trở lên khi cần

EmbeddingHost riêng / thêm GPU

PostgreSQLSSD / IOPS riêng

Graph LadybugWorker ghi có điều phối

Không tăng replica Cognee tùy ý để cùng ghi file Ladybug trên volume chia sẻ. Cần kiểm tra mô hình khóa và hỗ trợ đa tiến trình trước khi mở rộng.

Cần chuẩn bị ngoài máy chủ

Tên miền nội bộ, chứng chỉ TLS và mạng riêng.
Google Workspace SSO qua OIDC cho web quản lý key; TLS và xác thực bearer key cho MCP.
Key hub dành riêng cho Sage, có budget và quyền model.
Kho backup mã hóa, tách khỏi máy chạy Sage.
Người quản trị dataset, quyền và chính sách lưu/xóa.

Lưu bền & phục hồi

Backup đồng bộ PostgreSQL, file graph, file gốc và cấu hình. Tạm dừng ghi hoặc tạo snapshot nhất quán để tránh graph và DB lệch phiên bản.

Trọng số/tokenizer tải lại được; file gốc và quyền truy cập phải phục hồi được. Secrets backup riêng bằng cơ chế quản lý khóa.

Khởi điểm vận hành đề xuất: backup hằng đêm, giữ bản hằng ngày 14 ngày và bản hằng tuần 8 tuần; điều chỉnh theo hợp đồng dữ liệu. Chỉ công bố RPO/RTO sau khi có lịch backup và đo phục hồi.

Volume Docker không thay thế backup.Đã kiểm tra dữ liệu qua recreate; chưa kiểm tra phục hồi từ backup trên máy mới.

03 / INGESTION CONTRACT

Tool import riêng, hợp đồng dữ liệu rõ ràng.

Importer của anh chịu trách nhiệm lấy dữ liệu, đồng bộ thay đổi và quyền. Cognee nhận nội dung đã được phép xử lý, lưu bản gốc, xây graph và chỉ mục.

Importer chưa được viết

Đọc nguồn

API, file, ticket, chat hoặc DB. Giữ ID ổn định và quyền gốc.

Chuẩn hóa

Text UTF-8; OCR nếu cần. Loại secrets, gắn nguồn và phiên bản.

Chọn dataset

Phân theo miền quyền. Chặn nguồn vượt chính sách LLM.

Ghi & lập chỉ mục

add rồi cognify. Job chỉ hoàn tất khi pipeline báo thành công.

Đồng bộ vòng đời

Cập nhật, thu hồi, xóa; kiểm tra lại quyền và trích dẫn.

Hướng đã chọn · chưa triển khai

Codex lấy Google Chat / Redmine theo lịch

Codex dùng in-app browser để đọc web và phân tích nội dung. Computer Use dùng khi cần giao diện ứng dụng; Chrome là lựa chọn khi cần phiên đăng nhập Chrome sẵn có. Một máy chạy agent có thể đọc nguồn qua VPN và gọi REST Cognee trên server riêng; không bắt buộc cài giao diện desktop trên máy Cognee Linux.

Lịch kích hoạt

Automation gọi quy trình có sẵn. Khóa theo nguồn để tránh hai lượt cùng sửa trạng thái.

Đọc phần thay đổi

Mở đúng space/dự án, phân trang và đọc thread/ticket đủ ngữ cảnh. Giữ mốc lần chạy thành công.

Lưu bằng chứng

Lưu text chuẩn hóa, URL, ID, tác giả, thời gian, phiên bản và checksum. Bản chụp màn hình chỉ bổ trợ.

Phân tích riêng

Codex tách sự kiện, quyết định, việc cần làm; gắn nguồn và phân biệt suy luận. Giữ nguyên bản nguồn để đối chiếu.

Import có kiểm soát

Writer kiểm tra schema/quyền rồi gọi add hoặc update và cognify. Chỉ hoàn tất khi kiểm tra được dữ liệu đã nhập.

Nguồn đầu tiên dự kiến
Nguồn	Đơn vị lưu	Phạm vi và đồng bộ
Google Chat	Một thread/chủ đề: space, thread ID hoặc khóa ổn định, người nói, thời gian, permalink, phản hồi và chỉnh sửa đã đọc được.	Chỉ space đã chọn; lịch sử có thể cần cuộn tải. Quyền xem của tài khoản thu thập không tự là quyền chia sẻ cho toàn công ty. Tệp đính kèm là nguồn riêng, chỉ tải và import khi đã được cho phép.
Redmine	Một issue: project, issue ID, tiêu đề, mô tả, trạng thái, assignee, journal và nguồn đính kèm được phép.	Chỉ project/issue/wiki đã chọn; giữ cờ private và miền quyền. Đồng bộ theo updated time và đối chiếu phiên bản; không suy quyền của toàn dự án từ một trang issue.

Ranh giới trách nhiệm

Browser reader: chỉ đọc, điều hướng, lọc và tải dữ liệu đã cấp; không gửi chat hay sửa ticket.
Vùng đệm: bản nguồn và kết quả phân tích tách riêng; khóa nguồn giữ ổn định qua các lần chạy.
Writer riêng: nhận nội dung đã xác thực, ánh xạ nguồn sang dataset UUID theo cấu hình; nội dung web/LLM không tự chọn quyền.
Manifest: lưu checksum, data_id, trạng thái pipeline và checkpoint; retry không tạo bản trùng khi kết quả API chưa rõ.
Theo dõi: ghi số trang/thread/issue đọc được, phần thiếu và lỗi. Chỉ cập nhật mốc thành công sau khi toàn phạm vi tương ứng hoàn tất.

Điều kiện chạy ổn định

Máy chạy agent phải online và app desktop đang chạy cho tác vụ dùng tài nguyên local; phiên web/VPN còn hiệu lực. Cần xác minh browser tools có trong lượt chạy theo lịch của môi trường thực tế.
Chọn browser cho từng nguồn. In-app browser có phiên riêng; không tự dùng cookie Chrome. Browser tích hợp không có sẵn trong Codex CLI.
Giới hạn số trang, khoảng thời gian, thời lượng và chi phí mỗi lượt. Không chạy hai Computer Use job trong cùng ứng dụng.
Hết phiên, gặp MFA/CAPTCHA hoặc giao diện đổi: dừng phần nguồn bị lỗi, báo cần xử lý; không import màn hình đăng nhập như tài liệu.
Không thấy tài liệu trong một lượt đọc không chứng minh đã xóa. Chỉ thu hồi/xóa khi có bằng chứng và chính sách được cấp; lỗi/phân trang thiếu không kích hoạt xóa hàng loạt.

Quyền nguồn và đường đi dữ liệu phải chốt trước khi chạy thật.Google Chat, private issue và dữ liệu nhạy cảm chỉ vào dataset đúng nhóm. Nếu không đọc được ACL gốc, dùng ánh xạ đã duyệt theo space/project hoặc giữ ngoài chỉ mục chia sẻ. Nội dung browser có thể được gửi tới model phục vụ Codex theo cấu hình tài khoản, ngoài đường Cognee gửi tới hub; cần cho phép cả hai đường. Kết quả phân tích giữ quyền hạn chế của các nguồn dùng để tạo nó.

Trạng thái: mới chốt loại nguồn Google Chat / Redmine và hướng browser importer. Chưa tạo automation, chưa đọc dữ liệu thật, chưa cấp key importer. Cần URL space/project, phạm vi nội dung và lịch theo giờ Việt Nam trước khi bật.

Tài liệu OpenAI: Browser · Scheduled tasks · Computer Use.

COGNEE 1.6.5 / MULTIPART

# Chạy trên máy Sage, dùng key tài khoản importer.
# Dataset phải được quản trị tạo và cấp quyền trước.
export SAGE_API=http://127.0.0.1:8000
# SAGE_IMPORT_KEY và DATASET_ID lấy từ secret/config.

curl --fail-with-body "$SAGE_API/api/v1/add" \
  -H "X-Api-Key: $SAGE_IMPORT_KEY" \
  -F "datasetId=$DATASET_ID" \
  -F 'data=@./quy-trinh.md;type=text/markdown' \
  -F 'labels=["procedure"]' \
  -F 'external_metadata=[{
    "source":"redmine",
    "source_id":"issue:1234",
    "source_uri":"https://redmine.example.org/issues/1234",
    "source_version":"2026-10-23T09:00:00+07:00",
    "classification":"L2",
    "owner_team":"engineering"
  }]' \
  -F 'run_in_background=false'

# Lưu data_id và dataset_id trong manifest của importer.
# Metadata classification chỉ mô tả; không tự cấp ACL.

Ví dụ cần thay ID, đường dẫn và key từ cấu hình riêng; không dán key vào HTML. Đã đối chiếu schema API đang chạy. Upload được xử lý nội bộ; không cần mở quyền đọc file tùy ý hoặc bật fetch URL trên Cognee.

COGNEE / COGNIFY & STATUS

# Sau khi add thành công: tạo graph, summary và vector.
# DATASET_ID là UUID, không phải tên dataset.
curl --fail-with-body "$SAGE_API/api/v1/cognify" \
  -H "X-Api-Key: $SAGE_IMPORT_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"datasetIds\":[\"$DATASET_ID\"],\"runInBackground\":true}"

# Theo dõi job nền bằng dataset/pipeline.
curl --fail-with-body --get \
  "$SAGE_API/api/v1/datasets/status" \
  -H "X-Api-Key: $SAGE_IMPORT_KEY" \
  --data-urlencode "dataset=$DATASET_ID" \
  --data-urlencode 'pipeline=cognify_pipeline'

# Chỉ đánh dấu searchable khi pipeline hoàn tất.
# HTTP 200 hoặc job được nhận chưa chứng minh đã lập chỉ mục.

Importer cần hàng đợi bền, retry có backoff cho lỗi tạm thời và khu vực giữ job lỗi. Với cấu hình CPU hiện tại, bắt đầu bằng một job cognify cùng lúc cho mỗi dataset; đo tải trước khi tăng.

COGNEE / DOCUMENT LIFECYCLE

# Giữ nguyên document ID khi nội dung nguồn thay đổi.
curl --fail-with-body -X PATCH \
  "$SAGE_API/api/v1/update?data_id=$DATA_ID&dataset_id=$DATASET_ID" \
  -H "X-Api-Key: $SAGE_IMPORT_KEY" \
  -F 'data=@./quy-trinh-moi.md;type=text/markdown'

# update có thể lập lại chỉ mục; kiểm tra status trong JSON.
# status=failed cần xử lý dù HTTP đã trả thành công.

# Khi nguồn bị xóa: gọi bằng danh tính có quyền delete.
# Thao tác này xóa tài liệu tương ứng; dùng đúng hai ID.
curl --fail-with-body -X DELETE \
  "$SAGE_API/api/v1/datasets/$DATASET_ID/data/$DATA_ID" \
  -H "X-Api-Key: $SAGE_DELETE_KEY"

# Không dùng DELETE /api/v1/datasets để đồng bộ một tài liệu.

Importer giữ lịch sử phiên bản/checksum trong manifest riêng. Nếu thay đổi phân loại hoặc ACL, không chỉ sửa metadata: thu hồi quyền cũ trước, di chuyển/lập lại phần tri thức cần thiết, xử lý cache và kiểm tra hết khả năng truy xuất cũ.

5 điều importer phải giữ

ID nguồn ổn định

Ánh xạ source + source_id sang dataset_id + data_id. Cùng nội dung từ hai tài liệu vẫn có thể có quyền khác nhau.

Phiên bản & checksum

Chỉ gửi phần thay đổi. Re-add không phải API cập nhật; dùng PATCH cho tài liệu đã tồn tại.

Quyền tại nguồn

Dataset không rộng quyền hơn tài liệu nguồn. Nguồn thay quyền phải kích hoạt đồng bộ quyền.

Trạng thái có thể tiếp tục

Ghi checkpoint, trạng thái add/cognify và lỗi. Không mất job khi worker khởi động lại.

Bằng chứng truy xuất được

Lưu URL/ID nguồn và thời điểm. Khi câu trả lời không đủ nguồn, báo thiếu dữ liệu; không tự lấp chỗ trống.

File PDF, bảng tính, chat, dữ liệu lớn: nhập thế nào?

PDF có text: thử loader trên mẫu đại diện; bản scan cần OCR trong tool import. Bảng tính/DB: chuyển thành tài liệu theo thực thể hoặc báo cáo có tên trường, đơn vị và khóa nguồn; tránh dump toàn DB thành một đoạn. Chat: gom theo thread/chủ đề, giữ người nói, thời gian và ACL của kênh.

Không phải định dạng nào cũng được bảo đảm đọc đúng. Kiểm tra bản text đầu ra trước khi cognify. Với dữ liệu lớn, chia lô và đặt giới hạn kích thước file, số trang, số token, timeout; không đẩy tất cả vào một job.

File gốc đang được Cognee giữ trong volume. Nếu cần lưu trữ lâu dài và nhiều phiên bản, bổ sung object storage/manifest do công ty quản lý; phần này chưa triển khai.

04 / GOOGLE SSO · SELF-SERVICE KEYS · MCP

Đăng nhập công ty. Tự tạo key đúng quyền.

Thiết kế đã chọn: Google Workspace xác thực từng người; quản trị Sage cấp nhóm và dataset. Mỗi người tự tạo key cho công cụ AI trong phạm vi được cấp, theo cách dùng quen thuộc của LiteLLM.

Demo local đã kiểm tra · SSO chưa bật

Phạm vi tài liệu: mô tả kiến trúc và web dự kiến.Các màn hình dưới đây là bản thiết kế HTML, không đăng nhập Google, không phát hành key và không gọi Cognee. Chưa cần cung cấp OAuth Client để xem kế hoạch.

Đã kiểm chứng local · dữ liệu giả lập

Demo đang nối Cognee và BGE-M3 thật

Tạo key theo phạm vi, truy vấn nguồn, chặn đọc chéo, thu hồi quyền và MCP chỉ đọc đã kiểm tra với hai dataset giả lập. 20 request, tối đa 4 đồng thời: không lỗi; trung vị 0,51 giây, p95 1,27 giây. Khởi động lại portal vẫn giữ session, key và grants.

Danh tính demo chọn trên banner; chưa dùng Google Workspace thật. Hai tài liệu nhỏ chưa chứng minh tải lớn hoặc vận hành lâu dài. Bản sản phẩm tại cổng 8088 vẫn dừng; harness demo chỉ bind loopback 8089.

Demo chỉ mở trên máy chạy Sage · Giới hạn demo local

Google Workspace

Người dùng đăng nhập tài khoản công ty. Sage xác minh ID token, tài khoản đã xác thực và domain được phép.

Danh tính Sage

Liên kết bằng Google subject ID. Người mới chưa có quyền dữ liệu; quản trị gán nhóm rõ ràng.

Web tạo key

Chọn tên công cụ, dataset được đọc và ngày hết hạn. Chỉ hiện key gốc một lần.

Gọi MCP / API

AI client gửi bearer key tới một URL chung. Gateway kiểm tra key, quyền hiện tại và giới hạn truy vấn.

Cognee trả ngữ cảnh

Danh tính backend chỉ đọc dataset được chọn. AI client nhận đoạn nguồn rồi tổng hợp câu trả lời.

Bản vẽ màn hình · không phải web đang chạy

Sage Access — web quản lý key dự kiến

01 / ĐĂNG NHẬP

Tài khoản công ty

Google Workspace

Đăng nhập bằng Google

Chỉ domain cho phép. Không có đăng ký mật khẩu riêng trong Sage. Admin đầu tiên cấu hình trước bằng email đã duyệt.

02 / KEY CỦA TÔI

Tạo key cá nhân

Tên: Codex máy làm việc
Dataset: Nội bộ + Dự án A đã được cấp
Hết hạn: chọn 7 / 30 / 90 ngày

[ Tạo key ] · [ Thu hồi ]

Danh sách chỉ hiện tiền tố, phạm vi, hạn dùng và lần dùng cuối. Không xem lại key gốc.

03 / QUẢN TRỊ

Người · nhóm · dataset

Gán thành viên vào nhóm; cấp hoặc thu hồi quyền đọc; khóa tài khoản; xem audit.

Lãnh đạo / Dự án A / Nhân viên

Vai trò quản trị cho phép quản lý chính sách. Quyền đọc nội dung vẫn phải cấp bằng grant.

Danh sách key minh họa trên web dự kiến
Key minh họa	Chủ sở hữu	Phạm vi đã chọn	Vòng đời
Codex · lãnh đạo	Người thuộc nhóm Lãnh đạo	Nội bộ + các dự án được cấp rõ ràng	Có hạn dùng; thu hồi riêng từng key
Codex · thành viên A	Người thuộc nhóm Dự án A	Chỉ Dự án A hoặc tập con được chọn	Gỡ khỏi nhóm A thì key mất quyền A ngay ở request tiếp theo

Quyền hiệu lực ở mỗi request

Phạm vi key ∩ quyền hiện tại của người dùng ∩ dataset đang được phép

Key không được tự chọn dataset ngoài grant. Khi thêm quyền mới cho người dùng, key cũ không tự mở rộng phạm vi; tạo key mới nếu cần.

Nhãn L0–L4 không tạo thang quyền tự động. “Lãnh đạo” chỉ đọc các dataset đã cấp; không mặc định đọc toàn công ty hoặc mọi dữ liệu nhạy cảm.

Hai loại key, hai trách nhiệm

Key Sage cá nhân: cấp cho AI client, gắn chủ sở hữu và tập dataset; lưu hash ở server, có hạn dùng và giới hạn request.

Key Cognee backend: giữ kín tại gateway, mã hóa khi lưu; một service account chỉ đọc đúng dataset đã ràng buộc, không admin, không write/delete/share.

Importer dùng danh tính ghi riêng. Không tái sử dụng key truy vấn để import, xóa hoặc phân quyền.

01 / AI CLIENTBearer key cá nhânURL chung dự kiến: https://sage.example.org/mcp/. Tên miền minh họa; chưa công bố.

02 / SAGE GATEWAYKiểm tra quyền phía serverKey còn hạn, user còn hoạt động, đúng dataset và tool; giới hạn tải, ghi audit không chứa nội dung.

03 / BACKEND IDENTITYService account hạn chếXác minh quyền trực tiếp và quyền kế thừa. Từ chối khi không xác minh được; không dùng key admin dự phòng.

04 / COGNEETruy xuất theo UUID datasetAdapter chỉ đọc trả ngữ cảnh nguồn. Tách session truy vấn; không mở tool nhớ/ghi/xóa upstream.

Ma trận phân quyền mẫu cần cấu hình
Nhóm ví dụ	Dataset được cấp	Quyền truy vấn	Giới hạn
Nhân viên chung	`company_internal` · L1	Read qua key cá nhân	Không tự đọc dataset dự án
Thành viên Dự án A	`project_a_internal` · L2; L1 nếu có grant riêng	Read trong scope key	Không đọc Dự án B
Lãnh đạo	L1 + từng dự án được duyệt	Read qua grant của nhóm	L3 cần miền cô lập và cấp riêng; không vượt quyền bằng chức danh
Đối tác A	`partner_a_release` đã biên tập	Read, có hạn và quota	Chưa mở đăng nhập ngoài Workspace; cần thiết kế danh tính đối tác riêng trước khi cấp
Importer	Chỉ dataset của nguồn được đồng bộ	Write; delete cấp riêng khi cần	REST nội bộ, không qua key MCP của người dùng

Hợp đồng MCP dự kiến

POST /mcp/ · Authorization: Bearer <SAGE_KEY>

Tool duy nhất: sage_search(query, dataset_ids?, top_k). Không truyền dataset thì tìm trong scope hiện tại của key; truyền ngoài scope thì từ chối.

Trả đoạn nguồn theo CHUNKS kèm dataset và thông tin nguồn có sẵn; AI client tổng hợp câu trả lời. Không mặc định gọi LLM tạo câu trả lời bên trong gateway. REST tương đương: POST /v1/search.

Client cần hỗ trợ Streamable HTTP và bearer header. Google SSO dành cho web tạo key; đây không phải luồng OAuth MCP tự đăng nhập trong mọi AI client.

Thu hồi và bảo vệ thông tin

Thu hồi key: chặn request mới dù key chưa hết hạn.
Gỡ nhóm hoặc khóa user: key cũ mất quyền theo chính sách hiện tại.
Kiểm tra lại quyền trước khi trả kết quả nếu quyền đổi lúc truy vấn.
Không log key gốc, câu hỏi hoặc toàn văn nguồn trong audit.
Dữ liệu đã gửi tới AI client không thể thu hồi từ xa; chỉ cấp client và model được duyệt.

Google Workspace xác thực danh tính; Sage quản lý quyền dữ liệu.Bản đầu dự kiến quản lý nhóm trong Sage, chưa đồng bộ Google Groups hoặc sự kiện nghỉ việc tự động. Khóa tài khoản trong Sage là bước thu hồi tức thời; cần tích hợp vòng đời Workspace trước khi vận hành rộng. Backend vẫn có thể ghi metadata/session vận hành khi tìm kiếm.

Lộ trình triển khai

Bốn phần việc có đầu ra rõ ràng

Bước	Việc cần làm	Điều kiện hoàn thành
1 · SSO & người dùng	Chốt domain, admin đầu tiên và URL HTTPS; tạo Google OAuth Client web, OIDC; tài khoản mới chưa có quyền.	Từ chối domain ngoài; không tự cấp admin; kiểm tra đăng nhập thật và hết phiên.
2 · Policy & key console	Dựng web cá nhân và quản trị; lưu user, nhóm, grants, hash key, expiry và audit trong DB riêng.	User chỉ tạo key trong scope được cấp; không xem/thu hồi key người khác; CSRF và thu hồi hoạt động.
3 · MCP gateway	Chỉ mở `sage_search`; ràng buộc UUID dataset với service account Cognee chỉ đọc; quota và kiểm tra quyền mỗi request.	Đọc chéo dự án và tool ghi/xóa đều bị chặn; không dùng backend admin; có kiểm chứng trên Cognee thật.
4 · Vận hành công ty	HTTPS, backup/restore, quản lý vòng đời Workspace, chính sách client/model; importer đi đường ghi riêng.	Phục hồi được dữ liệu và ACL; thu hồi user chặn truy cập; kiểm tra tải thực tế trước khi cấp rộng.

Hiện tại: lõi Sage local đã chạy. Phần SSO/key/team ở đây là kế hoạch; bản sản phẩm đang dừng, chưa kích hoạt OAuth và chưa cấp key cho công ty. Harness demo local dùng danh tính giả lập, hai dataset giả lập trên Cognee thật và key chỉ đọc riêng; xem bằng chứng ở trên.

MCP cũ tại 127.0.0.1:8001/mcp vẫn là danh tính admin local.Không dùng URL này làm endpoint chung của team. Gateway mới cần hoàn thành và kiểm chứng các điều kiện trên trước khi cấp truy cập.

05 / SECURITY BOUNDARIES

Chia tầng theo dữ liệu và quyền thực tế.

Phân loại quyết định dữ liệu được đưa vào đâu, ai được đọc và có được gửi tới LLM hay không. Nhãn phân loại phải được chuyển thành quyền backend và chính sách xử lý.

Tầng phân loại bảo mật đề xuất
Tầng	Ví dụ	Lưu ở đâu / ai đọc	LLM & MCP
L0 · Công khai	Tài liệu đã phát hành	Dataset public đã duyệt; endpoint công khai chỉ khi có nhu cầu	Được dùng model/client đã duyệt. Chống lạm dụng và đặt quota.
L1 · Nội bộ	Quy trình chung, hướng dẫn nhân viên	`company_internal`; nhân viên đã xác thực	Hub và AI client công ty đã chấp thuận; không cấp đối tác.
L2 · Dự án	Đặc tả, ticket, mã nguồn dự án	Dataset theo dự án/nhóm quyền; ACL giới hạn thành viên	Giới hạn endpoint, dataset UUID và session. Hub chỉ nhận nội dung theo chính sách.
L3 · Hạn chế	Nhân sự, tài chính, dữ liệu khách hàng nhạy cảm	Khuyến nghị stack/DB/graph/storage riêng cho miền nhạy cảm; nhóm được chỉ định	Chặn gửi hub/client bên ngoài mặc định. Chỉ mở theo phê duyệt dữ liệu cụ thể hoặc dùng LLM nội bộ.
L4 · Bí mật	Mật khẩu, private key, token, bí mật đặc biệt	Credentials vào secret manager, không đưa vào Sage. Tài liệu bí mật khác cần hệ thống cô lập riêng.	Không import mặc định. Chỉ xử lý khi có thiết kế cô lập, model và quy trình được duyệt.

Mạng & danh tính

Chỉ gateway phục vụ HTTPS; backend/DB/Ollama ở mạng riêng. Xác minh token, đúng audience, hết hạn và quyền nhóm. VPN không thay thế xác thực ứng dụng.

Quyền dữ liệu trước truy xuất

Chọn dataset được phép trên server trước khi vector/graph search. Không tìm toàn kho rồi nhờ LLM che bớt. node_set và metadata không thay ACL; per-dataset schema cũng không tự tạo tenant cách ly tuyệt đối.

Quyền của dữ liệu phát sinh

Chunk, summary, graph, câu trả lời cache và session giữ mức hạn chế của nguồn. Tổng hợp nhiều nguồn dùng phạm vi đọc là giao của quyền nguồn. Không nối graph hoặc cache giữa các bên có quyền khác nhau.

Model & công cụ AI nhận dữ liệu

Chặn egress theo tầng dữ liệu, không dựa vào prompt. Tài liệu import là dữ liệu không tin cậy; không cho chỉ dẫn trong tài liệu tự mở tool, cấp quyền hoặc gửi dữ liệu đi.

Khóa, audit, backup & thu hồi

Key riêng từng dịch vụ, mã hóa ổ đĩa/backup, luân chuyển khóa. Audit actor, dataset, tool, nguồn trả về và kết quả quyết định; tránh log toàn văn mặc định. Thu hồi quyền phải áp dụng cả cache, session và dữ liệu xuất.

Cấu trúc dataset nên bắt đầu

Dataset ví dụ	Miền quyền
`company_internal`	Nhân viên công ty
`project_a_internal`	Nhóm dự án A
`partner_a_release`	Bản đã biên tập, duyệt giao đối tác A
`hr_restricted`	Nhóm Nhân sự, stack nhạy cảm riêng

Một dataset phải có cùng ranh giới đọc. Nếu nguồn có ACL khác nhau, tách dataset/miền tương ứng hoặc xây kiểm soát mức tài liệu đã được chứng minh. Đối tác dùng bản phát hành riêng, không trỏ vào dataset nội bộ rồi lọc bằng từ khóa.

Trước khi mở endpoint cho bên khác

Xác minh danh tính và giới hạn tool ghi/xóa ở phía server.
Thử đọc chéo dự án, giả mạo dataset và gọi tool bị cấm; tất cả phải bị từ chối.
Thu hồi user/key rồi kiểm tra truy vấn mới, cache và session cũ.
Kiểm tra dữ liệu gửi tới hub và AI client có đúng tầng được phép.
Phục hồi backup trên máy mới; đối chiếu dữ liệu gốc, graph, vector và ACL.

Trạng thái hiện tại: chưa sẵn sàng mở trực tiếp MCP local cho công ty hoặc đối tác.Lõi tri thức đã chạy. Kế hoạch Google Workspace SSO, web tự tạo key và gateway chỉ đọc đã mô tả ở mục 04; chưa kích hoạt cho công ty. Cần hoàn thiện service account hạn chế, chính sách model theo tầng và kiểm chứng quyền trên dữ liệu thật.

Thứ tự triển khai tiếp theo

Chốt nhóm người dùng, owner dataset và loại dữ liệu được phép gửi hub.
Dựng server nội bộ, backup và tài khoản backend giới hạn quyền.
Viết importer theo hợp đồng ID / phiên bản / ACL / vòng đời ở trên.
Dựng Google Workspace SSO, web tự tạo key và MCP gateway dùng chung URL, phân quyền từng request.
Kiểm tra quyền chéo, thu hồi và phục hồi; sau đó mới cấp rộng hơn.

Một nguồn tri thức.Đúng quyền truy cập.

Từ nguồn dữ liệu đến câu trả lời

Cognee API

Kiến trúc đích khi cấp MCP cho team

Lõi tri thức hoạt động

Mỗi bên có phạm vi riêng

CPU đủ để bắt đầu. GPU chưa bắt buộc.

Cần chuẩn bị ngoài máy chủ

Lưu bền & phục hồi

Tool import riêng, hợp đồng dữ liệu rõ ràng.

Đọc nguồn

Chuẩn hóa

Chọn dataset

Ghi & lập chỉ mục

Đồng bộ vòng đời

Codex lấy Google Chat / Redmine theo lịch

Lịch kích hoạt

Đọc phần thay đổi

Lưu bằng chứng

Phân tích riêng

Import có kiểm soát

Ranh giới trách nhiệm

Điều kiện chạy ổn định

5 điều importer phải giữ

Đăng nhập công ty. Tự tạo key đúng quyền.

Demo đang nối Cognee và BGE-M3 thật

Google Workspace

Danh tính Sage

Web tạo key

Gọi MCP / API

Cognee trả ngữ cảnh

Sage Access — web quản lý key dự kiến

Tài khoản công ty

Tạo key cá nhân

Người · nhóm · dataset

Quyền hiệu lực ở mỗi request

Hai loại key, hai trách nhiệm

Hợp đồng MCP dự kiến

Thu hồi và bảo vệ thông tin

Bốn phần việc có đầu ra rõ ràng

Chia tầng theo dữ liệu và quyền thực tế.

Mạng & danh tính

Quyền dữ liệu trước truy xuất

Quyền của dữ liệu phát sinh

Model & công cụ AI nhận dữ liệu

Khóa, audit, backup & thu hồi

Cấu trúc dataset nên bắt đầu

Trước khi mở endpoint cho bên khác

Một nguồn tri thức.
Đúng quyền truy cập.