Chuẩn cấu trúc Knowledge Pack

Tổng quan: Knowledge Pack là gì?

Knowledge Pack là file chứa kiến thức chuyên biệt về thị trường tài chính Việt Nam, được đóng gói theo chuẩn để AI agent có thể load và sử dụng ngay mà không cần tiền xử lý thêm.

Khác với prompt thông thường, một Knowledge Pack có đầy đủ: cấu trúc rõ ràng, code snippet sẵn chạy được, prompt snippet định nghĩa hành vi agent, và tham chiếu nguồn dữ liệu thực tế từ Viet Dataverse API.

Tại sao cần chuẩn cấu trúc?

System kiểm tra tự động (auto-validator) chạy ngay khi Seller upload. Pack đạt chuẩn thì lên sàn ngay, không cần admin duyệt. Pack thiếu phần bắt buộc bị reject với thông báo chi tiết để sửa.

3 loại pack

Viet Dataverse hỗ trợ ba định dạng sản phẩm, mỗi loại phục vụ một use case khác nhau trong AI agent pipeline:

Loại 1: Knowledge Document (.md)

Knowledge Document là loại pack phổ biến nhất. File Markdown chứa kiến thức chuyên sâu về một chủ đề tài chính VN, cấu trúc theo 7 phần bắt buộc để developer và researcher đều dùng được ngay.

Cấu trúc skeleton

# [Tên chủ đề]
**Dành cho:** [use case chính — 1 câu]
**Tầm quan trọng:** [tại sao quan trọng với nền kinh tế VN — 1-2 câu]

---

## Cách dùng pack này

### Dành cho Developer / Agent Builder
```python
import requests
API_KEY = "your-api-key"
headers = {"X-API-Key": API_KEY}

# Gọi Viet Dataverse API
data = requests.get(
    "https://api.vietdataverse.online/api/v1/[endpoint]",
    params={"period": "1y"},
    headers=headers
).json()["data"]

# Ví dụ output:
# [{"period": "2024-01-15", "value": ...}, ...]
print(f"Dữ liệu mới nhất: {data[-1]}")
```

### Dành cho Researcher / Người không biết code
1. Nhấn "📋 Copy to Claude" trên thư viện VDV
2. Mở Claude.ai → paste vào chat
3. Đặt câu hỏi bên dưới
**Câu hỏi gợi ý:**
- "[Câu hỏi cụ thể có con số thực tế]"
- "[Câu hỏi so sánh hoặc tìm nguyên nhân]"
- "[Câu hỏi về tác động hoặc kịch bản what-if]"

---

## 1. [Phần nội dung — thực trạng / số liệu]

[Số liệu, bảng ASCII, cơ chế thị trường — kèm nguồn + năm]

## 2. [Phần nội dung — phân tích / cơ chế]

| Yếu tố | Giá trị / Ngưỡng | Ý nghĩa |
|--------|-----------------|---------|
| ...    | ...             | ...     |

## Prompt snippet cho agent [tên ngành]
```
Khi phân tích [chủ đề]:

1. [Bước đầu tiên]
2. [Bước hai — kiểm tra gì]
3. [Bước ba — kết luận thế nào]

Dấu hiệu tốt:   [điều kiện] → [ý nghĩa]
Dấu hiệu xấu:  [điều kiện] → [ý nghĩa]

KHÔNG đưa ra khuyến nghị mua/bán tuyệt đối.
Luôn kết hợp với [context bổ sung cần thiết].
```

---

## Nguồn dữ liệu
```python
GET https://api.vietdataverse.online/api/v1/[endpoint-1]
GET https://api.vietdataverse.online/api/v1/[endpoint-2]

# Nguồn thực tế (không có API):
# [Tên tổ chức]: https://[url]
```

Ví dụ thực tế — rút gọn từ pack "Vietnam Gold Market Playbook"

# Thị trường Vàng Việt Nam — Cơ chế & Số liệu Chuyên sâu
**Dành cho:** Agent phân tích giá vàng VN, nhà đầu tư cá nhân, nhà nghiên cứu kinh tế vĩ mô
**Tầm quan trọng:** Vàng tại Việt Nam không chỉ là hàng hoá — đây là kênh trú ẩn chính khi đồng VND mất giá,
với thị trường nội địa thường cách biệt đáng kể so với giá quốc tế do chính sách nhập khẩu hạn chế của SBV.

