---
title: "오픈 모델 함수 호출(도구 호출): 스키마, 재시도, 코드 | BroadRouter"
description: "OpenAI 호환 오픈 모델의 함수 호출: 스키마 작성 팁, 병렬 도구 호출, 도구 호출이 실패하는 다섯 가지 경우, 검증하고 재시도하는 Python 루프를 정리했습니다."
url: https://broadrouter.com/ko/blog/tool-calling-open-models/
lang: ko
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

이 페이지는 영어 원문을 AI의 도움을 받아 번역했습니다. [영어 원문 읽기](https://broadrouter.com/blog/tool-calling-open-models/) (2026-11-16 업데이트).

# 오픈 모델 도구 호출: 스키마, 병렬 호출, 재시도

BroadNet Inference 팀 · 4분 분량 · 게시 2026-11-14 · 업데이트 2026-11-16

OpenAI 호환 API의 오픈 모델은 OpenAI와 같은 tools 및 tool\_calls 형식을 사용합니다. 스키마는 작고 평평하게 유지하고, 인수는 JSON 문자열로 파싱하며, 무엇이든 실행하기 전에 검증하고, 오류는 도구 결과로 모델에 돌려보내 재시도하게 하세요. 단계 수에는 상한을 두세요. BroadNet에서는 GLM 5.3과 Qwen3.8 27B에 도구 지원이 표시되어 있습니다.

## 핵심 요약

-   전송 형식은 OpenAI와 같습니다. tools 목록을 보내면 tool\_calls가 돌아오고, tool\_call\_id마다 role tool 메시지를 하나씩 보냅니다.
-   인수는 JSON 문자열로 도착합니다. vLLM 문서는 원시 텍스트에서 도구 호출을 추출할 때 호출이 "may occasionally be malformed or violate the function's parameter schema"(번역: 가끔 형식이 잘못되거나 함수의 파라미터 스키마를 위반할 수 있다)고 경고합니다.
-   모든 호출을 검증하고, 오류는 도구 결과로 돌려보내며, 재시도 횟수와 전체 단계 수에 상한을 두세요.
-   도구는 적고 평평할수록 잘 동작합니다. OpenAI는 턴 시작 시점에 함수를 20개 미만으로 두라고 권합니다.
-   BroadNet Inference에서 도구 호출에는 GLM 5.3 또는 Qwen3.8 27B를 쓰고, DeepSeek V4.1 Flash는 의존하기 전에 테스트하세요.

**이 페이지의 내용**

1.  OpenAI 호환 API에서 도구 호출은 어떻게 동작하나요?
2.  도구 스키마는 어떻게 작성해야 하나요?
3.  병렬 도구 호출은 어떻게 다루나요?
4.  도구 호출은 왜 실패하나요?
5.  검증하고 재시도하는 도구 루프
6.  BroadNet에서 도구 호출을 지원하는 모델은 무엇인가요?
7.  BroadNet Inference는 어디에 적합한가요?

[도구 호출](https://broadrouter.com/ko/glossary/tool-calling/)은 모델을 에이전트로 만들어 주는 기능입니다. [OpenAI 호환 API](https://broadrouter.com/ko/glossary/openai-compatible-api/)의 오픈 모델에서도 요청 형식은 OpenAI에서 쓰는 것과 같습니다. 다른 점은 문제가 얼마나 자주 생기는지, 그리고 서버가 이를 막기 위해 무엇을 하는지입니다. 이 글에서는 형식, 오픈 모델이 잘 다루는 스키마 작성법, 병렬 호출, 실제로 마주치게 될 다섯 가지 실패, 그리고 이를 견디는 Python 루프를 다룹니다.

## OpenAI 호환 API에서 도구 호출은 어떻게 동작하나요?

1.  `messages`와 함께 `tools` 목록을 보냅니다. 각 도구에는 이름, 설명, 인수용 JSON Schema가 있습니다.
2.  모델은 `finish_reason: "tool_calls"`와 `tool_calls` 목록으로 응답합니다. 각 항목에는 `id`, 함수 이름, 그리고 **JSON 문자열** 형태의 `arguments`가 들어 있습니다.
3.  코드가 각 호출을 실행하고, 호출마다 해당 `tool_call_id`를 담은 `role: "tool"` 메시지를 하나씩 추가합니다.
4.  API를 다시 호출합니다. 모델은 답하거나 도구를 더 요청합니다.

모델은 아무것도 실행하지 않습니다. 무엇을 실행할지는 여러분의 코드가 결정합니다.

## 도구 스키마는 어떻게 작성해야 하나요?

오픈 모델은 단순한 스키마를 더 안정적으로 따릅니다. 아래 규칙은 OpenAI 가이드와, 실제로 자주 깨지는 부분에서 나온 것입니다.

-   **도구 이름은 동작으로 짓고**(`read_file`, `search_code` 등), 설명에는 각 도구를 _언제_ 써야 하는지 적으세요.
-   **목록은 짧게 유지하세요.** OpenAI 가이드는 턴 시작 시점에 함수를 20개 미만으로 두는 것을 가벼운 권장 사항으로 제시합니다. 모든 스키마는 매 호출마다 함께 전송되기도 합니다. [에이전트 토큰 예산](https://broadrouter.com/ko/blog/agent-token-budget/)을 참고하세요.
-   **평평한 인수를 선호하세요.** 문자열, 숫자, 불리언, enum을 쓰고 깊은 중첩과 자유 형식 객체는 피하세요.
-   **고정된 선택지에는 enum을 쓰세요.** 그래야 모델이 값을 지어내지 못합니다. [JSON 스키마 생성기](https://broadrouter.com/tools/json-schema-generator/)는 샘플 인수 객체를 `parameters`에 그대로 붙여 넣을 수 있는 평평한 스키마로 바꿔 줍니다.
-   **필수 필드를 표시하세요.** OpenAI의 strict 모드는 `additionalProperties: false`와 모든 필드를 `required`에 넣을 것을 요구하며, 선택 필드에는 타입으로 `null`을 추가합니다. 제공업체가 `strict`를 강제하는지는 제각각이므로 어쨌든 검증하세요.

## 병렬 도구 호출은 어떻게 다루나요?

모델은 한 턴에 `tool_calls` 항목을 여러 개 반환할 수 있습니다. 예를 들어 파일 읽기 세 개입니다. 서로 독립적인 호출은 동시에 실행하고, `tool_call_id`마다 결과를 하나씩 순서와 상관없이 돌려주세요. 도구에 서로 의존하는 부작용이 있다면 `parallel_tool_calls: false`를 설정하세요. OpenAI 가이드에 따르면 이렇게 하면 모델이 턴당 호출을 0개 또는 1개만 합니다. 제공업체가 이 설정을 지키는지 테스트하세요.

## 도구 호출은 왜 실패하나요?

| 실패 | 보이는 현상 | 해결 |
| --- | --- | --- |
| 잘못된 형식의 인수 | `json.loads`가 예외 발생 | 파싱 오류를 도구 결과로 돌려주고 재시도 |
| 스키마 불일치 | 필드 누락, 타입 오류, 지어낸 enum 값 | 검증하고 검증 오류를 돌려줌 |
| 알 수 없는 도구 | 정의한 적 없는 이름 | “unknown tool, available: …” 반환 |
| 필요한데 호출하지 않음 | 대신 텍스트로 답변 | `tool_choice: "required"` 또는 특정 함수 지정 |
| 잘린 호출 | `finish_reason: "length"` | `max_tokens` 늘리기. 추론이 한도를 함께 씀 |

처음 두 가지는 드문 일이 아니라 예상해야 하는 일입니다. vLLM의 도구 호출 문서에 따르면 `auto` 모드에서는 도구가 `strict: true`를 설정하고(또는 서버가 최소 엄격도를 강제하고) 모델의 파서가 제약을 지원하는 경우가 아니라면 “vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.”(번역: vLLM은 원시 텍스트에서 도구 호출을 추출하므로, 인수가 가끔 형식이 잘못되거나 함수의 파라미터 스키마를 위반할 수 있습니다.) 특정 함수를 지정하면 vLLM의 구조화된 출력 백엔드를 사용합니다. 제공업체마다 모델을 서빙하는 방식이 다를 수 있으므로 검증은 필수로 여기세요.

마지막 행은 [추론 모델](https://broadrouter.com/ko/glossary/reasoning-tokens/)을 쓰는 사람들이 자주 걸리는 부분입니다. GLM 5.3과 Qwen3.8 27B는 답하기 전에 사고하며, 사고 과정은 [`max_tokens`](https://broadrouter.com/ko/glossary/max-tokens/)에 포함됩니다. 여유를 얼마나 남겨야 하는지는 [응답이 비거나 잘리는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)에서 설명합니다.

## 검증하고 재시도하는 도구 루프

```python
import json, os
from openai import OpenAI
from jsonschema import validate, ValidationError

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
MODEL = "broadnet/glm-5.3"

TOOLS = [{"type": "function", "function": {
    "name": "get_order_status",
    "description": "Look up one order by its ID. Use when the user asks where an order is.",
    "parameters": {"type": "object",
                   "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"], "additionalProperties": False}}}]
SCHEMAS = {t["function"]["name"]: t["function"]["parameters"] for t in TOOLS}
IMPL = {"get_order_status": lambda order_id: f"Order {order_id}: shipped"}

def run_call(call):
    name = call.function.name
    if name not in IMPL:
        return f"Error: unknown tool {name}. Available: {', '.join(IMPL)}"
    try:
        args = json.loads(call.function.arguments or "{}")
        validate(args, SCHEMAS[name])
    except (json.JSONDecodeError, ValidationError) as e:
        return f"Error: invalid arguments ({e}). Send the call again with valid JSON."
    return str(IMPL[name](**args))

def agent(messages, max_steps=8):
    for _ in range(max_steps):
        r = client.chat.completions.create(model=MODEL, messages=messages,
                                           tools=TOOLS, max_tokens=4000)
        msg = r.choices[0].message
        if r.choices[0].finish_reason == "length":
            raise RuntimeError("Output limit reached; raise max_tokens")
        messages.append(msg.model_dump(exclude_none=True))
        if not msg.tool_calls:
            return msg.content
        for call in msg.tool_calls:
            messages.append({"role": "tool", "tool_call_id": call.id,
                             "content": run_call(call)})
    raise RuntimeError("Step limit reached")
```

여기서 중요한 설계 선택은 세 가지입니다.

1.  **오류는 도구 결과로 모델에 돌아갑니다.** 모델은 무엇이 잘못됐는지 보고 대개 다음 턴에 고칩니다. 예외를 발생시키면 그 기회를 버리는 셈입니다.
2.  **루프에는 상한이 있습니다.** `max_steps`는 진전 없이 도구만 계속 호출하는 모델을 멈춥니다.
3.  **전송 계층 재시도는 별개입니다.** 클라이언트의 `max_retries`는 429와 5xx를 처리합니다. 잘못된 인수는 루프에서 처리합니다. 둘을 섞지 마세요. [오류와 재시도](https://broadrouter.com/ko/guides/errors-and-retries/)를 참고하세요.

이메일 발송처럼 부작용이 있는 도구에는 멱등성 키를 추가해 재시도된 단계가 두 번 실행되지 않게 하세요. [장시간 실행 에이전트](https://broadrouter.com/ko/blog/long-running-agents-timeouts-retries/)에서 이를 다룹니다.

## BroadNet에서 도구 호출을 지원하는 모델은 무엇인가요?

| 모델 | 도구 표시 | 컨텍스트 | 비고 |
| --- | --- | --- | --- |
| [GLM 5.3](https://broadrouter.com/ko/models/glm-5.3/) | 예 | 1,048,576 | 구조화된 출력도 지원 |
| [Qwen3.8 27B](https://broadrouter.com/ko/models/qwen3.8-27b/) | 예 | 262,144 | 이미지 입력도 지원 |
| [DeepSeek V4.1 Flash](https://broadrouter.com/ko/models/deepseek-v4.1-flash/) | 표시되지 않음 | 1,048,576 | 이미지 입력, 도구는 의존하기 전에 테스트 |
| [Gemma 4 VL 26B](https://broadrouter.com/ko/models/gemma-4-vl-26b/) | 표시되지 않음 | 32,768 | 도구 루프용이 아님 |

도구를 지원하는 두 모델 중에서 고르려면 [GLM 5.3 vs Qwen3.8 27B](https://broadrouter.com/compare/glm-5.3-vs-qwen3.8-27b/)를 참고하세요. 최종 답변이 특정 형태를 따라야 하지만 실행할 함수는 없다면, 도구보다 [구조화된 출력](https://broadrouter.com/ko/blog/structured-output-json-schema/)이 더 간단합니다.

## BroadNet Inference는 어디에 적합한가요?

BroadNet Inference는 도구 호출이 표시된 GLM 5.3과 Qwen3.8 27B를 표준 채팅 완성 형식으로 제공하므로, 위 루프는 [OpenAI Python SDK](https://broadrouter.com/ko/guides/openai-python-sdk/)에서 수정 없이 실행됩니다. 토큰당 가격은 [가격 페이지](https://broadrouter.com/ko/pricing/)에 있습니다. 웹 검색이나 코드 실행 같은 서버 측 도구는 호스팅하지 않으며, 무제한 플랜의 모델인 DeepSeek V4.1 Flash에는 문서상 도구 호출이 표시되어 있지 않습니다. 도구를 많이 쓰는 에이전트라면 GLM 5.3이나 Qwen3.8 27B를 토큰당 과금으로 쓰세요. 그래도 정액 플랜을 원한다면, 한 달 플랜을 사기 전에 $1 요금의 Meteor 1시간으로 DeepSeek V4.1 Flash가 도구를 안정적으로 호출하는지 확인하세요.

관련 무료 도구 (영어)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[무료 도구 (영어)](https://broadrouter.com/tools/)

## 이 글의 용어

[구조화된 출력(Structured output)](https://broadrouter.com/ko/glossary/structured-output/)

구조화된 출력(structured output)은 모델의 응답을 개발자가 지정한 형식, 주로 JSON Schema에 맞추도록 제한해 코드가 안정적으로 파싱할 수 있게 하는 LLM API 기능입니다. 유효한 JSON만 보장하고 특정 구조는 보장하지 않는 JSON 모드보다 더 엄격합니다.

[AI 에이전트(AI agent)](https://broadrouter.com/ko/glossary/agent/)

AI 에이전트는 언어 모델이 목표를 향해 스스로 단계를 정하는 시스템입니다. 어떤 도구를 호출할지 결정하고, 결과를 읽고, 최종 답변을 내거나 한도에 닿을 때까지 이를 반복합니다. 정해진 지점에서 모델을 호출하는 고정된 스크립트는 보통 워크플로라고 부릅니다.

[OpenAI 호환 API(OpenAI-compatible API)](https://broadrouter.com/ko/glossary/openai-compatible-api/)

OpenAI 호환 API는 POST /v1/chat/completions처럼 OpenAI API와 같은 요청 및 응답 형식을 받는 HTTP API입니다. 그래서 OpenAI SDK와 도구는 base URL, API 키, 모델 이름만 바꾸면 이 API를 그대로 사용할 수 있습니다.

[도구 호출(tool calling)](https://broadrouter.com/ko/glossary/tool-calling/)

도구 호출(tool calling)은 함수 호출(function calling)이라고도 하며, 모델이 개발자가 정의한 함수를 실행해 달라는 구조화된 요청을 JSON 인자와 함께 반환하는 LLM API 기능입니다. 함수는 애플리케이션이 실행하고 그 결과를 다시 보냅니다. 모델이 직접 코드를 실행하지는 않습니다.

[멱등성 키(idempotency key)](https://broadrouter.com/ko/glossary/idempotency-key/)

멱등성 키(idempotency key)는 결제나 구매처럼 상태를 바꾸는 요청에 클라이언트가 붙이는 고유한 값으로, 보통 UUID 같은 무작위 ID입니다. 같은 요청이 같은 키로 다시 오면 서버는 작업을 두 번 수행하지 않고 처음 결과를 돌려줍니다.

[JSON Schema(JSON 스키마)](https://broadrouter.com/ko/glossary/json-schema/)

JSON Schema는 JSON으로 작성하는 어휘로, 타입, 필수 필드, 허용 값, 중첩 같은 JSON 데이터의 구조를 기술하고 검증합니다. 현재 버전은 2020-12입니다. LLM API는 이를 사용해 도구 파라미터와 구조화된 출력이 따라야 할 정확한 형태를 정의합니다.

[vLLM](https://broadrouter.com/ko/glossary/vllm/)

vLLM은 UC 버클리 Sky Computing Lab에서 처음 개발된 LLM 추론·서빙용 오픈소스 라이브러리입니다. PagedAttention으로 KV 캐시 메모리를 관리하고, 들어오는 요청을 연속적으로 배칭하며, 다양한 양자화 형식을 지원하고, OpenAI 호환 HTTP 서버를 제공합니다.

## 자주 묻는 질문

### 오픈 모델도 함수 호출을 지원하나요?

많은 모델이 지원하지만, 지원 여부는 모델과 제공업체의 서빙 방식에 따라 다릅니다. BroadNet Inference 문서에는 GLM 5.3과 Qwen3.8 27B에 도구 호출이 표시되어 있습니다. DeepSeek V4.1 Flash와 Gemma 4 VL 26B에는 표시되어 있지 않습니다.

### 도구 호출 인수가 잘못된 JSON으로 나오는 이유는 무엇인가요?

서버가 디코딩을 제약하지 않는 한, 인수는 텍스트로 생성된 뒤 나중에 파싱됩니다. vLLM 문서는 원시 텍스트에서 추출한 인수가 가끔 형식이 잘못될 수 있다고 말합니다. 파싱 오류를 잡아 도구 결과로 돌려보내면 모델이 스스로 고칠 수 있습니다.

### 병렬 도구 호출은 어떻게 끄나요?

OpenAI 형식에서는 parallel\_tool\_calls를 false로 설정하세요. 그러면 모델은 턴당 도구 호출을 0개 또는 1개만 합니다. 제공업체가 이 필드를 지원하는지 확인하세요.

### 모델이 도구를 호출하지 않고 텍스트로 답하는 이유는 무엇인가요?

tool\_choice가 auto이면 모델이 결정합니다. 호출이 반드시 필요하다면 tool\_choice를 required나 특정 함수로 설정하세요. 도구 설명에 언제 써야 하는지가 적혀 있는지도 확인하세요.

### 도구 호출이 중간에 잘리는 이유는 무엇인가요?

추론 모델은 사고 과정을 max\_tokens에 포함합니다. 한도가 작으면 인수 중간에서 응답이 끝날 수 있습니다. finish\_reason을 확인하고 max\_tokens를 늘리세요.

## 이어서 읽기

-   [저렴한 모델로 OpenClaw와 Hermes Agent 쓰기: 설정과 토큰 계산](https://broadrouter.com/ko/blog/openclaw-hermes-agent-cheap-model/)
-   [JSON 모드 vs json\_schema: 믿고 쓸 수 있는 구조화된 출력](https://broadrouter.com/ko/blog/structured-output-json-schema/)
-   [OpenAI 호환 모델에서 MCP 서버 사용하기(모든 제공업체)](https://broadrouter.com/ko/blog/mcp-with-openai-compatible-models/)
-   [장시간 실행 에이전트: 버티는 타임아웃, 재시도, 체크포인트](https://broadrouter.com/ko/blog/long-running-agents-timeouts-retries/)
-   [에이전트 토큰 예산: 에이전트 루프의 토큰은 어디로 가는가](https://broadrouter.com/ko/blog/agent-token-budget/)
-   [BroadNet의 GPU 하드웨어와 서빙 방식: BroadNet이 밝힌 내용](https://broadrouter.com/ko/blog/broadnet-gpu-fleet-and-serving/)
-   [LLM API 응답 캐싱으로 비용 줄이기: Python 정확 일치 캐시](https://broadrouter.com/ko/blog/cache-llm-responses-cut-cost/)
-   [가이드: BroadNet Inference에서 OpenAI Python SDK 사용하기](https://broadrouter.com/ko/guides/openai-python-sdk/)
-   [가이드: BroadNet Inference에서 OpenAI Agents SDK 실행하기](https://broadrouter.com/ko/guides/openai-agents-sdk-custom-provider/)
-   [가이드: 추론 모델이 빈 답변을 반환하는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)
-   [가이드: BroadNet Inference 오류 코드와 재시도해야 하는 경우](https://broadrouter.com/ko/guides/errors-and-retries/)

실제 워크로드로 테스트해 보세요. 신규 계정에는 US$5 상당의 초기 크레딧이 제공되며 Gemma 및 음성 전사에 사용할 수 있습니다. DeepSeek, GLM 및 Qwen3.8 모델은 충전이 필요합니다.

[시작하기](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-blog-tool-calling-open-models&utm_content=page-cta) ·

**출처**

-   [OpenAI 함수 호출 가이드(2026-11-14 확인)](https://developers.openai.com/api/docs/guides/function-calling)
-   [vLLM 문서, 도구 호출(2026-11-14 확인)](https://docs.vllm.ai/en/latest/features/tool_calling/)
-   [BroadNet Inference API 레퍼런스, 모델 (영어)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-blog-tool-calling-open-models&utm_content=sources#models)
