Function Calling là gì và tại sao bạn cần biết?

Khi tôi lần đầu tiếp xúc với AI, tôi tưởng chatbot chỉ trả lời text thuần túy. Nhưng thực tế, AI có thể làm được nhiều hơn thế — đặc biệt khi bạn dùng Function Calling (gọi hàm). Đây là cách để AI "ra lệnh" cho máy tính thực hiện tác vụ cụ thể như tra cứu thời tiết, tìm kiếm thông tin, hoặc xử lý dữ liệu. Trong bài viết này, tôi sẽ hướng dẫn bạn từ con số 0 — không cần biết gì về lập trình hay API. Bạn sẽ hiểu cách định nghĩa tool (công cụ) và gắn nó vào Gemini để AI có thể thực hiện các tác vụ thông minh.
💡 Mẹo cho người mới: Hãy chuẩn bị một ly cà phê và đọc từng bước chậm rãi. Code mẫu trong bài có thể copy-paste trực tiếp và chạy được ngay.

Chuẩn Bị Trước Khi Bắt Đầu

1. Đăng ký tài khoản HolySheep AI

Trước tiên, bạn cần một nơi để gọi API. Tôi khuyên bạn nên đăng ký tại đây vì:

2. Lấy API Key

Sau khi đăng ký thành công:
  1. Đăng nhập vào dashboard HolySheep
  2. Tìm mục "API Keys" trong thanh điều hướng
  3. Click "Create New Key" và đặt tên dễ nhớ
  4. COPY ngay — API key chỉ hiển thị một lần duy nhất
📸 [Ảnh chụp màn hình: Vị trí API Keys trong dashboard HolySheep — góc phải màn hình, biểu tượng chìa khóa]

3. Cài đặt công cụ cần thiết

Bạn cần Python (phiên bản 3.8 trở lên) và thư viện requests. Mở terminal (cmd) và gõ: 
pip install requests

Hiểu Về Cấu Trúc Tool Trong Gemini

Trước khi viết code, hãy hiểu "tool" là gì. Đơn giản như sau: Tool = Tên hành động + Mô tả + Tham số cần thiết Ví dụ thực tế: Khi bạn hỏi "Hà Nội nay mưa không?", AI cần:

Cấu trúc JSON của một Tool

Dưới đây là template chuẩn: 
{
  "name": "ten_ham_cua_ban",
  "description": "Giải thích AI hiểu hàm này làm gì (viết tự nhiên, dễ hiểu)",
  "parameters": {
    "type": "object",
    "properties": {
      "ten_tham_so": {
        "type": "string/integer/boolean",
        "description": "Tham số này dùng để làm gì"
      }
    },
    "required": ["ten_tham_so"]
  }
}

Bước 1: Tạo Tool Tra Cứu Thời Tiết

Đây là ví dụ kinh điển nhất để học Function Calling. Tôi sẽ hướng dẫn từng dòng code.

Code hoàn chỉnh

import requests
import json


============ CẤU HÌNH ============

BASE_URL = "https://api.holysheep.ai/v1"
API_KEY = "YOUR_HOLYSHEEP_API_KEY"  # Thay bằng key của bạn


============ ĐỊNH NGHĨA TOOL ============

def get_weather_tool():
    """Hàm này trả về cấu trúc JSON của tool thời tiết"""
    return {
        "name": "get_weather",
        "description": "Tra cứu thời tiết hiện tại của một thành phố. Trả về nhiệt độ, độ ẩm, và mô tả thời tiết.",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "Tên thành phố cần tra cứu thời tiết (VD: Hà Nội, TP.HCM)"
                }
            },
            "required": ["city"]
        }
    }


============ GỌI API ============

def ask_gemini_about_weather(user_question):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "model": "gemini-2.0-flash",
        "messages": [
            {
                "role": "user",
                "content": user_question
            }
        ],
        "tools": [
            {
                "type": "function",
                "function": get_weather_tool()
            }
        ],
        "tool_choice": "auto"
    }
    
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers=headers,
        json=payload
    )
    
    return response.json()


