Kiến Trúc Tham Chiếu Microsoft Skills for Fabric cho Hệ Thống Conversational Analytics Agent

Bộ mã nguồn mở microsoft/skills-for-fabric không chỉ là tập hợp các hướng dẫn sử dụng Microsoft Fabric cho AI Coding Assistant. Dưới góc độ kỹ thuật hệ thống (Systems Engineering), đây là một kiến trúc tham chiếu (Reference Architecture) cấp độ Production của Microsoft về cách thiết kế, điều phối và kiểm soát một hệ thống Conversational Analytics & BI Agent.

Tài liệu này bóc tách toàn bộ cấu trúc, luồng điều phối (orchestration workflow) và các mẫu thiết kế (design patterns) quan trọng nhất từ microsoft/skills-for-fabric để đội ngũ phát triển (Dev & Data Analyst) tham khảo và áp dụng trực tiếp vào hệ thống Conversational Analytics Agent nội bộ.

1. Tại sao Đội Dev Conversational Analytics cần tham khảo Repo này?

Khi xây dựng một hệ thống Conversational Analytics Agent (hỏi đáp dữ liệu bằng ngôn ngữ tự nhiên qua Text-to-SQL hoặc Text-to-DAX), các đội phát triển thường gặp 5 điểm nghẽn kỹ thuật lớn:

1. Bùng nổ ngữ cảnh (Context Window Explosion): Nhồi toàn bộ schema của hàng trăm bảng, cột, measure và luật nghiệp vụ vào một System Prompt duy nhất làm giảm độ chính xác suy luận và tăng chi phí token/độ trễ.
2. Ảo giác giá trị lọc (Filter Value Hallucination): Agent tự đoán giá trị trong mệnh đề lọc (ví dụ viết WHERE Region = 'North America' trong khi dữ liệu thực tế lưu là 'NA' hoặc 'AMER'), dẫn đến kết quả trả về bằng 0 hoặc rỗng.
3. Lệch chuẩn số liệu giữa Chat và Dashboard (Metric & Filter Drift): Cùng một câu hỏi “Doanh thu quý này là bao nhiêu?”, Agent tính ra một con số khác với con số hiển thị trên Dashboard của Ban Giám đốc vì bỏ sót các bộ lọc ngầm định (Report/Page/Visual filters) hoặc tự viết công thức tính toán thay vì dùng Measure đã chuẩn hóa.
4. Lỗi logic khi sinh truy vấn phức tạp (Auto-Exist & Subtotal Truncation): Khi gom nhóm nhiều chiều (multi-dimension hierarchy), câu lệnh sinh ra bị sai dòng tổng (Grand Total) hoặc bị cắt mất dòng tổng quan trọng do vượt quá giới hạn dòng trả về (maxRows).
5. Rủi ro an toàn khi kết hợp Đọc và Ghi (Read/Write Mixing): Agent tự ý thay đổi cấu trúc mô hình hoặc xuất bản báo cáo khi người dùng mới chỉ yêu cầu lên phương án.

Trong microsoft/skills-for-fabric, Microsoft đã giải quyết triệt để cả 5 bài toán trên thông qua kiến trúc Hybrid 3-Tier (Agents - Skills - Common) kết hợp với MCP Orchestration Tools.

2. Kiến trúc tổng thể: Mô hình Hybrid 3-Tier và MCP Layer

Thay vì xây dựng một Agent nguyên khối (Monolithic Agent), Microsoft chia hệ thống thành 3 tầng văn bản điều hướng kết hợp với 1 tầng thực thi qua giao thức MCP (Model Context Protocol).

Cơ chế Progressive Disclosure (Tiết kiệm 70-80% Context Window)

Điểm đáng học hỏi nhất trong cách tổ chức thư mục của skills-for-fabric là không bao giờ nạp toàn bộ tài liệu hướng dẫn vào bộ nhớ cùng lúc.

