Citations — Trích dẫn nguồn chính xác với Claude API

Một vấn đề cốt lõi của LLM là hallucination — tạo ra thông tin không có trong nguồn. Với ứng dụng RAG (Retrieval-Augmented Generation) và document Q&A, người dùng cần biết thông tin đến từ đâu. Citations API của Claude giải quyết vấn đề này bằng cách buộc model trích dẫn chính xác từ tài liệu được cung cấp.

Citations API là gì?

Khi bật citations, Claude không chỉ trả lời câu hỏi mà còn chỉ ra chính xác đoạn văn nào trong tài liệu được dùng để support mỗi claim. Đây là tính năng built-in, không cần prompt engineering phức tạp.

Ưu điểm:

• Người dùng có thể verify thông tin trực tiếp từ nguồn
• Giảm hallucination vì Claude biết mình sẽ bị fact-check
• Tự động highlight passages liên quan trong tài liệu
• Hữu ích cho legal, medical, research applications

Cấu trúc Document với Citations

import anthropic

client = anthropic.Anthropic()

# Tài liệu cần analyze
document_text = """
Chính sách hoàn trả hàng hóa

Điều 1: Thời hạn hoàn trả
Khách hàng có quyền hoàn trả sản phẩm trong vòng 30 ngày kể từ ngày nhận hàng.
Sản phẩm phải còn nguyên vẹn, chưa sử dụng, và còn đầy đủ bao bì gốc.

Điều 2: Sản phẩm không được hoàn trả
Các sản phẩm sau không được hoàn trả: đồ ăn uống, sản phẩm vệ sinh cá nhân đã mở,
phần mềm đã kích hoạt, và các mặt hàng clearance được đánh dấu "Không hoàn trả".

Điều 3: Quy trình hoàn trả
Để hoàn trả, khách hàng liên hệ bộ phận CSKH qua hotline 1800-xxxx.
Chúng tôi sẽ gửi label vận chuyển miễn phí trong vòng 24 giờ.
Tiền hoàn trả được xử lý trong 5-7 ngày làm việc.
"""

# Gửi document với citations enabled
response = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "text",
                        "media_type": "text/plain",
                        "data": document_text,
                    },
                    "title": "Chính sách hoàn trả",
                    # Bật citations cho document này
                    "citations": {"enabled": True},
                },
                {
                    "type": "text",
                    "text": "Tôi mua điện thoại 15 ngày trước và muốn hoàn trả. Tôi có được không? Quy trình như thế nào?"
                }
            ],
        }
    ],
)

print(response.content)

Parse và hiển thị Citations

def parse_cited_response(response) -> dict:
    """
    Parse response có citations thành cấu trúc dễ dùng.
    """
    result = {
        "text_blocks": [],
        "citations": [],
        "full_answer": "",
    }

    for block in response.content:
        if block.type == "text":
            result["text_blocks"].append(block.text)
            result["full_answer"] += block.text

        elif block.type == "citations":
            for citation in block.citations:
                citation_data = {
                    "claim": citation.cited_text if hasattr(citation, "cited_text") else "",
                    "source_document": citation.document_title if hasattr(citation, "document_title") else "Unknown",
                    "quote": citation.quote if hasattr(citation, "quote") else "",
                    "start_char": getattr(citation, "start_char_index", None),
                    "end_char": getattr(citation, "end_char_index", None),
                }
                result["citations"].append(citation_data)

    return result

# Parse kết quả
parsed = parse_cited_response(response)

print("=== TRẢ LỜI ===")
print(parsed["full_answer"])

