BroadRouter
시작하기

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

BroadNet Inference 팀 · 4분 분량 · 게시 · 업데이트

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

도구 호출은 모델을 에이전트로 만들어 주는 기능입니다. OpenAI 호환 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개 미만으로 두는 것을 가벼운 권장 사항으로 제시합니다. 모든 스키마는 매 호출마다 함께 전송되기도 합니다. 에이전트 토큰 예산을 참고하세요.
  • 평평한 인수를 선호하세요. 문자열, 숫자, 불리언, enum을 쓰고 깊은 중첩과 자유 형식 객체는 피하세요.
  • 고정된 선택지에는 enum을 쓰세요. 그래야 모델이 값을 지어내지 못합니다. JSON 스키마 생성기는 샘플 인수 객체를 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의 구조화된 출력 백엔드를 사용합니다. 제공업체마다 모델을 서빙하는 방식이 다를 수 있으므로 검증은 필수로 여기세요.

마지막 행은 추론 모델을 쓰는 사람들이 자주 걸리는 부분입니다. GLM 5.3과 Qwen3.8 27B는 답하기 전에 사고하며, 사고 과정은 max_tokens에 포함됩니다. 여유를 얼마나 남겨야 하는지는 응답이 비거나 잘리는 이유에서 설명합니다.

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

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를 처리합니다. 잘못된 인수는 루프에서 처리합니다. 둘을 섞지 마세요. 오류와 재시도를 참고하세요.

이메일 발송처럼 부작용이 있는 도구에는 멱등성 키를 추가해 재시도된 단계가 두 번 실행되지 않게 하세요. 장시간 실행 에이전트에서 이를 다룹니다.

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

모델 도구 표시 컨텍스트 비고
GLM 5.3 예 1,048,576 구조화된 출력도 지원
Qwen3.8 27B 예 262,144 이미지 입력도 지원
DeepSeek V4.1 Flash 표시되지 않음 1,048,576 이미지 입력, 도구는 의존하기 전에 테스트
Gemma 4 VL 26B 표시되지 않음 32,768 도구 루프용이 아님

도구를 지원하는 두 모델 중에서 고르려면 GLM 5.3 vs Qwen3.8 27B를 참고하세요. 최종 답변이 특정 형태를 따라야 하지만 실행할 함수는 없다면, 도구보다 구조화된 출력이 더 간단합니다.

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

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

자주 묻는 질문

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

많은 모델이 지원하지만, 지원 여부는 모델과 제공업체의 서빙 방식에 따라 다릅니다. 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를 늘리세요.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기