============ CHẠY THỬ ============

if __name__ == "__main__":
    # Hỏi AI về thời tiết Hà Nội
    result = ask_gemini_about_weather("Hà Nội hôm nay thời tiết thế nào?")
    print(json.dumps(result, indent=2, ensure_ascii=False))
📸 [Ảnh chụp màn hình: Kết quả trả về từ API — hiển thị JSON response trong terminal]

Giải thích từng phần quan trọng

  1. BASE_URL: Luôn dùng https://api.holysheep.ai/v1 — đây là endpoint chuẩn của HolySheep
  2. tools: Mảng chứa các tool định nghĩa sẵn
  3. tool_choice: "auto": AI tự quyết định có dùng tool hay không

Bước 2: Tạo Tool Tính Toán Nâng Cao

Ngoài tra cứu, bạn có thể tạo tool xử lý tính toán phức tạp mà AI không làm được tự nhiên. 
import requests
import json

BASE_URL = "https://api.holysheep.ai/v1"
API_KEY = "YOUR_HOLYSHEEP_API_KEY"


============ TOOL TÍNH CHI PHÍ MÁY BAY ============

def calculate_flight_cost_tool():
    """Định nghĩa tool tính chi phí vé máy bay"""
    return {
        "name": "calculate_flight_cost",
        "description": "Tính tổng chi phí chuyến bay bao gồm thuế và phí xăng dầu",
        "parameters": {
            "type": "object",
            "properties": {
                "base_price": {
                    "type": "number",
                    "description": "Giá vé cơ bản (USD)"
                },
                "passengers": {
                    "type": "integer",
                    "description": "Số lượng hành khách"
                },
                "tax_rate": {
                    "type": "number",
                    "description": "Tỷ lệ thuế (ví dụ: 0.15 cho 15%)"
                }
            },
            "required": ["base_price", "passengers"]
        }
    }


Tool chuyển đổi tiền tệ

def currency_converter_tool():
    """Định nghĩa tool chuyển đổi tiền tệ"""
    return {
        "name": "convert_currency",
        "description": "Chuyển đổi số tiền từ đơn vị này sang đơn vị khác",
        "parameters": {
            "type": "object",
            "properties": {
                "amount": {
                    "type": "number",
                    "description": "Số tiền cần chuyển đổi"
                },
                "from_currency": {
                    "type": "string",
                    "description": "Tiền tệ nguồn (USD, CNY, VND)"
                },
                "to_currency": {
                    "type": "string",
                    "description": "Tiền tệ đích (USD, CNY, VND)"
                }
            },
            "required": ["amount", "from_currency", "to_currency"]
        }
    }

def ask_with_tools(user_question):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "model": "gemini-2.0-flash",
        "messages": [
            {"role": "user", "content": user_question}
        ],
        "tools": [
            {"type": "function", "function": calculate_flight_cost_tool()},
            {"type": "function", "function": currency_converter_tool()}
        ]
    }
    
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers=headers,
        json=payload
    )
    
    return response.json()


============ CHẠY THỬ ============

if __name__ == "__main__":
    questions = [
        "Vé máy bay 200 USD cho 2 người, thuế 15% thì tổng bao nhiêu?",
        "Chuyển 500 USD sang VND, tỷ giá bao nhiêu?"
    ]
    
    for q in questions:
        print(f"\n🤔 Câu hỏi: {q}")
        result = ask_with_tools(q)
        print(json.dumps(result, indent=2, ensure_ascii=False))

Bước 3: Xử Lý Kết Quả Từ Function Call

Khi AI quyết định dùng tool, nó sẽ trả về một tool_calls. Bạn cần xử lý và gửi lại kết quả cho AI. 
import requests
import json

BASE_URL = "https://api.holysheep.ai/v1"
API_KEY = "YOUR_HOLYSHEEP_API_KEY"


============ ĐỊNH NGHĨA TOOL ============

def get_weather_tool():
    return {
        "name": "get_weather",
        "description": "Tra cứu thời tiết của một thành phố",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "Tên thành phố cần tra cứu"
                }
            },
            "required": ["city"]
        }
    }


