Day 34: Chunking Strategies

Document -> parse -> clean -> chunk -> embed -> index -> retrieve -> rerank -> build context -> generate answer

{
  "chunk_id": "doc-123:v4:recursive:v2:0007:9f1a2c",
  "document_id": "doc-123",
  "document_title": "Chính sách hoàn tiền SaaS",
  "source_uri": "s3://kb/policies/refund-policy-v4.pdf",
  "source_type": "pdf",
  "page_start": 3,
  "page_end": 4,
  "heading_path": ["Chính sách hoàn tiền", "Điều kiện được hoàn tiền"],
  "chunk_index": 7,
  "parent_id": "doc-123:v4:section:refund-conditions",
  "token_count": 312,
  "char_start": 8421,
  "char_end": 10102,
  "document_version": "v4",
  "parser_version": "pdf-layout-parser-2026-05",
  "chunking_strategy": "recursive",
  "chunking_version": "v2",
  "text_hash": "9f1a2c...",
  "tenant_id": "tenant-a",
  "acl_hash": "sales-support-policy-read"
}

Document text
  -> chunk 0: token 0-400
  -> chunk 1: token 350-750
  -> chunk 2: token 700-1100

separators = ["\n## ", "\n### ", "\n\n", "\n", ". ", " ", ""]

# API Rate Limit

## Error 429

| Plan | Limit |
|---|---:|
| Pro | 600 rpm |

Document: API Rate Limit
Section: Errors > HTTP 429
Content:
When the API key exceeds 600 requests per minute, the API returns HTTP 429...

PDF
  -> layout parser
  -> OCR nếu cần
  -> cleanup header/footer
  -> detect block: title, paragraph, table, figure caption, footnote
  -> page-aware chunking
  -> table serialization
  -> metadata validation
  -> embedding/index

Table: Gói dịch vụ và giới hạn request
Columns: Plan | Requests per minute | Burst
Row: Pro | 600 | 1200
Row: Enterprise | 5000 | 10000
Source: page 4

{
  "repo": "payment-service",
  "commit": "a1b2c3d",
  "file_path": "src/refund/policy.ts",
  "language": "typescript",
  "symbol_name": "calculateRefundEligibility",
  "symbol_type": "function",
  "start_line": 42,
  "end_line": 118,
  "imports": ["date-fns", "./types"],
  "chunking_strategy": "tree-sitter-symbol-v1"
}

Parent: section 900-1800 tokens
  Child 1: 180-350 tokens
  Child 2: 180-350 tokens
  Child 3: 180-350 tokens

query
  -> retrieve top_k child chunks
  -> apply metadata/ACL filters
  -> rerank child chunks
  -> group by parent_id
  -> fetch parent sections with budget
  -> dedupe and compress context
  -> generate answer with citations

100,000 documents * 12 chunks/document = 1.2M vectors
100,000 documents * 35 chunks/document = 3.5M vectors

from __future__ import annotations

import hashlib
import math
import re
from dataclasses import dataclass
from typing import Iterable, Literal


Strategy = Literal["fixed", "recursive", "markdown"]


@dataclass(frozen=True)
class Chunk:
    chunk_id: str
    document_id: str
    text: str
    strategy: Strategy
    chunk_index: int
    heading_path: tuple[str, ...]
    source_uri: str
    page_start: int | None = None
    page_end: int | None = None
    parent_id: str | None = None
    token_count: int = 0
    text_hash: str = ""


def estimate_tokens(text: str) -> int:
    # Đủ tốt cho sizing tương đối trong demo. Production nên dùng tokenizer của embedding/LLM model.
    return max(1, math.ceil(len(re.findall(r"\w+|[^\w\s]", text, flags=re.UNICODE)) * 1.25))


def stable_hash(text: str) -> str:
    return hashlib.sha256(text.encode("utf-8")).hexdigest()[:12]


def make_chunk(
    *,
    document_id: str,
    source_uri: str,
    strategy: Strategy,
    chunk_index: int,
    text: str,
    heading_path: tuple[str, ...] = (),
    page_start: int | None = None,
    page_end: int | None = None,
    parent_id: str | None = None,
) -> Chunk:
    normalized = re.sub(r"\s+", " ", text).strip()
    text_hash = stable_hash(normalized)
    chunk_id = f"{document_id}:{strategy}:v1:{chunk_index:04d}:{text_hash}"
    return Chunk(
        chunk_id=chunk_id,
        document_id=document_id,
        text=normalized,
        strategy=strategy,
        chunk_index=chunk_index,
        heading_path=heading_path,
        source_uri=source_uri,
        page_start=page_start,
        page_end=page_end,
        parent_id=parent_id,
        token_count=estimate_tokens(normalized),
        text_hash=text_hash,
    )


