Tool calling 베스트 프랙티스

몸으로 익힌 룰

모든 tool call validate. 모델이 함수 이름 hallucinate, required 인자 누락, 잘못된 type 줄 수 있어. Dispatch를 try/except로 감싸고 crash 대신 error JSON 반환.
Tool set 작게. 5–10개가 sweet spot. 그 이상이면 모델이 distracted돼서 잘못 골라. 더 필요하면 도메인별 group 만들고 request마다 subset 선택.
Description은 docstring처럼. 첫 문장: 뭐 하는지. 두 번째 문장: 언제 쓸지 (그리고 언제 안 쓸지).
stream: false로 먼저 test. Streaming + tool call은 parsing 복잡도 추가. Non-streaming으로 loop 제대로 만든 다음 streaming 위에 layer.
Registry 사용. {name: callable} dict가 거대한 if/else chain보다 좋음 — test 쉽고, 확장 쉽고, tool 하나 교체 쉬움.

Ollama Python library 단축

v0.4부터 공식 library가 Python 함수를 tools로 직접 받음. Function signature랑 docstring에서 JSON Schema 자동 생성. Prototyping에 큰 가속기. Production은 description 의도적으로 만들도록 schema 명시적으로 정의.

Code

Timeout 가진 방어적 dispatch·python

import asyncio, json, signal
from contextlib import contextmanager

class ToolError(Exception): ...

@contextmanager
def timeout(seconds: int):
    """POSIX SIGALRM 기반 timeout (single-thread만)."""
    def handler(_signum, _frame):
        raise TimeoutError(f"tool exceeded {seconds}s")
    old = signal.signal(signal.SIGALRM, handler)
    signal.alarm(seconds)
    try:
        yield
    finally:
        signal.alarm(0)
        signal.signal(signal.SIGALRM, old)

def dispatch(name: str, args: dict, registry: dict, timeout_s: int = 10) -> str:
    if name not in registry:
        return json.dumps({"error": f"Unknown tool: {name}"})
    try:
        with timeout(timeout_s):
            result = registry[name](**args)
        return result if isinstance(result, str) else json.dumps(result)
    except TypeError as e:
        return json.dumps({"error": f"Bad arguments: {e}"})
    except Exception as e:
        return json.dumps({"error": str(e)})

Ollama Python library — function-as-tool·python

from ollama import chat

def get_temperature(city: str) -> str:
    """Get the current temperature for a city. Returns string like '22C in Seoul'."""
    return f"22C in {city}"

# Library가 docstring + signature에서 JSON Schema 생성
response = chat(
    model="qwen2.5:7b",
    messages=[{"role": "user", "content": "Temperature in Paris?"}],
    tools=[get_temperature],
)
print(response.message.content)

Tool calling 베스트 프랙티스

몸으로 익힌 룰

Ollama Python library 단축

Code

External links

Exercise

Progress

댓글 0