============ XỬ LÝ TOOL CALL ============

def execute_tool(tool_name, arguments):
    """Hàm thực thi tool và trả về kết quả"""
    
    # Mô phỏng kết quả tra cứu thời tiết
    weather_data = {
        "Hà Nội": {"temp": 28, "humidity": 75, "condition": "Nắng nóng"},
        "TP.HCM": {"temp": 33, "humidity": 80, "condition": "Mưa rào"},
        "Đà Nẵng": {"temp": 30, "humidity": 70, "condition": "Nhiều mây"}
    }
    
    if tool_name == "get_weather":
        city = arguments.get("city", "")
        if city in weather_data:
            return weather_data[city]
        else:
            return {"error": f"Không tìm thấy dữ liệu cho {city}"}
    
    return {"error": "Tool không được hỗ trợ"}

def chat_with_function_calling(user_message):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    
    messages = [{"role": "user", "content": user_message}]
    
    # Lần gọi đầu tiên - AI quyết định dùng tool
    payload = {
        "model": "gemini-2.0-flash",
        "messages": messages,
        "tools": [{"type": "function", "function": get_weather_tool()}]
    }
    
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers=headers,
        json=payload
    ).json()
    
    assistant_message = response["choices"][0]["message"]
    messages.append(assistant_message)
    
    # Nếu có tool_calls, xử lý và gửi lại
    if "tool_calls" in assistant_message:
        for tool_call in assistant_message["tool_calls"]:
            tool_name = tool_call["function"]["name"]
            arguments = json.loads(tool_call["function"]["arguments"])
            
            print(f"🔧 AI muốn gọi tool: {tool_name}")
            print(f"📋 Tham số: {arguments}")
            
            # Thực thi tool
            tool_result = execute_tool(tool_name, arguments)
            print(f"✅ Kết quả: {tool_result}")
            
            # Gửi kết quả cho AI
            messages.append({
                "role": "tool",
                "tool_call_id": tool_call["id"],
                "content": json.dumps(tool_result)
            })
        
        # Gọi lại API với kết quả tool
        payload["messages"] = messages
        final_response = requests.post(
            f"{BASE_URL}/chat/completions",
            headers=headers,
            json=payload
        ).json()
        
        return final_response["choices"][0]["message"]["content"]
    
    return assistant_message["content"]


============ CHẠY THỬ ============

if __name__ == "__main__":
    result = chat_with_function_calling("Thời tiết Hà Nội như thế nào?")
    print(f"\n🤖 Trả lời cuối cùng: {result}")
📸 [Ảnh chụp màn hình: Luồng hoạt động — câu hỏi → AI gọi tool → kết quả → câu trả lời hoàn chỉnh]

So Sánh Chi Phí Khi Sử Dụng HolySheep

Đây là lý do tôi chọn HolySheep cho các dự án cá nhân:
Nền tảngGemini 2.5 FlashTiết kiệm
OpenAI/Anthropic$15-30/MTok—
HolySheep AI$2.50/MTok85%+
Với một ứng dụng nhỏ xử lý 1 triệu token/tháng, bạn chỉ mất khoảng $2.50 thay vì $15-30.
💰 Bonus: Đăng ký mới tại HolySheep AI ngay hôm nay để nhận tín dụng miễn phí — đủ để bạn thử nghiệm tất cả các ví dụ trong bài viết này!

Lỗi Thường Gặp Và Cách Khắc Phục

Qua quá trình sử dụng, tôi đã gặp nhiều lỗi và tổng hợp lại đây để bạn không phải mất thời gian debug như tôi.

Lỗi 1: "401 Unauthorized" - API Key Sai Hoặc Hết Hạn

# ❌ SAI - Copy thừa khoảng trắng hoặc sai định dạng
headers = {
    "Authorization": "Bearer YOUR_HOLYSHEEP_API_KEY "  # Thừa dấu cách!
}


✅ ĐÚNG - Kiểm tra kỹ key không có khoảng trắng thừa

