PydanticAI + Gonka — 저렴한 유형화된 AI 에이전트

먼저 키를 받으세요: gate.joingonka.ai/register 에서 등록하십시오(등록 시 3M 무료 토큰 제공). 그 후 Dashboard → API Keys 에서 jg-xxx 키를 생성합니다.

설치:

pip install pydantic-ai
# 또는 OpenAI 의존성만 포함한 경량 버전:
# pip install "pydantic-ai-slim[openai]"

최소 예제 — Gonka를 통한 에이전트입니다. PydanticAI는 OpenAIChatModel 로 전달되는 OpenAIProvider(base_url=..., api_key=...) 를 통해 커스텀 endpoint를 설정합니다:

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-your-key",
    ),
)

agent = Agent(model)

result = agent.run_sync("PoUW가 무엇인지 두 문장으로 설명해줘")
print(result.output)

이것으로 끝입니다. 귀하의 PydanticAI 에이전트가 Gonka 탈중앙화 네트워크 를 통해 저렴한 비용으로 작동합니다. run_sync 메서드는 스크립트에 편리하며, 비동기 코드의 경우 await agent.run(...) 을 사용하십시오.

모델 매개변수: MiniMax M2.7의 컨텍스트 윈도우는 200K 토큰(200000), DeepSeek V4 Flash는 380K, GLM-5.3 Flash는 390K입니다. Gateway를 통한 최대 응답 길이는 MiniMax 및 GLM-5.3 Flash의 경우 최대 8192 토큰, DeepSeek의 경우 최대 32768 토큰입니다. 모델 설정(OpenAIChatModelSettings(max_tokens=8192))을 통해 출력을 제한할 수 있습니다. MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731, zai-org/GLM-5.3-Flash 가 사용 가능하며, OpenAIChatModel 의 첫 번째 인자에서 모델 이름을 바꾸기만 하면 됩니다.

PydanticAI를 선택하는 주된 이유는 structured output 입니다. 텍스트 응답을 정규식으로 파싱하는 대신, 결과를 Pydantic 모델로 기술하고 output_type 매개변수에 전달합니다. 프레임워크는 모델의 tool calling 기능을 사용하여 스키마에 엄격히 부합하는 데이터를 반환하게 하고, 이를 검증한 후 result.output 을 통해 완성된 객체를 제공합니다.

from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-your-key",
    ),
)


class Profile(BaseModel):
    name: str
    role: str
    skills: list[str]


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "데이터 추출: 안나는 백엔드 개발자이며 Python, Go, Postgres를 알고 있습니다."
)
print(result.output)
# name='안나' role='백엔드 개발자' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — list[str] 형식으로 획득

Gonka의 세 가지 모델(MiniMax M2.7, DeepSeek V4 Flash, GLM-5.3 Flash) 모두 네이티브 tool calling을 지원하므로 가능합니다. PydanticAI는 이를 활용하여 유효한 JSON 구조를 반환합니다. 출력물로서 수동 파싱이 필요한 문자열이 아닌, 타입이 지정된 Python 객체를 얻게 됩니다. 데이터 추출, 분류, 양식 입력 및 코드 내부에서 엄격한 형식의 결과가 필요한 RAG 파이프라인에 이상적입니다.

PydanticAI는 데이터를 추출하고, 도구를 호출하며, 요청 스트림을 처리하는 등 지속적으로 작동하는 에이전트와 파이프라인을 위한 프레임워크입니다. 여기서 토큰 비용은 프로젝트가 프로토타입으로 남을지 프로덕션으로 넘어갈지를 결정합니다. 일반적인 부하를 비교해 보겠습니다:

차이는 수백에서 수천 배에 달합니다. 프로토타입의 경우 3M의 무료 토큰으로 에이전트 초기 구동을 충분히 수행할 수 있습니다. 매일 수십만 건의 요청을 처리하는 프로덕션 환경에서는 동일한 PydanticAI 코드를 유지하면서 base_url만 변경하면 월 수만 달러를 절약할 수 있습니다.

하나의 jg-xxx 키와 잔액으로 OpenAI 형식(/v1)과 Anthropic 형식(/v1/messages) 모두를 지원하지만, PydanticAI에는 위에 표시된 OpenAI 호환 엔드포인트만으로 충분합니다.

PydanticAI의 두 번째 핵심 기능은 도구(tools)입니다. 함수는 데코레이터 @agent.tool_plain (컨텍스트 없음) 또는 @agent.tool (RunContext 및 dependency injection에 접근 가능)를 사용하여 등록할 수 있습니다. 모델은 스스로 도구를 호출할 시점을 결정하고, 결과를 받은 뒤 추론을 계속합니다:

import random
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-ваш-ключ",
    ),
)

agent = Agent(
    model,
    instructions="Ты помощник. Используй инструменты, когда нужно.",
)


@agent.tool_plain
def roll_dice() -> str:
    """Бросает шестигранный кубик и возвращает результат."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """Вычисляет математическое выражение."""
    return str(eval(expression))


result = agent.run_sync("Брось кубик и умножь результат на 7")
print(result.output)

Gonka에서의 tool calling은 네이티브 방식이므로, 불안정한 텍스트 응답 파싱 없이 도구가 안정적으로 호출됩니다. 전체 사이클(요청 → 도구 호출 → 최종 응답)의 비용은 Gonka를 통해 약 $0.00007이며, OpenAI/Anthropic의 $0.04–0.22 대비 매우 저렴합니다.

모델 선택 권장사항: MiniMaxAI/MiniMax-M2.7 — 긴 대화 및 균형 잡힌 작업용, 출력 최대 8192. deepseek-ai/DeepSeek-V4-Flash-0731 — 네트워크상 가장 긴 컨텍스트(380K)와 저렴한 대형 프롬프트 제공, 출력 최대 32768. zai-org/GLM-5.3-Flash — 복잡한 추론을 위한 reasoning 모델이자 네트워크상 가장 긴 컨텍스트(390K) 제공, 출력 최대 8192; 추론 시 max_tokens의 일부가 소모되므로 여유 있게 설정(600 이상)하십시오. 세 모델 모두 하나의 키로 즉시 사용 가능하며 모델명만 변경하면 됩니다. 관련 도구: 체인 및 RAG를 위한 LangChain, 데이터 인덱싱을 위한 LlamaIndex.