def fixed_size_chunks(
    document_id: str,
    source_uri: str,
    text: str,
    max_tokens: int = 160,
    overlap_tokens: int = 30,
) -> list[Chunk]:
    words = re.findall(r"\S+", text)
    chunks: list[Chunk] = []
    start = 0
    index = 0
    step = max(1, max_tokens - overlap_tokens)
    while start < len(words):
        piece = " ".join(words[start : start + max_tokens])
        chunks.append(
            make_chunk(
                document_id=document_id,
                source_uri=source_uri,
                strategy="fixed",
                chunk_index=index,
                text=piece,
            )
        )
        start += step
        index += 1
    return chunks


def split_sentences(text: str) -> list[str]:
    parts = re.split(r"(?<=[.!?])\s+", text.strip())
    return [p.strip() for p in parts if p.strip()]


def recursive_chunks(
    document_id: str,
    source_uri: str,
    text: str,
    max_tokens: int = 220,
    overlap_sentences: int = 1,
) -> list[Chunk]:
    paragraphs = [p.strip() for p in re.split(r"\n\s*\n", text) if p.strip()]
    chunks: list[str] = []
    current: list[str] = []

    def flush() -> None:
        if current:
            chunks.append("\n\n".join(current).strip())
            current.clear()

    for paragraph in paragraphs:
        if estimate_tokens(paragraph) > max_tokens:
            flush()
            sentences = split_sentences(paragraph)
            window: list[str] = []
            for sentence in sentences:
                candidate = " ".join([*window, sentence])
                if estimate_tokens(candidate) > max_tokens and window:
                    chunks.append(" ".join(window))
                    window = window[-overlap_sentences:] if overlap_sentences else []
                window.append(sentence)
            if window:
                chunks.append(" ".join(window))
            continue

        candidate = "\n\n".join([*current, paragraph])
        if estimate_tokens(candidate) > max_tokens:
            flush()
        current.append(paragraph)
    flush()

    return [
        make_chunk(
            document_id=document_id,
            source_uri=source_uri,
            strategy="recursive",
            chunk_index=i,
            text=chunk_text,
        )
        for i, chunk_text in enumerate(chunks)
    ]


def markdown_chunks(
    document_id: str,
    source_uri: str,
    markdown: str,
    max_tokens: int = 260,
) -> list[Chunk]:
    lines = markdown.splitlines()
    sections: list[tuple[tuple[str, ...], list[str]]] = []
    heading_stack: list[tuple[int, str]] = []
    current_lines: list[str] = []
    current_path: tuple[str, ...] = ()

    def flush() -> None:
        if current_lines:
            sections.append((current_path, current_lines.copy()))
            current_lines.clear()

    for line in lines:
        match = re.match(r"^(#{1,6})\s+(.+)$", line)
        if match:
            flush()
            level = len(match.group(1))
            title = match.group(2).strip()
            heading_stack[:] = [(l, t) for l, t in heading_stack if l < level]
            heading_stack.append((level, title))
            current_path = tuple(title for _, title in heading_stack)
            current_lines.append(line)
        else:
            current_lines.append(line)
    flush()

    chunks: list[Chunk] = []
    for path, section_lines in sections:
        section_text = "\n".join(section_lines).strip()
        contextual_text = f"Section: {' > '.join(path)}\n\n{section_text}" if path else section_text
        if estimate_tokens(contextual_text) <= max_tokens:
            chunks.append(
                make_chunk(
                    document_id=document_id,
                    source_uri=source_uri,
                    strategy="markdown",
                    chunk_index=len(chunks),
                    text=contextual_text,
                    heading_path=path,
                )
            )
            continue

        for sub in recursive_chunks(document_id, source_uri, section_text, max_tokens=max_tokens):
            chunks.append(
                make_chunk(
                    document_id=document_id,
                    source_uri=source_uri,
                    strategy="markdown",
                    chunk_index=len(chunks),
                    text=f"Section: {' > '.join(path)}\n\n{sub.text}",
                    heading_path=path,
                )
            )
    return chunks


def simple_embed(text: str) -> set[str]:
    stopwords = {"và", "là", "của", "cho", "trong", "khi", "nếu", "the", "a", "to", "of"}
    terms = re.findall(r"[\w]+", text.lower(), flags=re.UNICODE)
    return {term for term in terms if len(term) > 2 and term not in stopwords}


