OpenAI Function Calling 완전 가이드: 도구 정의부터 결과 파싱까지

안녕하세요, 개발자 여러분! 오늘은 OpenAI API의 가장 강력한 기능 중 하나인 Function Calling을 초보자도 쉽게 이해할 수 있도록一步一步 설명드리겠습니다. 이 기능을 사용하면 AI 모델이 개발자가 정의한 도구를 호출하여 실제 작업을 수행할 수 있게 됩니다.

Function Calling이란 무엇인가?

Function Calling은 AI 모델이 사용자의 질문을 이해하고, 적절한 도구(함수)를 선택하여 호출한 후, 그 결과를 사용자에게 돌려주는 기능입니다. 예를 들어 사용자가 "내일 서울 날씨 알려줘"라고 물으면, AI는 날씨 정보를 가져오는 함수를 호출하고 그 결과를 정리해서 보여줍니다.

Function Calling이 필요한 이유

• 실시간 정보 제공: 학습 데이터에 없는 최신 정보를 가져올 수 있습니다
• 자동화된 작업: 계산, 검색, 데이터베이스 查询 등을 자동으로 처리합니다
• 정확한 응답: 모델이幻觉(그림짓기)을 하지 않고 검증된 데이터를 사용합니다

1단계: HolySheep AI에서 API 키 발급받기

먼저 HolySheep AI에서 API 키를 발급받아야 합니다. HolySheep AI는 해외 신용카드 없이도 로컬 결제가 가능하며, 단일 API 키로 GPT-4.1, Claude, Gemini, DeepSeek 등 모든 주요 모델을 통합하여 사용할 수 있습니다.

1. 지금 가입 페이지에 접속합니다
2. 이메일과 비밀번호로 회원가입을 완료합니다
3. 대시보드에서 "API Keys" 메뉴를 클릭합니다
4. "새 키 생성" 버튼을 눌러 API 키를 발급받습니다

💡 화면 구성 이미지 힌트: 대시보드 좌측 사이드바에 "API Keys" 메뉴가 파란색 아이콘과 함께 표시되어 있습니다

2단계: 사용할 도구(함수) 정의하기

Function Calling의 핵심은 모델이 호출할 수 있는 도구를 미리 정의하는 것입니다. 도구는 JSON 형태로 정의하며, 이름, 설명, 매개변수 등을 포함합니다.

도구 정의 기본 구조

import openai

client = openai.OpenAI(
    api_key="YOUR_HOLYSHEEP_API_KEY",
    base_url="https://api.holysheep.ai/v1"
)

도구 정의 배열
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "특정 도시의 현재 날씨를 조회합니다",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "날씨를 조회할 도시 이름"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "온도 단위 (기본값: celsius)"
                    }
                },
                "required": ["city"]
            }
        }
    }
]

실용적인 도구 예제들

여러분이 실제로 사용할 수 있는 도구들을 준비했습니다. 아래 코드에는 날씨 查询, 계산기, 할 일 관리 도구가 포함되어 있습니다.

import openai
import json

client = openai.OpenAI(
    api_key="YOUR_HOLYSHEEP_API_KEY",
    base_url="https://api.holysheep.ai/v1"
)

실용적인 도구 정의 예제
tools = [
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "수학 계산식을 계산합니다",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {
                        "type": "string",
                        "description": "계산할 수학 식 (예: 2 + 3 * 4)"
                    }
                },
                "required": ["expression"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_products",
            "description": "온라인 상점에서 제품을 검색합니다",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "검색할 제품 키워드"
                    },
                    "max_results": {
                        "type": "integer",
                        "description": "최대 결과 수 (기본값: 5)"
                    }
                },
                "required": ["query"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "add_todo",
            "description": "할 일 목록에 새 항목을 추가합니다",
            "parameters": {
                "type": "object",
                "properties": {
                    "task": {
                        "type": "string",
                        "description": "할 일 내용"
                    },
                    "priority": {
                        "type": "string",
                        "enum": ["high", "medium", "low"],
                        "description": "우선순위 (기본값: medium)"
                    }
                },
                "required": ["task"]
            }
        }
    }
]

도구 정의 완료 메시지
print("도구 정의가 완료되었습니다!")
print(f"총 {len(tools)}개의 도구를 사용할 수 있습니다: calculate, search_products, add_todo")

3단계: AI에게 질문하고 함수 호출하기

