함수 호출 (Function Calling)

함수 호출 (Function Calling)

llama.cpp는 모델이 도구를 호출하는 OpenAI 스타일의 함수 호출을 지원해요. llama-server에서 --jinja 플래그로 켜면 대부분의 모델에서 쓸 수 있어요. 모델의 채팅 템플릿이 알려진 네이티브 포맷이라면 그 포맷을 쓰고, 그렇지 않으면 일반(Generic) 방식으로 동작해요.

출처: llama.cpp function-calling 문서

네이티브 포맷과 일반(Generic) 지원

함수 호출은 모든 모델에서 지원돼요. 단, 모델의 템플릿이 네이티브 포맷 핸들러 중 하나라면 그 포맷을 사용하고, 그렇지 않으면 일반 핸들러로 동작해요. 로그에서 Chat format: Generic이 보이면 일반 지원이라는 뜻이에요.

  • 로그에서 Generic이 보일 때는 --chat-template-file로 적절한 템플릿을 지정할 수 있어요.
  • Generic은 모델 네이티브 포맷보다 토큰을 더 쓰고 효율이 떨어질 수 있어요.
  • 병렬(다중) 도구 호출은 일부 모델에서 지원하지만 기본으론 꺼져 있고, completion 파라미터에 "parallel_tool_calls": true를 넣어 켜요.

네이티브 포맷을 지원하는 대표 모델 계열:

  • Llama 3.1 / 3.3 (내장 도구 wolfram_alpha, web_search/brave_search, code_interpreter 포함), Llama 3.2
  • Functionary v3.1 / v3.2
  • Hermes 2/3, Qwen 2.5
  • Qwen 2.5 Coder
  • Mistral Nemo
  • Firefunction v2
  • Command R7B
  • DeepSeek R1 (WIP — 도구 호출을 잘 안 하는 경향이 있음)

서버 실행 예시

정식 tool_use Jinja 템플릿이 없는 모델이라면 --chat-template chatml을 써서 여러 모델에서 동작하는 기본 템플릿을 쓰는 것도 한 방법이에요.

# Hermes 3 (tool_use 템플릿 지정)
llama-server --jinja -fa -hf bartowski/Hermes-3-Llama-3.1-8B-GGUF:Q4_K_M \
    --chat-template-file models/templates/NousResearch-Hermes-3-Llama-3.1-8B-tool_use.jinja

# Generic 포맷 지원
llama-server --jinja -fa -hf bartowski/phi-4-GGUF:Q4_0

경고: 극단적인 KV 양자화(예: -ctk q4_0)는 모델의 도구 호출 성능을 크게 떨어뜨릴 수 있어요.

curl로 테스트하기

CLI에서든 OpenAI 호환 API를 쓰는 라이브러리든, 아래처럼 completion 엔드포인트에 tools를 넣어 테스트할 수 있어요.

curl http://localhost:8080/v1/chat/completions -d '{
    "model": "gpt-3.5-turbo",
    "tools": [
        {
        "type":"function",
        "function":{
            "name":"python",
            "description":"Runs code in an ipython interpreter and returns the result of the execution after 60 seconds.",
            "parameters":{
            "type":"object",
            "properties":{
                "code":{
                "type":"string",
                "description":"The code to run in the ipython interpreter."
                }
            },
            "required":["code"]
            }
        }
        }
    ],
    "messages": [
        {
        "role": "user",
        "content": "Print a hello world message with python."
        }
    ]
}'

응답은 finish_reason이 tool로 오고, message.tool_calls에 모델이 부른 함수 이름과 인자가 담겨요.

더 알아보기