poc_system/doc/4.OpenSearch-Index-Search-Playbook.md

4.OpenSearch-Index-Search-Playbook.md

Tài liệu này kế thừa trực tiếp các file trước (1–3). Mục tiêu: thiết kế Index & Search Layer đảm bảo tra cứu nhanh, đúng quyền, hỗ trợ full‑text, semantic search và RAG về sau. Nội dung viết để tái sử dụng lâu dài, có thể nạp lại để tiếp tục triển khai.

---

Mục lục

1. Vai trò của Index/Search trong pipeline
2. Nguyên tắc thiết kế
3. Kiến trúc logical của Search Layer
4. Thiết kế Index (mapping chi tiết)
5. ACL‑aware indexing & filtering
6. Full‑text Search
7. Vector & Semantic Search
8. Hybrid Search (khuyến nghị)
9. Highlight, Ranking & Relevance tuning
10. Query contract (API level)
11. Performance & Scale
12. Lifecycle management (update/delete)
13. Checklist triển khai

---

1. Vai trò của Index/Search trong pipeline

Extraction & Chunking
        │
        ▼
Index Layer (OpenSearch)
        │
        ▼
Search UI / Chat (RAG)

Index/Search chịu trách nhiệm:

• Lưu trữ chunk nội dung + metadata + ACL
• Trả kết quả nhanh, chính xác, đúng quyền
• Cho phép search theo từ khóa lẫn ngữ nghĩa

---

2. Nguyên tắc thiết kế

1. Chunk‑first, không file‑first
2. Permission filter ở query time nhưng dữ liệu đã chuẩn hóa từ ingestion
3. Hybrid search mặc định (keyword + vector)
4. Index schema ổn định, embedding thay đổi được
5. Re‑index được từ output Extraction mà không cần SharePoint

---

3. Kiến trúc logical của Search Layer

OpenSearch Cluster
 ├── text index
 ├── vector index (hoặc combined)
 ├── analyzer (vi, en)
 └── ACL filter

Có thể:

• Dùng 1 index combined (text + vector)
• Hoặc 2 index song song (đơn giản giai đoạn đầu: 1 index)

---

4. Thiết kế Index (Mapping)

4.1 Document unit

Mỗi document trong index = 1 chunk.

4.2 Mapping gợi ý

{
  "mappings": {
    "properties": {
      "chunk_id": { "type": "keyword" },
      "file_id": { "type": "keyword" },
      "file_name": { "type": "text" },
      "text": {
        "type": "text",
        "analyzer": "standard",
        "search_analyzer": "standard"
      },
      "embedding": {
        "type": "knn_vector",
        "dimension": 768
      },
      "site_id": { "type": "keyword" },
      "page_from": { "type": "integer" },
      "page_to": { "type": "integer" },
      "source_url": { "type": "keyword" },
      "permissions": { "type": "keyword" },
      "updated_at": { "type": "date" }
    }
  }
}

---

5. ACL‑aware Indexing & Filtering

5.1 Nguyên tắc

• Không index public rồi filter payload
• Mỗi chunk mang theo list principal IDs (user/group)

5.2 Filter tại query

{
  "terms": {
    "permissions": ["current_user_id", "group_id_1"]
  }
}

---

6. Full‑text Search

Sử dụng khi:

• Tìm chính xác điều khoản, mã số, tên riêng

Ví dụ query:

{
  "match": {
    "text": "hợp đồng lao động không xác định thời hạn"
  }
}

---

7. Vector & Semantic Search

Sử dụng khi:

• Câu hỏi tự nhiên
• Nội dung diễn đạt khác từ khóa

{
  "knn": {
    "embedding": {
      "vector": [ ... ],
      "k": 10
    }
  }
}

---

8. Hybrid Search (Khuyến nghị mặc định)

{
  "bool": {
    "must": [
      {
        "match": { "text": "chấm dứt hợp đồng" }
      }
    ],
    "should": [
      {
        "knn": {
          "embedding": {
            "vector": [ ... ],
            "k": 10
          }
        }
      }
    ]
  }
}

Score cuối = combine(keyword_score, semantic_score)

---

9. Highlight, Ranking & Relevance

9.1 Highlight

• Highlight ở field text
• Trả snippet cho UI

9.2 Ranking hints

• Boost theo:
  • page proximity
  • recency (updated_at)
  • heading match

---

10. Query Contract (API nội bộ)

POST /search

Input:

{ "query": "...", "user_id": "...", "groups": ["..."] }

Output:

{
  "results": [
    { "file_name": "...", "page": 5, "snippet": "...", "url": "..." }
  ]
}

---

11. Performance & Scale

• Index theo chunk, không theo file
• Shard theo dữ liệu, không theo tenant sớm
• Cache query phổ biến

---

12. Lifecycle Management

Event	Action
File update	Delete chunks cũ → index lại
File delete	Soft delete hoặc remove
Re‑embedding	Update embedding field

---

13. Checklist triển khai

✅ Mapping ổn định ✅ ACL filter hoạt động ✅ Hybrid search default ✅ Highlight trả đúng trang ✅ Re‑index không cần SharePoint

---

Kết thúc Index & Search Playbook. File tiếp theo sẽ là RAG / Chat Layer.