def jaccard_score(query: str, chunk: Chunk) -> float:
    q = simple_embed(query)
    c = simple_embed(" ".join([*chunk.heading_path, chunk.text]))
    if not q or not c:
        return 0.0
    return len(q & c) / len(q | c)


def retrieve(query: str, chunks: Iterable[Chunk], top_k: int = 5) -> list[tuple[float, Chunk]]:
    scored = [(jaccard_score(query, chunk), chunk) for chunk in chunks]
    return sorted(scored, key=lambda item: item[0], reverse=True)[:top_k]

[
  {
    "query": "Gói Pro bị giới hạn bao nhiêu request mỗi phút?",
    "expected_source": "refund-policy.md#rate-limit",
    "expected_terms": ["Pro", "600", "requests per minute"]
  },
  {
    "query": "Khách hàng có được hoàn tiền sau 30 ngày không?",
    "expected_source": "refund-policy.md#refund-window",
    "expected_terms": ["30 ngày", "không hoàn tiền", "ngoại lệ"]
  }
]

Nếu tài liệu có cấu trúc rõ -> chunk theo cấu trúc.
Nếu tài liệu là PDF quan trọng -> ưu tiên layout/page/table trước token size.
Nếu tài liệu là code -> chunk theo symbol.
Nếu query cần fact nhỏ nhưng answer cần context rộng -> parent-child.
Nếu chưa biết gì -> recursive baseline + eval, không nhảy thẳng vào semantic phức tạp.

document_id: acme-refund-policy-v4
title: Chính sách hoàn tiền và giới hạn sử dụng ACME Cloud
source_uri: kb://policies/acme-refund-policy-v4.md
source_type: markdown
document_version: v4
effective_date: 2026-05-01
owner_team: customer-success
tenant_id: acme-public-demo

# Chính sách hoàn tiền và giới hạn sử dụng ACME Cloud

Tài liệu này mô tả điều kiện hoàn tiền, giới hạn request và quy trình xử lý exception cho khách hàng dùng ACME Cloud. Tài liệu áp dụng cho các gói Starter, Pro và Enterprise từ ngày 2026-05-01.

## 1. Phạm vi áp dụng

Chính sách này áp dụng cho khách hàng mua subscription trực tiếp từ ACME Cloud. Chính sách không áp dụng cho khách hàng mua qua marketplace của bên thứ ba, reseller hoặc hợp đồng enterprise có điều khoản riêng.

Nếu hợp đồng enterprise có điều khoản hoàn tiền riêng, điều khoản trong hợp đồng được ưu tiên hơn tài liệu này. Nhân viên support phải kiểm tra contract id trước khi trả lời khách hàng enterprise.

## 2. Cửa sổ hoàn tiền

Khách hàng được yêu cầu hoàn tiền trong vòng 30 ngày kể từ ngày thanh toán đầu tiên của subscription. Sau 30 ngày, ACME Cloud không hoàn tiền cho phí subscription đã phát sinh, trừ khi có lỗi hệ thống nghiêm trọng được xác nhận bởi đội Engineering.

Yêu cầu hoàn tiền chỉ được xử lý nếu tài khoản không vi phạm điều khoản sử dụng, không có dấu hiệu abuse và chưa sử dụng quá 20% quota tháng đầu tiên.

Ví dụ: nếu khách hàng Pro có quota 1,000,000 API calls mỗi tháng, khách hàng phải dùng không quá 200,000 API calls trong tháng đầu tiên để đủ điều kiện hoàn tiền tự động.

## 3. Bảng giới hạn request

| Gói | Request mỗi phút | Burst tối đa | Quota tháng |
|---|---:|---:|---:|
| Starter | 60 | 120 | 100,000 |
| Pro | 600 | 1,200 | 1,000,000 |
| Enterprise | 5,000 | 10,000 | Theo hợp đồng |

Nếu vượt giới hạn request mỗi phút, API trả về HTTP 429 và header `Retry-After`. Client nên dùng exponential backoff với jitter. ACME Cloud có thể giảm rate limit tạm thời nếu phát hiện traffic bất thường.

## 4. Điều kiện không được hoàn tiền

Khách hàng không được hoàn tiền nếu một trong các điều kiện sau xảy ra:

