메인 콘텐츠로 건너뛰기
PydanticAI는 Pydantic 팀이 만든 Python 에이전트 프레임워크입니다. LLM 공급자 위에 타입 기반 의존성, 도구 호출, 구조화된 출력, 스트리밍을 제공합니다. Venice는 OpenAI 호환 백엔드로 동작합니다 — OpenAIChatModel이 Venice를 가리키도록 설정하고, 나머지 PydanticAI API는 평소처럼 사용하세요.

사전 준비

설치

OpenAI 지원과 함께 PydanticAI를 설치하세요:
OpenAI 엑스트라가 포함된 전체 pydantic-ai 패키지를 설치할 수도 있습니다. Venice API 키를 환경 변수에 추가하세요:
API 키를 소스 컨트롤에 두지 마세요. 프로덕션에서는 환경 변수나 시크릿 매니저를 사용하는 것이 좋습니다.

Venice를 모델 공급자로 구성

Venice는 OpenAI Chat Completions API를 지원합니다. OpenAIChatModelOpenAIProvider, 그리고 Venice의 base URL을 함께 사용하세요:
OpenAIResponsesModel 이나 openai: 단축 표기 대신 OpenAIChatModel(Chat Completions)을 사용하세요. Venice의 주된 호환 경로는 /chat/completions입니다. Chat Completions로 고정하면 최신 PydanticAI 버전에서 OpenAI 기본 모델이 사용하는 Responses 전용 동작을 피할 수 있습니다.

환경 변수

OpenAIProviderOPENAI_API_KEYOPENAI_BASE_URL도 읽습니다. 코드에서 인수를 넘기는 대신 아래처럼 Venice를 구성할 수도 있습니다:

에이전트 실행

비동기 사용도 await agent.run(...)으로 동일한 패턴입니다:

응답 스트리밍

토큰을 도착하는 대로 받고 싶다면 run_stream을 사용하세요:

구조화된 출력

output_type에 Pydantic 모델을 넘겨 에이전트의 최종 답변을 검증하세요:
프로덕션에서 도구 기반 구조화된 출력을 사용하기 전에 구조화된 응답함수 호출을 지원하는 모델들을 살펴보세요.

도구

@agent.tool_plain(에이전트 컨텍스트 없음) 또는 @agent.tool(RunContext 필요)로 도구를 등록하세요:

Venice 전용 파라미터

Venice 전용 옵션은 ModelSettings.extra_body로 전달하세요. 예를 들어 venice_parameters로 내장 웹 검색을 활성화할 수 있습니다:
실행별로 설정을 재정의할 수도 있습니다:
전체 venice_parameters 목록(웹 스크래핑, 인용, 캐릭터, 사고 제어, E2EE 토글)은 API 사양을 참고하세요.

권장 모델

모델 ID는 시간이 지남에 따라 변경됩니다 — 현재 ID는 GET /models 또는 모델 개요에서 확인하세요.

프라이버시 이점

PydanticAI는 애플리케이션 데이터, 사용자 컨텍스트, 내부 도구를 다루는 에이전트에 자주 사용됩니다. Venice와 함께 사용하면 그러한 워크플로를 프라이빗, 비검열 추론 위에서 유지할 수 있습니다:
  • 프라이빗 모델의 데이터 보존 제로(zero data retention) — 요청 이후 프롬프트와 도구 페이로드가 보관되지 않습니다
  • 에이전트가 노골적인 비판이나 레드 티밍이 필요할 때의 비검열 분석
  • OpenAI 호환 배선 덕분에 공급자 base URL과 API 키만 바꾸면 기존 PydanticAI 앱을 마이그레이션할 수 있습니다

문제 해결

에이전트를 실행하는 프로세스에 VENICE_API_KEY(또는 OPENAI_API_KEY)가 설정되어 있는지 확인하세요. 환경 변수를 변경한 후에는 셸이나 프로세스를 재시작하세요.
모델 페이지에서 최신 모델 ID를 사용하세요. base_url은 뒤에 경로 없이 https://api.venice.ai/api/v1로 설정하세요 — PydanticAI가 /chat/completions를 덧붙입니다.
OpenAIChatModel을 명시적인 OpenAIProvider와 함께 사용하는 것이 좋습니다. Chat Completions 대신 OpenAI의 Responses API를 대상으로 할 수 있는 단순 openai: 에이전트 단축 표기는 피하세요.
함수 호출을 지원하는 모델을 선택하고, instructions에 도구를 언제 실행해야 하는지 서술하며, 도구 docstring을 정확하게 유지하세요 — PydanticAI는 시그니처와 docstring으로부터 JSON 스키마를 만듭니다.

PydanticAI 문서

에이전트, 도구, 의존성, 출력 타입

Venice 모델

모델과 지원 기능을 둘러보세요