---

## Cách dùng pack này

### Dành cho Developer / Agent Builder
```python
import requests

API_KEY = "your-api-key"
BASE    = "https://api.vietdataverse.online/api/v1"

# Lấy 90 ngày giá vàng SJC
r = requests.get(f"{BASE}/gold",
    params={"type": "SJC", "period": "90d"},
    headers={"X-API-Key": API_KEY})

data = r.json()["data"]
latest = data[-1]
print(f"SJC {latest['period']}: mua={latest['buy_price']:,} | bán={latest['sell_price']:,} VND/lượng")
# Output: SJC 2025-06-08: mua=121,500,000 | bán=123,000,000 VND/lượng
```

### Dành cho Researcher / Người không biết code
1. Nhấn "📋 Copy to Claude" trên thư viện Viet Dataverse
2. Mở Claude.ai → paste vào chat
3. Đặt câu hỏi bên dưới

**Câu hỏi gợi ý:**
- "Chênh lệch giá vàng SJC so với DOJI hiện tại là bao nhiêu? Nguyên nhân?"
- "Khi USD/VND tăng 1%, giá vàng VN thường phản ứng thế nào trong lịch sử?"
- "SBV có những công cụ nào để kiểm soát chênh lệch giá vàng nội địa—quốc tế?"

---

## 1. Thực trạng thị trường vàng VN (2024–2025)

```
Tổ chức      Loại      Mua vào       Bán ra        Chênh lệch
SJC          24K 1 lượng 120,500,000  122,500,000   2,000,000 VND
DOJI         24K 1 lượng 119,800,000  121,300,000   1,500,000 VND
BTMC         24K 1 lượng 119,700,000  121,200,000   1,500,000 VND

Giá vàng quốc tế (XAU): ~3,320 USD/oz → ~109,000,000 VND/lượng (tỷ giá 25,450)
Chênh lệch nội địa–quốc tế: ~10–13 triệu VND/lượng (khoảng 10–12%)

Nguồn: Viet Dataverse API / SJC / DOJI / BTMC, tháng 6/2025
```

## Prompt snippet cho agent phân tích vàng
```
Khi người dùng hỏi về giá vàng Việt Nam:

1. Lấy giá SJC + DOJI + BTMC mới nhất từ Viet Dataverse API
2. Tính chênh lệch mua–bán của từng thương hiệu
3. So sánh với giá XAU quốc tế quy đổi VND theo tỷ giá VCB
4. Nhận xét xu hướng 30 ngày gần nhất

Ngưỡng chênh lệch đáng chú ý: >5 triệu VND/lượng so quốc tế → áp lực thị trường cao.

KHÔNG đưa ra khuyến nghị mua/bán tuyệt đối.
Luôn kết hợp với diễn biến tỷ giá USD/VND và chính sách SBV.
```

## Nguồn dữ liệu
```python
GET https://api.vietdataverse.online/api/v1/gold?type=SJC&period=90d
GET https://api.vietdataverse.online/api/v1/gold?type=DOJI&period=90d
GET https://api.vietdataverse.online/api/v1/sbv-centralrate?currency=USD

# Nguồn tham khảo:
# SBV: https://www.sbv.gov.vn
# SJC: https://sjc.com.vn
```

Loại 2: Agent Blueprint (.yaml / .json)

Agent Blueprint là file YAML hoặc JSON định nghĩa toàn bộ hành vi của một AI agent chuyên biệt. Khác với Knowledge Document chỉ là reference material, Blueprint có thể import trực tiếp vào LangChain, n8n, Dify như một workflow definition — tools, routing logic, few-shot examples đều được khai báo sẵn.

Cấu trúc skeleton

# VDV Agent Blueprint v1
meta:
  name: "Tên agent"
  version: "1.0"
  description: "Mô tả 1 câu — agent làm gì, cho ai"
  domains: [macro, gold, fx]        # lĩnh vực chuyên môn
  compatible_with: [langchain, n8n, dify, claude-tools]