- Tài khoản bị khóa do vi phạm chính sách spam, scraping hoặc credential sharing.
- Khách hàng đã dùng quá 20% quota tháng đầu tiên.
- Yêu cầu hoàn tiền được gửi sau cửa sổ 30 ngày.
- Subscription được mua qua marketplace hoặc reseller.
- Invoice đã được điều chỉnh bằng credit note trước đó.

Support agent không được hứa hoàn tiền nếu chưa kiểm tra đầy đủ các điều kiện trên.

## 5. Exception do lỗi hệ thống

Nếu ACME Cloud gặp lỗi hệ thống nghiêm trọng làm khách hàng không thể dùng dịch vụ trên 4 giờ liên tục, Customer Success có thể tạo exception để hoàn tiền một phần hoặc cấp service credit.

Exception phải có incident id, thời gian ảnh hưởng, danh sách region bị ảnh hưởng và xác nhận từ Engineering Manager trực ca. Nếu thiếu incident id, yêu cầu phải được chuyển sang manual review.

## 6. Quy trình xử lý support ticket

Support agent cần thực hiện các bước sau:

1. Xác định `account_id`, `subscription_id`, `invoice_id` và ngày thanh toán đầu tiên.
2. Kiểm tra contract id nếu khách hàng thuộc gói Enterprise.
3. Kiểm tra usage trong tháng đầu tiên.
4. Kiểm tra trạng thái abuse hoặc policy violation.
5. Đối chiếu cửa sổ 30 ngày.
6. Nếu đủ điều kiện, tạo refund request trong billing system.
7. Nếu không đủ điều kiện, trả lời khách hàng bằng lý do cụ thể và trích dẫn chính sách.

## 7. Mẫu phản hồi cho khách hàng

Nếu khách hàng đủ điều kiện:

> Chúng tôi đã kiểm tra tài khoản của bạn và xác nhận yêu cầu hoàn tiền nằm trong cửa sổ 30 ngày, đồng thời usage chưa vượt quá 20% quota tháng đầu tiên. Yêu cầu hoàn tiền đã được tạo và thường được xử lý trong 5-10 ngày làm việc.

Nếu khách hàng không đủ điều kiện:

> Chúng tôi chưa thể xử lý hoàn tiền vì yêu cầu không đáp ứng điều kiện của chính sách hiện tại. Lý do cụ thể là: {reason}. Nếu bạn cho rằng đây là lỗi hệ thống, vui lòng cung cấp thêm thông tin để chúng tôi chuyển sang manual review.

## 8. Code ví dụ cho client retry

```python
import random
import time


def call_with_backoff(client, request, max_retries=5):
    for attempt in range(max_retries):
        response = client.send(request)
        if response.status_code != 429:
            return response

        retry_after = response.headers.get("Retry-After")
        if retry_after is not None:
            sleep_seconds = float(retry_after)
        else:
            sleep_seconds = min(30, 2 ** attempt) + random.uniform(0, 0.5)

        time.sleep(sleep_seconds)

    raise TimeoutError("API vẫn trả về HTTP 429 sau khi retry")
```

Code trên chỉ minh họa client behavior. Production client nên có timeout, circuit breaker, request id, structured log và metric cho số lần retry.

QUERIES = [
    {
        "id": "Q1",
        "query": "Gói Pro được gọi bao nhiêu request mỗi phút?",
        "expected_terms": ["Pro", "600"],
        "expected_heading": "Bảng giới hạn request",
    },
    {
        "id": "Q2",
        "query": "Khách hàng sau 30 ngày có được hoàn tiền không?",
        "expected_terms": ["Sau 30 ngày", "không hoàn tiền"],
        "expected_heading": "Cửa sổ hoàn tiền",
    },
    {
        "id": "Q3",
        "query": "Khi nào support phải chuyển manual review?",
        "expected_terms": ["incident id", "manual review"],
        "expected_heading": "Exception do lỗi hệ thống",
    },
    {
        "id": "Q4",
        "query": "Điều kiện usage để được hoàn tiền tự động là gì?",
        "expected_terms": ["20% quota", "tháng đầu tiên"],
        "expected_heading": "Cửa sổ hoàn tiền",
    },
    {
        "id": "Q5",
        "query": "Client nên xử lý HTTP 429 như thế nào?",
        "expected_terms": ["Retry-After", "exponential backoff", "jitter"],
        "expected_heading": "Bảng giới hạn request",
    },
    {
        "id": "Q6",
        "query": "Khách hàng mua qua reseller có được áp dụng chính sách này không?",
        "expected_terms": ["không áp dụng", "reseller"],
        "expected_heading": "Phạm vi áp dụng",
    },
]