headers = {
    "Authorization": f"Bearer {API_KEY.strip()}"
}
Cách khắc phục:
  1. Kiểm tra lại API key trong dashboard HolySheep
  2. Đảm bảo không copy dư khoảng trắng
  3. Nếu key hết hạn, tạo key mới tại mục "API Keys"

Lỗi 2: "400 Bad Request" - Tool Định Nghĩa Sai Cấu Trúc

# ❌ SAI - Thiếu "type" trong parameters
tool = {
    "name": "get_weather",
    "description": "Tra cứu thời tiết",
    "parameters": {
        "properties": {  # THIẾU: "type": "object"
            "city": {"type": "string"}
        }
    }
}


✅ ĐÚNG - Đủ các trường bắt buộc

tool = {
    "name": "get_weather",
    "description": "Tra cứu thời tiết",
    "parameters": {
        "type": "object",  # BẮT BUỘC
        "properties": {
            "city": {"type": "string", "description": "Tên thành phố"}
        },
        "required": ["city"]  # BẮT BUỘC nếu cần
    }
}
Cách khắc phục:
  1. Luôn đảm bảo có "type": "object" trong parameters
  2. Kiểm tra syntax JSON bằng công cụ như jsonlint.com
  3. Copy template trong bài viết này và chỉnh sửa tên/tham số

Lỗi 3: "429 Rate Limit Exceeded" - Gọi API Quá Nhiều

import time
from functools import wraps

def rate_limit(max_calls=60, period=60):
    """Decorator giới hạn số lần gọi API"""
    def decorator(func):
        calls = []
        @wraps(func)
        def wrapper(*args, **kwargs):
            now = time.time()
            calls[:] = [t for t in calls if now - t < period]
            
            if len(calls) >= max_calls:
                wait_time = period - (now - calls[0])
                print(f"⏳ Đợi {wait_time:.1f} giây...")
                time.sleep(wait_time)
            
            calls.append(time.time())
            return func(*args, **kwargs)
        return wrapper
    return decorator


Cách sử dụng

@rate_limit(max_calls=30, period=60)  # Tối đa 30 lần/phút
def call_gemini_api(question):
    # Gọi API ở đây
    pass
Cách khắc phục:
  1. Thêm delay giữa các lần gọi: time.sleep(1)
  2. Sử dụng caching để không gọi lại cùng một câu hỏi
  3. Nâng cấp gói API nếu cần xử lý khối lượng lớn
  4. Theo dõi usage trong dashboard HolySheep

Lỗi 4: AI Không Gọi Tool - Tool Description Không Rõ Ràng

# ❌ SAI - Mô tả chung chung, AI không hiểu khi nào dùng
tool = {
    "name": "search",
    "description": "Tìm kiếm thông tin",
    # AI sẽ không biết khi nào cần dùng tool này!
}


✅ ĐÚNG - Mô tả cụ thể khi nào và làm gì

tool = {
    "name": "search_restaurant",
    "description": "Tìm kiếm nhà hàng theo tên, địa điểm, hoặc loại món ăn. "
                   "Dùng khi người dùng hỏi về địa điểm ăn uống, "
                   "muốn tìm nhà hàng cụ thể, hoặc hỏi về menu.",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "Từ khóa tìm kiếm"},
            "location": {"type": "string", "description": "Khu vực tìm kiếm"}
        },
        "required": ["query"]
    }
}
Cách khắc phục:
  1. Viết description dài hơn, mô tả rõ ngữ cảnh sử dụng
  2. Đưa vào ví dụ: "Dùng khi người dùng muốn..."
  3. Đặt tên function rõ ràng, có tính mô tả

Tổng Kết

Qua bài viết này, bạn đã học được: Bây giờ, hãy bắt đầu xây dựng ứng dụng AI của riêng bạn. Đừng quên — thực hành là cách học nhanh nhất. Copy code, chạy thử, và tự do sáng tạo! 👉 Đăng ký HolySheep AI — nhận tín dụng miễn phí khi đăng ký

Tài nguyên liên quan

Bài viết liên quan