Khi mình lần đầu nghe hai cụm từ "function calling" và "JSON Schema", mình đã lầm tưởng đó là thứ chỉ dành cho kỹ sư Google hay nhân viên OpenAI. Mình thử mở tài liệu của Anthropic xem, đọc xong thì gãi đầu bó tay vì toàn thuật ngữ chuyên ngành. Phải đến khi ngồi xuống nghịch thử qua nền tảng HolySheep AI, mình mới vỡ ra: bạn chỉ cần biết copy-paste, dán API key, rồi gọi một endpoint duy nhất là xong. Bài viết này mình sẽ dẫn bạn đi từ con số 0 đến lúc tự tin ép Claude Opus 4.7 trả về JSON đúng cấu trúc mình muốn, hoàn toàn không cần biết trước bất cứ thứ gì.
[Hình ảnh minh họa: chụp màn hình trang chủ HolySheep AI với nút "Đăng ký" màu xanh ở góc phải — đây là nơi bạn tạo tài khoản miễn phí.]
1. Function Calling và JSON Schema — Hiểu trong 2 phút
Hãy tưởng tượng bạn ra quán cà phê và nói: "Cho tôi một ly latte, không đường, size lớn, dùng tại quán". Barista hiểu chính xác bạn muốn gì vì bạn đã mô tả rõ ràng. Function Calling cũng vậy: bạn mô tả cho AI biết "tôi có một công cụ đặt vé máy bay, nó cần các tham số như thế này", rồi AI sẽ quyết định khi nào cần gọi và truyền tham số gì. JSON Schema là phần "mô tả cấu trúc" đó — một bản hợp đồng nói rằng "dữ liệu trả về phải có dạng thế này, không được lệch".
Claude Opus 4.7 hỗ trợ chế độ response_format với type: "json_schema", nghĩa là bạn có thể ép mô hình 100% trả về JSON khớp schema, không cần dùng regex hậu xử lý, không cần hy vọng may rủi.
2. Chuẩn bị — 4 thứ cần có trước khi bắt đầu
- Tài khoản HolySheep AI: đăng ký miễn phí tại HolySheep, nhận ngay tín dụng thử nghiệm.
- Python 3.8 trở lên: tải tại python.org nếu chưa có.
- Trình soạn code: khuyên dùng VS Code (miễn phí).
- Một ly cà phê ☕ — vì sao? Vì từ đầu đến cuối bài này bạn sẽ mất khoảng 15 phút thôi.
[Hình ảnh minh họa: giao diện VS Code với file claude_demo.py đang mở, terminal ở dưới.]
3. Bước 1 — Cài đặt và viết đoạn code đầu tiên
Mở Terminal (hoặc CMD trên Windows) và gõ:
pip install requests
Tạo một file mới tên claude_demo.py và dán đoạn code dưới đây vào. Đoạn này chỉ làm một việc duy nhất: gửi câu hỏi "Bạn tên gì?" tới Claude Opus 4.7 và in câu trả lời ra màn hình.
import requests
import json
API_KEY = "YOUR_HOLYSHEEP_API_KEY"
BASE_URL = "https://api.holysheep.ai/v1"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
data = {
"model": "claude-opus-4-7",
"messages": [
{"role": "user", "content": "Xin chào, bạn tên gì?"}
]
}
response = requests.post(
f"{BASE_URL}/chat/completions",
headers=headers,
json=data,
timeout=30
)
print(json.dumps(response.json(), indent=2, ensure_ascii=False))
Chạy file bằng lệnh python claude_demo.py. Nếu mọi thứ ổn, bạn sẽ thấy JSON trả về trong terminal với nội dung kiểu: "Bạn tôi tên Claude, một trợ lý AI được tạo bởi Anthropic...". Từ giây phút này, bạn đã gọi được Claude Opus 4.7 thành công — quá dễ đúng không?
4. Bước 2 — Ép đầu ra JSON Schema
Giả sử bạn đang xây chatbot bán hàng và cần trích xuất thông tin khách hàng từ câu chat. Bạn không muốn mô hình trả lời lan man, bạn muốn JSON thuần túy. Đây là cách làm:
import requests
import json
API_KEY = "YOUR_HOLYSHEEP_API_KEY"
BASE_URL = "https://api.holysheep.ai/v1"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
json_schema = {
"name": "thong_tin_khach_hang",
"strict": True,
"schema": {
"type": "object",
"properties": {
"ho_ten": {"type": "string", "description": "Họ và tên đầy đủ"},
"tuoi": {"type": "integer", "minimum": 0, "maximum": 150},
"thanh_pho": {"type": "string"},
"so_dien_thoai": {"type": ["string", "null"]}
},
"required": ["ho_ten", "tuoi", "thanh_pho"],
"additionalProperties": False
}
}
data = {
"model": "claude-opus-4-7",
"messages": [
{
"role": "user",
"content": "Trích xuất thông tin từ câu sau: 'Chào shop, mình tên Lan, 27 tuổi, ở TP.HCM, SĐT 0901234567.'"
}
],
"response_format": {
"type": "json_schema",
"json_schema": json_schema
}
}
response = requests.post(
f"{BASE_URL}/chat/completions",
headers=headers,
json=data,
timeout=30
)
ket_qua = response.json()["choices"][0]["message"]["content"]
parsed = json.loads(ket_qua)
print(json.dumps(parsed, indent=2, ensure_ascii=False))
Kết quả in ra màn hình sẽ là:
{
"ho_ten": "Lan",
"tuoi": 27,
"thanh_pho": "TP.HCM",
"so_dien_thoai": "0901234567"
}
Đẹp không? Mô hình không thể nào trả lời sai schema vì Claude Opus 4.7 được ép 100% tuân thủ cấu trúc thong_tin_khach_hang bạn vừa khai báo.
5. Bước 3 — Function Calling thực chiến
Function Calling khác JSON Schema ở chỗ: thay vì chỉ trả về dữ liệu, mô hình có thể yêu cầu gọi một hàm cụ thể (ví dụ: dat_ve_may_bay, kiem_tra_ton_kho, tao_don_hang). Bạn khai báo "danh sách công cụ", Claude sẽ quyết định khi nào cần dùng và truyền tham số gì.
import requests
import json
API_KEY = "YOUR_HOLYSHEEP_API_KEY"
BASE_URL = "https://api.holysheep.ai/v1"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
tools = [
{
"type": "function",
"function": {
"name": "dat_ve_may_bay",
"description": "Đặt vé máy bay cho khách hàng",
"parameters": {
"type": "object",
"properties": {
"diem_di": {"type": "string", "description": "Mã sân bay hoặc tên thành phố khởi hành"},
"diem_den": {"type": "string", "description": "Mã sân bay hoặc tên thành phố đến"},
"ngay_khoi_hanh": {"type": "string", "description": "Ngày đi, định dạng YYYY-MM-DD"},
"so_luong_ve": {"type": "integer", "minimum": 1, "maximum": 9},
"hang_ve": {"type": "string", "enum": ["pho_thong", "thuong_gia", "nhat"]}
},
"required": ["diem_di", "diem_den", "ngay_khoi_hanh", "so_luong_ve"]
}
}
}
]
data = {
"model": "claude-opus-4-7",
"messages": [
{"role": "user", "content": "Tôi muốn đặt 2 vé hạng phổ thông từ Hà Nội đi Đà Nẵng vào ngày 15/06/2026."}
],
"tools": tools,
"tool_choice": "auto"
}
response = requests.post(
f"{BASE_URL}/chat/completions",
headers=headers,
json=data,
timeout=30
)
result = response.json()
tool_calls = result["choices"][0]["message"].get("tool_calls", [])
if tool_calls:
for call in tool_calls:
func_name = call["function"]["name"]
func_args = json.loads(call["function"]["arguments"])
print(f"Mô hình yêu cầu gọi hàm: {func_name}")
print(f"Tham số: {json.dumps(func_args, indent=2, ensure_ascii=False)}")
else:
print("Mô hình không gọi hàm nào, nội dung trả lời:")
print(result["choices"][0]["message"]["content"])
Khi chạy, bạn sẽ thấy:
Mô hình yêu cầu gọi hàm: dat_ve_may_bay
Tham số: {
"diem_di": "Hà Nội",
"diem_den": "Đà Nẵng",
"ngay_khoi_hanh": "2026-06-15",
"so_luong_ve": 2,
"hang_ve": "pho_thong"
}
Tới đây bạn chỉ cần nhận func_args, gọi hàm Python thật của bạn (gọi database, gọi API hãng hàng không), rồi trả kết quả ngược lại cho mô hình để nó phản hồi người dùng bằng ngôn ngữ tự nhiên. Đó chính là toàn bộ vòng khép kín của Function Calling.
[Hình ảnh minh họa: sơ đồ luồng "User → Claude Opus 4.7 → Function → Database → Response" vẽ tay trên giấy A4.]
6. Kết hợp JSON Schema + Function Calling
Bạn có thể kết hợp cả hai: tools để mô hình gọi hàm, đồng thời response_format để ép phần text trả lời cuối cùng theo schema. Đây là kiểu pipeline mình hay dùng cho chatbot chăm sóc khách hàng:
- Bước 1: Khách hỏi → mô hình gọi
tra_cuu_don_hang. - Bước 2: Hệ thống trả về dữ liệu đơn hàng.
- Bước 3: Mô hình sinh câu trả lời dạng JSON Schema
{trang_thai, ma_van_don, ngay_du_kien}. - Bước 4: Frontend nhận JSON, hiển thị đẹp lên giao diện.
Lỗi thường gặp và cách khắc phục
Lỗi 1 — 401 Unauthorized: Sai hoặc thiếu API key
Triệu chứng: Terminal in ra {"error": {"code": 401, "message": "Invalid API key"}}. Nguyên nhân phổ biến nhất là copy nhầm key, dư dấu cách, hoặc dùng key của nền tảng khác (như key của OpenAI hay Anthropic trực tiếp).
import os
import requests
API_KEY = os.getenv("HOLYSHEEP_API_KEY", "YOUR_HOLYSHEEP_API_KEY").strip()
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
response = requests.post(
"https://api.holysheep.ai/v1/chat/completions",
headers=headers,
json={"model": "claude-opus-4-7", "messages": [{"role": "user", "content": "test"}]},
timeout=30
)
if response.status_code == 401:
print("Key sai. Vui lòng đăng nhập HolySheep AI dashboard, copy lại key mới.")
else:
print(response.json())
Mẹo nhỏ: lưu key vào biến môi trường thay vì ghi thẳng vào code, như vậy không ai lộ key khi bạn push lên GitHub.