이제 도구를 정의했으니, 사용자의 질문에 따라 AI가 적절한 함수를 호출하도록 합시다.

기본 호출 방식

import openai

client = openai.OpenAI(
    api_key="YOUR_HOLYSHEEP_API_KEY",
    base_url="https://api.holysheep.ai/v1"
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "수학 계산식을 계산합니다",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {
                        "type": "string",
                        "description": "계산할 수학 식"
                    }
                },
                "required": ["expression"]
            }
        }
    }
]

사용자의 질문
user_message = "255 * 37을 계산해줘"

AI에게 질문 보내기
response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[
        {"role": "user", "content": user_message}
    ],
    tools=tools,
    tool_choice="auto"
)

print("AI 응답 확인:")
print(response.choices[0].message)

💡 예상 출력 이미지 힌트: 콘솔에 tool_calls 속성에 함수 이름과 인수가 포함된 메시지가 표시됩니다

4단계: 함수 실행하고 결과 파싱하기

AI가 함수를 호출했다면, 이제 해당 함수를 실제로 실행하고 결과를 AI에게 다시 전달해야 합니다.

완전한 워크플로우

import openai
import json

client = openai.OpenAI(
    api_key="YOUR_HOLYSHEEP_API_KEY",
    base_url="https://api.holysheep.ai/v1"
)

도구 정의
tools = [
    {
        "type": "function",
        "function": {
            "name": "calculate",
            "description": "수학 계산식을 계산합니다",
            "parameters": {
                "type": "object",
                "properties": {
                    "expression": {
                        "type": "string",
                        "description": "계산할 수학 식"
                    }
                },
                "required": ["expression"]
            }
        }
    }
]

실제 함수 실행 (여러분이 구현하는 로직)
def execute_function(name, arguments):
    if name == "calculate":
        expression = arguments.get("expression")
        try:
            result = eval(expression)  # 실제 계산 수행
            return {"result": result, "success": True}
        except Exception as e:
            return {"error": str(e), "success": False}
    return {"error": "알 수 없는 함수", "success": False}

첫 번째 요청: AI가 함수를 호출하도록 요청
user_message = "255 * 37을 계산해줘"

response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[{"role": "user", "content": user_message}],
    tools=tools,
    tool_choice="auto"
)

assistant_message = response.choices[0].message

도구 호출이 있는지 확인
if assistant_message.tool_calls:
    print("함수 호출 감지!")
    
    # 함수 실행 결과 수집
    tool_results = []
    messages = [{"role": "user", "content": user_message}]
    
    for tool_call in assistant_message.tool_calls:
        func_name = tool_call.function.name
        func_args = json.loads(tool_call.function.arguments)
        
        print(f"호출 함수: {func_name}")
        print(f"전달 인자: {func_args}")
        
        # 함수 실행
        result = execute_function(func_name, func_args)
        print(f"실행 결과: {result}")
        
        # 결과를 messages에 추가
        messages.append({
            "role": assistant_message.role,
            "content": None,
            "tool_calls": assistant_message.tool_calls
        })
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(result)
        })
    
    # 두 번째 요청: 함수 결과를 포함하여 최종 답변 요청
    final_response = client.chat.completions.create(
        model="gpt-4.1",
        messages=messages,
        tools=tools
    )
    
    print("\n최종 답변:")
    print(final_response.choices[0].message.content)
else:
    print("함수 호출 없음 - 일반 대화 응답:")
    print(assistant_message.content)

5단계: 실제 프로젝트에 적용하기

위에서 배운 내용을 바탕으로 실전에서 바로 사용할 수 있는 템플릿을 만들어보겠습니다.

万能 도구 호출 핸들러 클래스

import openai
import json
from typing import Dict, Any, Callable

