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

먼저 키를 받으세요. gate.joingonka.ai/register에 등록하면 시작 시 10M 무료 토큰을 제공하며 대시보드 → API Keys에서 jg-xxx 키를 생성하세요.

설치:

pip install pydantic-ai
# 또는 OpenAI 의존성만 있는 경량 옵션:
# pip install "pydantic-ai-slim[openai]"

Gonka를 통한 에이전트의 최소 예제. PydanticAI는 OpenAIProvider(base_url=..., api_key=...)를 통해 사용자 지정 엔드포인트를 설정하며, 이는 OpenAIChatModel에 전달됩니다:

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

model = OpenAIChatModel(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    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(...)이 있습니다.

모델 매개변수: Qwen3-235B의 컨텍스트 창은 128K 토큰(131072)이며, 게이트웨이를 통한 최대 응답 길이는 8192 토큰입니다. 모델 설정(OpenAIChatModelSettings(max_tokens=8192))을 통해 출력을 제한할 수 있습니다. moonshotai/Kimi-K2.6(최대 3072 출력 토큰) 및 MiniMaxAI/MiniMax-M2.7(최대 4096)도 사용 가능하며, OpenAIChatModel의 첫 번째 인수로 모델 이름만 변경하면 됩니다.

PydanticAI를 선택하는 주된 이유는 구조화된 출력입니다. 응답 텍스트를 정규식으로 파싱하는 대신, 결과를 Pydantic 모델로 설명하고 이를 output_type 매개변수에 전달합니다. 프레임워크는 모델의 도구 호출을 사용하여 모델이 스키마와 엄격하게 일치하는 데이터를 반환하도록 강제하고, 유효성을 검사하여 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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    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]이며 텍스트가 아닙니다

이는 Qwen3-235B (및 다른 두 Gonka 모델)가 네이티브 도구 호출을 지원하기 때문에 작동합니다. PydanticAI는 이를 기반으로 유효한 JSON 구조를 반환합니다. 결과적으로 수동으로 파싱할 필요 없는 유형화된 Python 객체를 얻게 됩니다. 데이터 추출, 분류, 양식 작성 및 결과가 엄격한 형식으로 코드에 전달되어야 하는 RAG 파이프라인에 이상적입니다.

PydanticAI는 데이터를 추출하고, 도구를 호출하고, 쿼리 스트림을 처리하는 등 지속적으로 작동하는 에이전트 및 파이프라인을 위한 프레임워크입니다. 여기서는 토큰 비용이 프로젝트가 프로토타입으로 남을지 아니면 프로덕션으로 전환될지를 결정합니다. 일반적인 워크로드를 비교해 보겠습니다.

수백, 수천 배의 차이가 있습니다. 프로토타입의 경우 10M 무료 토큰으로 에이전트를 수백 번 실행할 수 있습니다. 하루에 수십만 개의 요청을 처리하는 프로덕션의 경우 같은 PydanticAI 코드에서 base_url만 변경해도 한 달에 수만 달러를 절약할 수 있습니다.

하나의 jg-xxx 키와 하나의 잔액은 OpenAI 형식(/v1)과 Anthropic 형식(/v1/messages) 모두에서 작동합니다. 그러나 PydanticAI의 경우 위에서 언급한 OpenAI 호환 엔드포인트면 충분합니다.

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

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

model = OpenAIChatModel(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-your-key",
    ),
)

agent = Agent(
    model,
    instructions="당신은 조수입니다. 필요할 때 도구를 사용합니다.",
)


@agent.tool_plain
def roll_dice() -> str:
    """6면 주사위를 굴려 결과를 반환합니다."""
    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의 도구 호출은 네이티브이므로 도구는 텍스트 응답 파싱의 취약성 없이 안정적으로 호출됩니다. 전체 주기(요청 → 도구 호출 → 최종 응답)는 Gonka를 통해 약 $0.00001이며, OpenAI/Anthropic의 경우 $0.04–0.22입니다.

어떤 모델을 선택해야 할까요: Qwen/Qwen3-235B-A22B-Instruct-2507-FP8은 기본값이며, 품질과 최대 출력 제한(8192)에서 가장 좋은 균형을 이룹니다. moonshotai/Kimi-K2.6은 코딩 및 복잡한 추론에 강력합니다(최대 3072 출력). MiniMaxAI/MiniMax-M2.7은 긴 대화에 적합합니다(최대 4096 출력). 세 가지 모두 한 번의 키로 즉시 사용 가능하며, 모델 문자열만 변경하면 됩니다. 유사한 도구로는 체인 및 RAG용 LangChain과 데이터 인덱싱용 LlamaIndex가 있습니다.