print("
=== TRÍCH DẪN NGUỒN ===")
for i, citation in enumerate(parsed["citations"], 1):
    print(f"
[{i}] Nguồn: {citation['source_document']}")
    print(f"    Đoạn trích: "{citation['quote'][:100]}..."" if len(citation['quote']) > 100 else f"    Đoạn trích: "{citation['quote']}"")

RAG với Citations — Nhiều tài liệu

def rag_with_citations(question: str, documents: list) -> dict:
    """
    RAG pipeline với citations.
    documents: list of {"title": str, "content": str}
    """
    # Build content list với nhiều documents
    content = []

    for doc in documents:
        content.append({
            "type": "document",
            "source": {
                "type": "text",
                "media_type": "text/plain",
                "data": doc["content"],
            },
            "title": doc["title"],
            "citations": {"enabled": True},
        })

    content.append({
        "type": "text",
        "text": question
    })

    response = client.messages.create(
        model="claude-opus-4-5",
        max_tokens=2000,
        system="""Trả lời câu hỏi dựa HOÀN TOÀN trên các tài liệu được cung cấp.
Nếu thông tin không có trong tài liệu, nói rõ "Tôi không tìm thấy thông tin này trong tài liệu."
Luôn trích dẫn nguồn cho mỗi khẳng định.""",
        messages=[{"role": "user", "content": content}],
    )

    return parse_cited_response(response)

# Ví dụ: Knowledge base về sản phẩm
knowledge_base = [
    {
        "title": "Hướng dẫn sử dụng iPhone 16",
        "content": """
iPhone 16 có pin 3.561 mAh, hỗ trợ sạc nhanh 20W và sạc không dây MagSafe 15W.
Camera chính 48MP với khẩu độ f/1.6. Chip A18 Bionic với 6 nhân CPU và 5 nhân GPU.
Bộ nhớ RAM 8GB, hỗ trợ nhiều tùy chọn storage từ 128GB đến 512GB.
"""
    },
    {
        "title": "Chính sách bảo hành Apple",
        "content": """
Apple Limited Warranty bảo hành 1 năm cho lỗi phần cứng từ nhà sản xuất.
AppleCare+ gia hạn thêm 2 năm và bao gồm tối đa 2 lần sửa chữa tai nạn mỗi năm.
Pin được bảo hành giữ trên 80% dung lượng trong 1 năm hoặc 500 chu kỳ sạc.
"""
    },
    {
        "title": "FAQ Mua hàng",
        "content": """
Chúng tôi có 30 ngày đổi trả không điều kiện cho hàng mới.
Giao hàng miễn phí cho đơn hàng trên 500.000 VND.
Thanh toán hỗ trợ: tiền mặt, chuyển khoản, thẻ tín dụng, trả góp 0%.
"""
    },
]

result = rag_with_citations(
    "Pin iPhone 16 có tốt không? Nếu pin hỏng trong 6 tháng thì được bảo hành không?",
    knowledge_base
)

print(result["full_answer"])
print(f"
Số citations: {len(result['citations'])}")

Tích hợp với UI — Highlight nguồn

def format_answer_with_inline_citations(parsed_response: dict) -> str:
    """
    Format câu trả lời với inline citation numbers,
    dùng cho hiển thị trên web.
    """
    answer = parsed_response["full_answer"]
    citations = parsed_response["citations"]

    # Thêm footer với danh sách nguồn
    if citations:
        answer += "

---
**Nguồn tham khảo:**
"
        for i, citation in enumerate(citations, 1):
            answer += f"
[{i}] **{citation['source_document']}**
"
            quote = citation['quote']
            if len(quote) > 150:
                quote = quote[:150] + "..."
            answer += f"    > {quote}
"

    return answer

def generate_html_with_citations(parsed_response: dict) -> str:
    """Tạo HTML với highlighted citations."""
    answer = parsed_response["full_answer"]
    citations = parsed_response["citations"]

    html = f"
{answer}
"

    if citations:
        html += "

Nguồn trích dẫn:

"
        for i, citation in enumerate(citations, 1):
            html += f"""

    [{i}] {citation['source_document']}
    
{citation['quote'][:200]}

"""
        html += "
"

    return html

# Output HTML
html_output = generate_html_with_citations(result)
print(html_output[:500])

PDF với Citations

import base64

def pdf_qa_with_citations(pdf_path: str, question: str) -> dict:
    """Q&A trên PDF với citations."""
    with open(pdf_path, "rb") as f:
        pdf_base64 = base64.standard_b64encode(f.read()).decode()

    response = client.messages.create(
        model="claude-opus-4-5",
        max_tokens=2000,
        messages=[{
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_base64,
                    },
                    "title": pdf_path.split("/")[-1],
                    "citations": {"enabled": True},
                },
                {"type": "text", "text": question}
            ],
        }],
    )

    return parse_cited_response(response)

Best Practices

• Chunk tài liệu hợp lý: Tài liệu quá dài khó cite chính xác — chia thành sections có tiêu đề rõ ràng
• Đặt tiêu đề document rõ ràng: Field title xuất hiện trong citations — đặt tên mô tả ("Điều lệ công ty 2024" thay vì "doc1.pdf")
• System prompt nghiêm ngặt: Yêu cầu Claude chỉ dùng thông tin từ tài liệu, không suy đoán thêm
• Verify citations programmatically: So sánh quote trong citation với text gốc để phát hiện hallucination

Citations API biến Claude thành công cụ research và fact-checking đáng tin cậy. Đặc biệt hữu ích cho legal tech, medical information systems, và enterprise knowledge bases. Kết hợp với Batch Processing để xử lý nhiều documents cùng lúc.

Bài viết liên quan

• Contextual Retrieval — Nâng cấp RAG với embeddings ngữ cảnh
• RAG với Pinecone + Claude — Vector database cho AI
• Multi-Document Agent — Truy vấn nhiều tài liệu với LlamaIndex
• Claude cho Engineering: Thiết kế kiến trúc hệ thống
• Claude Plugins: Tạo Cowork Plugin tùy chỉnh