system_prompt: |
  Bạn là agent phân tích [lĩnh vực] cho thị trường Việt Nam.
  Chuyên môn: [liệt kê cụ thể]
  Nguyên tắc trả lời:
  - Luôn trích dẫn nguồn dữ liệu
  - Chỉ cung cấp thông tin tham khảo
  KHÔNG đưa ra khuyến nghị mua/bán.

tools:
  - name: get_gold_price
    description: "Lấy giá vàng VN từ Viet Dataverse"
    endpoint: "https://api.vietdataverse.online/api/v1/gold"
    params: {type: string, period: string}
    auth: x-api-key

  - name: get_fx_rate
    description: "Lấy tỷ giá USD/VND"
    endpoint: "https://api.vietdataverse.online/api/v1/sbv-centralrate"
    params: {currency: string, period: string}
    auth: x-api-key

routing:
  - intent: "hỏi về vàng"
    tool: get_gold_price
    then: analyze_and_respond
  - intent: "hỏi về tỷ giá"
    tool: get_fx_rate
    then: analyze_and_respond

few_shot_examples:
  - user: "Giá vàng SJC hôm nay bao nhiêu?"
    assistant: |
      Dựa trên dữ liệu từ Viet Dataverse (cập nhật [ngày]):
      - SJC mua vào: 120,500,000 VND/lượng
      - SJC bán ra: 122,500,000 VND/lượng
      Chênh lệch so với giá quốc tế: khoảng 11 triệu VND/lượng (~10%).

disclaimer: |
  Agent này chỉ cung cấp thông tin tham khảo.
  Không chịu trách nhiệm về các quyết định đầu tư dựa trên thông tin từ agent.

Ví dụ thực tế — Credit Scoring Support Agent (rút gọn)

# VDV Agent Blueprint v1
meta:
  name: "VN Credit Context Agent"
  version: "1.2"
  description: "Agent cung cấp context lãi suất & tín dụng VN cho hệ thống credit scoring"
  domains: [finance, credit, termdepo, sbv-policy]
  compatible_with: [langchain, n8n, dify, openai-function-calling]

system_prompt: |
  Bạn là agent chuyên cung cấp dữ liệu nền tảng về thị trường tín dụng Việt Nam.
  Mục tiêu: hỗ trợ mô hình credit scoring bằng cách cung cấp context lãi suất thực tế.

  Khi được hỏi, luôn:
  1. Truy vấn dữ liệu mới nhất từ Viet Dataverse
  2. Cung cấp khoảng lãi suất thị trường theo kỳ hạn
  3. Nêu xu hướng 3 tháng gần nhất
  4. Đặt trong bối cảnh chính sách SBV hiện hành

  KHÔNG đưa ra đánh giá tín dụng cá nhân.
  KHÔNG đưa ra khuyến nghị cho vay hay từ chối vay.

tools:
  - name: get_termdepo_rates
    description: "Lấy lãi suất tiết kiệm ngân hàng theo kỳ hạn"
    endpoint: "https://api.vietdataverse.online/api/v1/termdepo"
    params:
      period: {type: string, options: [30d, 90d, 1y], default: 90d}
    auth: x-api-key
    output_format: |
      Trả về mảng [{period, term_1m, term_3m, term_6m, term_12m}]

  - name: get_sbv_policy_rate
    description: "Lấy lãi suất điều hành SBV"
    endpoint: "https://api.vietdataverse.online/api/v1/sbv-interbank"
    params:
      period: {type: string, default: 90d}
    auth: x-api-key

routing:
  - intent: "lãi suất hiện tại"
    tool: get_termdepo_rates
    then: summarize_rates
  - intent: "lãi suất SBV"
    tool: get_sbv_policy_rate
    then: summarize_rates
  - intent: "so sánh kỳ hạn"
    tool: get_termdepo_rates
    then: compare_tenors