Ví dụ với skill powerbi-report-cli (quản lý trọn vòng đời báo cáo Power BI với hơn 60 file tài liệu tham khảo chi tiết): - File skills/powerbi-report-cli/SKILL.md chỉ dài khoảng 250 dòng và tuyên bố rõ: “This skill is a mode dispatcher and intentionally contains no detailed procedures. Select the mode that matches the request, then read the matching mode reference end to end before acting.” - Khi người dùng yêu cầu thiết kế giao diện, Agent chỉ nạp references/design.md và references/design/chart-selection.md. - Khi người dùng yêu cầu sửa code JSON của biểu đồ, Agent mới nạp references/authoring.md và references/authoring/cartesian.md.

Bài học cho Đội Dev: Hãy tách System Prompt của Conversational Agent thành một Router/Dispatcher mỏng và một hệ thống Knowledge Base dạng mô-đun (có thể truy xuất qua Tool read_reference hoặc RAG theo chủ đề) thay vì ghép mọi luật SQL/DAX và mô tả bảng vào một prompt cố định.

3. Phân tích sâu FabricIQ: Luồng điều phối 9 bước cho Conversational BI Agent

Trong repo, agents/FabricIQ.agent.md và skills/fabriciq/SKILL.md là trái tim của hệ thống hỏi đáp dữ liệu tự nhiên trên Power BI và Semantic Model. Hệ thống này sử dụng một MCP Server duy nhất (https://fabriciq.svc.cloud.microsoft/v1/mcp/fabriciq) với đúng 6 công cụ (MCP Tools) được thiết kế cực kỳ chặt chẽ:

Quy trình 9 bước thực thi chuẩn (9-Step Execution Pipeline)

Khi nhận một câu hỏi từ người dùng (ví dụ: “Top 5 sản phẩm có doanh thu cao nhất của khách hàng Terra Firma trong kịch bản ngân sách là gì?”), FabricIQ bắt buộc Agent tuân thủ nghiêm ngặt trình tự 9 bước sau:

1. Bước 1 - Định danh tài nguyên (Artifact Identification):
2. Nếu có URL hoặc GUID: Gọi ResolveFabricItem.
3. Nếu chỉ có tên hoặc từ khóa: Gọi DiscoverArtifacts. Lưu ý tách biệt rõ reportObjectId (ID của báo cáo) và artifactId (ID của Semantic Model nằm bên dưới báo cáo đó).
4. Bước 2 - Đọc ngữ cảnh báo cáo (Report Metadata Inspection):
5. Gọi GetReportMetadata (lần đầu không truyền tham số queries để lấy toàn cảnh).
6. Trích xuất semanticModel ID, danh sách các Visual liên quan đến câu hỏi, các Measure đang được Visual đó sử dụng và toàn bộ bộ lọc đang áp dụng trên Report, Page và Visual.
7. Bước 3 - Phân tích Schema và Luật nghiệp vụ (Schema & Rules Analysis):
8. Gọi GetSemanticModelSchema với ID của Semantic Model.
9. Đọc toàn bộ VerifiedAnswers (câu trả lời đã xác thực) và CustomInstructions (hướng dẫn nghiệp vụ của chủ sở hữu mô hình).
10. Bước 4 - Đối sánh Câu trả lời đã xác thực (Verified Answers Matching - Bắt buộc):
11. Quét toàn bộ danh sách VerifiedAnswers xem có mục nào khớp về mặt ngữ nghĩa với câu hỏi của người dùng không (kể cả khi dùng từ đồng nghĩa). Nếu khớp, bắt buộc dùng nguyên bản thiết kế (Bindings + Filters) của Verified Answer đó, không tự ý sáng tạo câu truy vấn mới.
12. Bước 5 - Neo giá trị thực thể (Entity Value Grounding qua ValueSearch):
13. Với câu hỏi có chứa tên riêng như "Terra Firma" và "Budget", Agent gọi ValueSearch(artifactId, searchTerms=["Terra Firma", "Budget"]) để biết chính xác giá trị này nằm ở bảng nào, cột nào và cách viết hoa/thường chuẩn trong cơ sở dữ liệu là gì.
14. Bước 6 - Sinh mã truy vấn theo khuôn mẫu (Constrained Query Generation):
15. Viết câu lệnh DAX dựa trên các Measure có sẵn trong mô hình (ưu tiên Measure đang gắn trên Visual của báo cáo), kết hợp bộ lọc từ Bước 2, luật từ Bước 3/4 và giá trị chuẩn từ Bước 5.
16. Bước 7 - Thực thi song song (Parallel Query Execution):
17. Gọi ExecuteQuery (hỗ trợ chạy song song tối đa 4 câu lệnh EVALUATE trong 1 request để giảm độ trễ mạng).
18. Bước 8 - Kiểm chứng và Tự sửa lỗi (Verification & Error Recovery):
19. Nếu kết quả trả về BLANK hoặc rỗng bất thường: Kiểm tra lại xem có đang lọc vào một ngày không có dữ liệu không (re-anchor về ngày gần nhất có dữ liệu bằng LASTNONBLANK), kiểm tra lại bộ lọc của Report, sửa DAX và thử lại tối đa 1 lần (max 1 retry).
20. Bước 9 - Tổng hợp câu trả lời hướng người dùng (Business-First Synthesis):
21. Trình bày kết quả ngắn gọn, đưa con số quan trọng lên đầu (in đậm), dùng bảng văn bản rõ ràng. Tuyệt đối không nhắc đến tên hàm DAX, tên bảng kỹ thuật hay tên MCP tool trong câu trả lời cho người dùng cuối.

4. Bảy Mẫu Thiết Kế (Design Patterns) Đắt Giá Nhất Cho Đội Dev

Dưới đây là 7 kỹ thuật cốt lõi được rút trích từ mã nguồn của skills-for-fabric mà đội phát triển Conversational Analytics có thể áp dụng ngay vào kiến trúc Agent của mình (dù backend của bạn dùng Power BI DAX, Fabric Warehouse T-SQL, BigQuery, Snowflake hay Postgres).

Pattern 1: Tháp ưu tiên nguồn chân lý (4-Level Hierarchy of Truth)

Một lỗi phổ biến của các Text-to-SQL / Text-to-DAX Agent là luôn cố gắng tự viết câu lệnh tính toán từ các bảng và cột thô (Raw Schema). FabricIQ định nghĩa một tháp ưu tiên 4 tầng rõ ràng:

Pattern 2: Kế thừa bộ lọc 3 cấp và Cơ chế công khai ghi đè (Filter Inheritance & Override Disclosure)

Tại sao người dùng hỏi Agent lại nhận được con số khác trên Dashboard? Vì trên Dashboard có các bộ lọc ngầm định ở cấp Báo cáo (Report filter), cấp Trang (Page filter) hoặc cấp Biểu đồ (Visual filter) - ví dụ: Status <> 'Cancelled' hoặc Scenario IN ('Actual', 'Forecast').

Quy tắc của Microsoft trong skills/fabriciq/SKILL.md: - Mặc định kế thừa toàn bộ: Khi truy vấn dữ liệu dựa trên một Visual trong báo cáo, Agent bắt buộc đưa toàn bộ Report Filters + Page Filters + Target Visual Filters vào câu lệnh truy vấn. - Cấm “mượn” bộ lọc chéo (No Cross-Visual Filter Borrowing): Không bao giờ lấy bộ lọc của một biểu đồ khác trên cùng trang để áp vào biểu đồ đang xét, ngay cả khi bộ lọc đó trông giống như quy tắc làm sạch dữ liệu chung. - Xử lý bảng ẩn bằng TREATAS: Nhiều khi bộ lọc cấp báo cáo tham chiếu đến một bảng cấu hình bị ẩn khỏi Schema. Agent không được bỏ qua bộ lọc này mà phải áp dụng bằng hàm TREATAS({"Actual", "Forecast"}, 'Budget'[Scenario]). - Ghi đè có công khai (Explicit Override Disclosure): Nếu báo cáo đang lọc cố định Year = 2025, nhưng người dùng hỏi “Doanh thu năm 2026 là bao nhiêu?”, Agent chỉ ghi đè đúng bộ lọc Year, giữ nguyên mọi bộ lọc khác, và bắt buộc ghi rõ trong câu trả lời (ví dụ: “Lưu ý: Kết quả này đã chuyển bộ lọc năm từ 2025 (mặc định của báo cáo) sang 2026 theo yêu cầu của bạn”).

Pattern 3: Xử lý Schema khổng lồ bằng JMESPath Projection (Two-Phase Metadata Retrieval)

Khi một Semantic Model có hàng trăm bảng và hàng nghìn measure, kết quả trả về từ GetSemanticModelSchema hoặc GetReportMetadata sẽ vượt giới hạn token và bị cắt bớt (truncated).

Microsoft giải quyết bằng cơ chế Truy xuất 2 pha tích hợp JMESPath ngay trên MCP Server: 1. Pha 1: Gọi GetSemanticModelSchema(artifactId) không kèm tham số lọc. Nếu mô hình nhỏ, nhận toàn bộ schema trong 1 lần gọi. 2. Pha 2 (Nếu kết quả Pha 1 bị cắt bớt): MCP tool hỗ trợ tham số queries nhận mảng các biểu thức JMESPath để lọc dữ liệu ngay phía server trước khi trả về cho LLM. Thứ tự ưu tiên lấy bổ sung bắt buộc: - Ưu tiên 1: Lấy toàn bộ danh sách câu hỏi xác thực: queries=["schema.VerifiedAnswers[].{Title: Title, Question: Question}"] - Ưu tiên 2: Lấy toàn bộ hướng dẫn nghiệp vụ: queries=["schema.CustomInstructions"] - Ưu tiên 3: Tìm kiếm measure và bảng theo từ khóa liên quan đến câu hỏi: queries=["schema.Tables[].Measures[?regex_match(to_string(@), 'revenue|sales')].{Name: Name, Expression: Expression} | []"]

Bài học cho Đội Dev: Khi thiết kế MCP Tool trả về Schema hoặc Metadata lớn cho Agent, hãy tích hợp sẵn bộ lọc JMESPath hoặc JSONPath vào tham số đầu vào của Tool. Điều này giúp Agent tự truy vấn sâu (drill-down) vào đúng nhánh JSON cần thiết mà không làm tràn bộ nhớ.

Pattern 4: Truy vấn kép song song cho dữ liệu phân cấp (Parallel Dual-Query chống mất dòng tổng)

Khi người dùng yêu cầu phân tích theo cấu trúc phân cấp từ 3 chiều trở lên (ví dụ: Khu vực -> Quốc gia -> Tỉnh thành -> Nhóm sản phẩm) hoặc các chiều có số lượng giá trị lớn (high-cardinality), câu lệnh tạo dòng tổng phụ (ROLLUPADDISSUBTOTAL trong DAX hoặc GROUP BY ROLLUP trong SQL) có thể sinh ra hàng chục nghìn dòng. Khi bị cắt ở giới hạn maxRows = 250 hoặc 1000, các dòng Tổng (Subtotals / Grand Total) rất dễ bị cắt mất, khiến Agent báo cáo sai tổng số.

Giải pháp trong skills/fabriciq/SKILL.md: - Agent phải gửi 2 câu truy vấn chạy song song trong cùng một lệnh ExecuteQuery: 1. Summary Query (Truy vấn tổng hợp đỉnh): Chỉ gom nhóm theo 1-2 chiều cao nhất (không dùng rollup chi tiết) kèm toàn bộ các Measure. Kết quả cực gọn, đảm bảo 100% không bao giờ bị cắt dòng và luôn có con số tổng chính xác tuyệt đối. 2. Detail Query (Truy vấn chi tiết có Rollup): Gom nhóm toàn bộ các chiều với ROLLUPADDISSUBTOTAL, nhưng bắt buộc sắp xếp (ORDER BY) theo các cột cờ Subtotal giảm dần trước (IsLevel1Subtotal DESC, IsLevel2Subtotal DESC), sau đó mới sắp xếp theo giá trị Measure giảm dần. Nhờ vậy, toàn bộ các dòng tổng cấp cao luôn nằm ở đầu bảng kết quả và sống sót qua mọi giới hạn cắt dòng (maxRows).

Pattern 5: Kỷ luật sinh mã DAX/SQL (Chống lỗi Auto-Exist và Time Intelligence Trap)

Để ngăn LLM viết ra những câu lệnh chạy được nhưng sai số liệu, skills/fabriciq/SKILL.md đặt ra bộ luật cú pháp cực kỳ nghiêm ngặt:

• Chống bẫy Auto-Exist khi lọc nhiều cột:
• Cấm tuyệt đối: Gộp nhiều điều kiện lọc vào chung một hàm FILTER('Table', 'Table'[Col1] = "A" && 'Table'[Col2] = "B"). Trong DAX, cách viết này kích hoạt cơ chế auto-exist làm sai lệch dòng Grand Total.
• Bắt buộc: Tách mỗi điều kiện lọc thành một đối số độc lập bên trong SUMMARIZECOLUMNS. Với điều kiện bằng/IN (=, IN), dùng TREATAS({"A"}, 'Table'[Col1]). Với các điều kiện khác (<>, >, IS NOT NULL), dùng KEEPFILTERS(FILTER(ALL('Table'[Col1]), ...)).
• Chống bẫy ngày tương lai trong Time Intelligence:
• Cấm tuyệt đối: Dùng MAX('Calendar'[Date]) để xác định “ngày hiện tại” vì bảng Calendar thường được tạo sẵn đến hết năm 2030.
• Bắt buộc: Dùng LASTNONBLANK hoặc lọc những ngày có phát sinh dữ liệu ([Measure] <> BLANK()) trước khi lấy mốc thời gian mới nhất.
• Xử lý Report-Level Measures:
• Nhiều Measure được DA tạo trực tiếp trên file báo cáo Power BI chứ không nằm trong Semantic Model. Nếu gọi tên Measure đó trong câu lệnh DAX gửi xuống Semantic Model sẽ bị lỗi không tìm thấy.
• Giải pháp: Đọc biểu thức của Measure đó từ GetReportMetadata, sau đó định nghĩa lại trực tiếp (inline) ở đầu câu truy vấn bằng cú pháp DEFINE MEASURE 'HostTable'[MeasureName] = <biểu thức>.

Pattern 6: Chuẩn bị mô hình cho AI (Semantic Model AI Readiness & OneLake Catalog Curation)

Một hệ thống Conversational Analytics không thể trả lời chính xác nếu tầng dữ liệu bên dưới đặt tên cột viết tắt vô nghĩa (col_01, amt_v2). Repo cung cấp 2 skill chuyên biệt để chuẩn hóa tầng ngữ nghĩa cho AI:

1. semantic-model-authoring (Workflow: Semantic Model AI Readiness):
2. Kiểm tra và làm giàu metadata của Semantic Model để phục vụ Copilot và Data Agent: chuẩn hóa tên gọi thân thiện với nghiệp vụ, thêm mô tả (Description) giải thích ý nghĩa và công thức tính cho từng bảng/cột/measure, thiết lập từ đồng nghĩa (Synonyms), ẩn các cột khóa kỹ thuật (Surrogate Keys), và tạo sẵn bộ VerifiedAnswers cùng CustomInstructions.
3. onelake-catalog-cli (Chế độ curate):
4. Tự động lấy mẫu dữ liệu và cấu trúc của các đối tượng trong Workspace, từ đó dùng AI gợi ý mô tả cấp độ Item, Table và Column, trình bày thành bảng đối chiếu (Current vs Proposed) để Data Steward phê duyệt trước khi ghi hàng loạt vào hệ thống qua API.

Pattern 7: Cổng phê duyệt bắt buộc và Phân tầng công cụ (Greenfield Approval Barrier & Tool Tiering)

Trong các skill có tác động thay đổi dữ liệu hoặc giao diện như powerbi-report-cli và semantic-model-authoring, Microsoft áp dụng 2 cơ chế bảo vệ quan trọng:

1. Greenfield Approval Barrier (Chốt chặn phê duyệt bắt buộc):
2. Ngay cả khi người dùng ra lệnh trong một câu duy nhất: “Hãy lên kế hoạch, thiết kế, tạo báo cáo Power BI và publish lên workspace cho tôi”, Agent vẫn bị khóa cứng ở trạng thái approval_pending (chỉ được phép chạy chế độ planning).
3. Agent bắt buộc phải khảo sát Semantic Model, xuất ra bản đặc tả _brief/report-spec.md, yêu cầu người dùng xác nhận và kết thúc lượt trả lời (end turn). Câu chữ “tạo và publish” trong prompt ban đầu chỉ được coi là “phạm vi mong muốn trong tương lai”, không được coi là giấy phép để bỏ qua bước duyệt thiết kế.
4. Tool Selection Priority (Phân tầng công cụ thực thi):
5. Tier 1 (Ưu tiên số 1 - Live MCP): Nếu powerbi-modeling-mcp đang kết nối trực tiếp tới mô hình (trên Desktop hoặc Workspace), mọi thao tác đọc/ghi phải đi qua MCP để đảm bảo tính toàn vẹn của Tabular Object Model (TOM) và cấm đọc file .tmdl trên đĩa để tránh lệch trạng thái (stale state).
6. Tier 2 (Fallback - Code/REST Round-trip): Chỉ khi không có MCP mới dùng phương pháp tải định nghĩa TMDL về qua az rest, chỉnh sửa file văn bản và đẩy lên lại qua API updateDefinition.

5. Danh mục 25 Skills và 5 Agents trong microsoft/skills-for-fabric

Để đội ngũ phát triển và Data Analyst dễ dàng tra cứu, dưới đây là bảng phân loại toàn bộ 25 Skills trong repo theo nhóm chức năng:

Nhóm A: Conversational BI, Semantic Model & Báo cáo Power BI (Trọng tâm cho DA & BI Agent)

Nhóm B: Truy vấn SQL, Data Warehouse & Khám phá Danh mục Dữ liệu

Nhóm C: Kỹ thuật Dữ liệu (Data Engineering), Real-Time Intelligence & Vận hành

6. Bảng Đối Chiếu Áp Dụng Cho Đội Phát Triển Conversational Analytics Agent

Nếu đội Dev của bạn đang tự xây dựng một hệ thống Conversational Analytics Agent (trên nền tảng LangGraph, AutoGen, Semantic Kernel, Cloudflare Agents SDK, hoặc Custom Agent), dưới đây là các thành phần có thể học hỏi và tái sử dụng trực tiếp từ microsoft/skills-for-fabric:

7. Hướng dẫn Cài đặt & Trải nghiệm Nhanh

Đội ngũ phát triển và Data Analyst có thể tải về nghiên cứu mã nguồn hoặc cài đặt trực tiếp vào công cụ AI Coding đang sử dụng:

Cách 1: Clone trực tiếp Repo để nghiên cứu Kiến trúc Prompt & Skills

Vì repo đã tích hợp sẵn các file cấu hình gốc (CLAUDE.md, GEMINI.md, AGENTS.md, .cursorrules, .windsurfrules, .mcp.json), bạn chỉ cần clone repo về máy và mở bằng Antigravity, Claude Code, Cursor hoặc Gemini CLI:

git clone https://github.com/microsoft/skills-for-fabric.git
cd skills-for-fabric

Cách 2: Cài đặt qua GitHub Copilot CLI hoặc APM (Agent Package Manager)

# Cài đặt trọn bộ Fabric Skills trên GitHub Copilot CLI
copilot plugin install github:microsoft/skills-for-fabric

# Hoặc chỉ cài đặt gói chuyên biệt cho Power BI & Data Analyst
copilot plugin install github:microsoft/skills-for-fabric --plugin-path .github/plugins/powerbi-authoring

# Hoặc cài từng skill riêng lẻ qua APM
apm install microsoft/skills-for-fabric --skill fabriciq -g
apm install microsoft/skills-for-fabric --skill semantic-model-authoring -g
apm install microsoft/skills-for-fabric --skill powerbi-report-cli -g

Cách 3: Xác thực Azure AD để kết nối trực tiếp vào Fabric / Power BI

# Đăng nhập Azure CLI
az login

# Kiểm tra token truy cập Fabric REST API
az account get-access-token --resource https://api.fabric.microsoft.com

# Kiểm tra token truy cập SQL Endpoint (Warehouse / Lakehouse)
az account get-access-token --resource https://database.windows.net