class FunctionCallingAssistant:
    def __init__(self, api_key: str, model: str = "gpt-4.1"):
        self.client = openai.OpenAI(
            api_key=api_key,
            base_url="https://api.holysheep.ai/v1"
        )
        self.model = model
        self.tools = []
        self.function_map: Dict[str, Callable] = {}
    
    def register_function(self, name: str, handler: Callable, schema: Dict):
        """도구 등록 메서드"""
        self.function_map[name] = handler
        self.tools.append({
            "type": "function",
            "function": {
                "name": name,
                **schema
            }
        })
    
    def chat(self, user_message: str) -> str:
        """대화 메서드 - 함수 호출 자동 처리"""
        messages = [{"role": "user", "content": user_message}]
        
        while True:
            response = self.client.chat.completions.create(
                model=self.model,
                messages=messages,
                tools=self.tools if self.tools else None
            )
            
            assistant_message = response.choices[0].message
            
            if not assistant_message.tool_calls:
                # 함수 호출 없음 - 일반 응답
                return assistant_message.content
            
            # 함수 호출 처리
            for tool_call in assistant_message.tool_calls:
                func_name = tool_call.function.name
                func_args = json.loads(tool_call.function.arguments)
                
                # 등록된 함수 실행
                if func_name in self.function_map:
                    result = self.function_map[func_name](**func_args)
                else:
                    result = {"error": f"함수 {func_name}이 등록되지 않았습니다"}
                
                # 결과 메시지 추가
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": json.dumps(result)
                })
            
            messages.insert(0, {"role": "user", "content": user_message})

사용 예제
assistant = FunctionCallingAssistant(
    api_key="YOUR_HOLYSHEEP_API_KEY"
)

도구 등록
assistant.register_function(
    name="get_exchange_rate",
    handler=lambda base, target: {"rate": 1340.5, "base": base, "target": target},
    schema={
        "description": "환율을 조회합니다",
        "parameters": {
            "type": "object",
            "properties": {
                "base": {"type": "string", "description": "기준 화폐 (예: USD)"},
                "target": {"type": "string", "description": "목표 화폐 (예: KRW)"}
            },
            "required": ["base", "target"]
        }
    }
)

대화 실행
response = assistant.chat("1달러는 몇 원이야?")
print(response)

Function Calling 최적화 팁

• 도구 설명을 자세히 작성하세요: 모델이 언제 이 도구를 호출할지 정확히 이해할 수 있게 명확한 설명을 작성합니다
• 필수 매개변수만 정의하세요: 불필요한 required 필드는 최소화하여 유연성을 높입니다
• enum을 활용하세요: 가능한 값들을 미리 정의하면 모델이 더 정확한 선택을 합니다
• 결과를 구조화하세요: 함수 실행 결과는 일관된 JSON 구조로 반환하는 것이 좋습니다

자주 발생하는 오류 해결

1. "Invalid API key" 오류

문제: API 키가 잘못되었거나 만료된 경우 발생합니다.

해결 방법: HolySheep AI 대시보드에서 새로운 API 키를 생성하고, 코드에서 YOUR_HOLYSHEEP_API_KEY를 새로 발급받은 키로 교체하세요. 키 앞뒤에 빈칸이나 따옴표가 없는지 확인하세요.

2. "tool_calls is undefined" 오류

문제: 모델이 함수를 호출하지 않고 일반 텍스트로만 응답한 경우 발생합니다.

해결 방법: 도구 정의의 description이 충분히 명확한지 확인하세요. 모델이 함수를 호출해야 하는 이유를 명시적으로 작성하면 호출 확률이 높아집니다. 또한 모델이 최신 버전(gpt-4.1 이상)인지 확인하세요.

3. JSON 파싱 오류

문제: json.loads(tool_call.function.arguments)에서 오류가 발생합니다.

해결 방법: 함수 매개변수 정의의 type이 정확한지 확인하세요. 특히 integer, string, boolean 등의 타입이 올바르게 정의되어야 합니다. 디버깅을 위해 print(tool_call.function.arguments)로 원본 데이터를 먼저 확인하세요.

4. 함수 실행 후 응답이 없음

문제: 함수를 실행했지만 두 번째 요청에서 응답이 없습니다.

해결 방법: messages 배열에 모든 대화 기록이 포함되어야 합니다. 원본 사용자 메시지, 어시스턴트의 도구 호출 메시지, 도구 결과 메시지가 순서대로 모두 포함되어야 하며, tool_call_id가 올바른지 확인하세요.

5. "model not found" 오류

문제: 지정한 모델 이름이 HolySheep AI에서 지원되지 않습니다.

해결 방법: HolySheep AI에서 지원하는 모델 목록을 확인하세요. 일반적으로 gpt-4.1, gpt-4o, claude-sonnet-4-20250514 등의 이름을 사용합니다. 모델 이름에 띄어쓰기나 오타가 없는지 확인하세요.

정리하며

오늘 우리는 Function