few_shot_examples:
  - user: "Lãi suất tiết kiệm 12 tháng hiện nay là bao nhiêu?"
    assistant: |
      Theo dữ liệu từ Viet Dataverse (ACB, cập nhật tháng 6/2025):
      - 1 tháng: 3.1%/năm
      - 3 tháng: 3.5%/năm
      - 6 tháng: 4.2%/năm
      - 12 tháng: 5.0%/năm
      Xu hướng 3 tháng: lãi suất 12 tháng tăng nhẹ +0.3% so với tháng 3/2025.

disclaimer: |
  Dữ liệu lấy từ Viet Dataverse API, có thể trễ 1 ngày so với niêm yết thực tế.
  Chỉ dùng cho mục đích tham khảo trong credit scoring pipeline.
  Không thay thế thẩm định tín dụng chuyên nghiệp.

Loại 3: Dataset Pack (.csv / .json)

Dataset Pack là file dữ liệu lịch sử dạng bảng — timeseries về lãi suất, CPI, giá vàng, hoặc benchmark VN30. Agent dùng cho RAG lookup, few-shot context injection, hoặc backtesting pipeline.

Required fields

Ví dụ CSV (CPI series)

period,value,source,unit,indicator
2024-01,3.37,GSO,% YoY,CPI
2024-02,3.98,GSO,% YoY,CPI
2024-03,3.97,GSO,% YoY,CPI
2024-04,4.40,GSO,% YoY,CPI
2024-05,4.44,GSO,% YoY,CPI
2024-06,4.34,GSO,% YoY,CPI
2024-07,3.45,GSO,% YoY,CPI
2024-08,3.45,GSO,% YoY,CPI
2024-09,2.63,GSO,% YoY,CPI
2024-10,2.89,GSO,% YoY,CPI

Cấu trúc bắt buộc (7 phần)

Áp dụng cho Knowledge Document (.md). Auto-validator kiểm tra tất cả 7 phần theo thứ tự khi upload.

Nội dung bị cấm (auto-reject)

Checklist trước khi submit

Tự kiểm tra trước khi upload để tránh bị reject:

• Header có **Dành cho:** và **Tầm quan trọng:** trong 5 dòng đầu
• Mục ## Cách dùng pack này có đủ 2 sub-section (Developer + Researcher)
• Code Python trong phần Developer có ít nhất 10 dòng và chạy được
• Có ít nhất 3 câu hỏi gợi ý cụ thể (không hỏi chung chung)
• Có ít nhất 2 phần nội dung chính với heading ##
• Mọi số liệu đều kèm tên nguồn và năm
• Có mục ## Prompt snippet cho agent với tối thiểu 10 dòng
• Prompt snippet kết thúc bằng dòng disclaimer "KHÔNG đưa ra khuyến nghị..."
• Có mục ## Nguồn dữ liệu với ít nhất 1 URL hoặc endpoint thực tế
• File size từ 2 KB đến 50 KB
• Không chứa API key thật, SĐT cá nhân, CMND, hoặc thông tin bí mật khác
• Mô tả sản phẩm (field "Mô tả" trên form upload) có ít nhất 50 ký tự

Điều khoản & Disclaimer tự động

Seller không cần viết disclaimer vào file. Platform tự động inject đoạn sau vào cuối mỗi pack khi lưu vào hệ thống:

---
## Điều khoản sử dụng

Knowledge pack này được cung cấp **chỉ cho mục đích sử dụng cá nhân** (personal use).
Nghiêm cấm sử dụng cho mục đích thương mại dưới bất kỳ hình thức nào mà không có
sự cho phép bằng văn bản của Viet Dataverse và/hoặc tác giả.

Thông tin trong pack này mang tính tham khảo và giáo dục.
**Viet Dataverse (và/hoặc tác giả) không chịu trách nhiệm** về bất kỳ kết quả,
tổn thất, hay hậu quả nào phát sinh từ việc sử dụng hoặc áp dụng thông tin này,
bao gồm nhưng không giới hạn ở các quyết định đầu tư, tài chính, hoặc kinh doanh.

*Phiên bản: được tạo tự động bởi Viet Dataverse Platform.*

Cách upload

Quy trình upload 3 bước — không có admin review, pack lên sàn ngay khi pass validator:

Cần hỗ trợ? Email support@vietdataverse.online hoặc xem Hướng dẫn Seller để biết thêm về quy trình đăng ký và payout.