> ## Documentation Index > Fetch the complete documentation index at: https://docs.venice.ai/llms.txt > Use this file to discover all available pages before exploring further. # PydanticAI 통합 > Venice의 프라이빗, OpenAI 호환 채팅 모델을 사용해 도구 호출, 구조화된 출력, 스트리밍을 지원하는 타입 기반 Python 에이전트를 PydanticAI로 구축하세요. [PydanticAI](https://ai.pydantic.dev/)는 Pydantic 팀이 만든 Python 에이전트 프레임워크입니다. LLM 공급자 위에 타입 기반 의존성, 도구 호출, 구조화된 출력, 스트리밍을 제공합니다. Venice는 OpenAI 호환 백엔드로 동작합니다 — `OpenAIChatModel`이 Venice를 가리키도록 설정하고, 나머지 PydanticAI API는 평소처럼 사용하세요. ## 사전 준비 * Python 3.9 이상 * [Venice API 키](/guides/getting-started/generating-api-key) ## 설치 OpenAI 지원과 함께 PydanticAI를 설치하세요: ```bash pip theme={"system"} pip install "pydantic-ai-slim[openai]" ``` ```bash uv theme={"system"} uv add "pydantic-ai-slim[openai]" ``` OpenAI 엑스트라가 포함된 전체 `pydantic-ai` 패키지를 설치할 수도 있습니다. Venice API 키를 환경 변수에 추가하세요: ```bash theme={"system"} export VENICE_API_KEY=your-venice-api-key ``` API 키를 소스 컨트롤에 두지 마세요. 프로덕션에서는 환경 변수나 시크릿 매니저를 사용하는 것이 좋습니다. ## Venice를 모델 공급자로 구성 Venice는 OpenAI Chat Completions API를 지원합니다. `OpenAIChatModel`과 `OpenAIProvider`, 그리고 Venice의 base URL을 함께 사용하세요: ```python theme={"system"} import os from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIChatModel from pydantic_ai.providers.openai import OpenAIProvider model = OpenAIChatModel( "venice-uncensored", provider=OpenAIProvider( base_url="https://api.venice.ai/api/v1", api_key=os.environ["VENICE_API_KEY"], ), ) agent = Agent( model, instructions="You are a concise, privacy-respecting assistant.", ) ``` `OpenAIResponsesModel` 이나 `openai:` 단축 표기 대신 `OpenAIChatModel`(Chat Completions)을 사용하세요. Venice의 주된 호환 경로는 `/chat/completions`입니다. Chat Completions로 고정하면 최신 PydanticAI 버전에서 OpenAI 기본 모델이 사용하는 Responses 전용 동작을 피할 수 있습니다. ### 환경 변수 `OpenAIProvider`는 `OPENAI_API_KEY`와 `OPENAI_BASE_URL`도 읽습니다. 코드에서 인수를 넘기는 대신 아래처럼 Venice를 구성할 수도 있습니다: ```bash theme={"system"} export OPENAI_API_KEY=your-venice-api-key export OPENAI_BASE_URL=https://api.venice.ai/api/v1 ``` ```python theme={"system"} from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIChatModel agent = Agent( OpenAIChatModel("venice-uncensored"), instructions="You are a concise, privacy-respecting assistant.", ) ``` ## 에이전트 실행 ```python theme={"system"} result = agent.run_sync("데이터 보존 제로(zero data retention)를 두 문장으로 설명해줘.") print(result.output) print(result.usage) ``` 비동기 사용도 `await agent.run(...)`으로 동일한 패턴입니다: ```python theme={"system"} import asyncio async def main() -> None: result = await agent.run("Venice는 어떤 프라이버시 등급을 제공해?") print(result.output) asyncio.run(main()) ``` ## 응답 스트리밍 토큰을 도착하는 대로 받고 싶다면 `run_stream`을 사용하세요: ```python theme={"system"} import asyncio async def main() -> None: async with agent.run_stream("프라이빗 AI에 관한 짧은 시를 써줘.") as response: async for text in response.stream_text(): print(text, end="", flush=True) asyncio.run(main()) ``` ## 구조화된 출력 `output_type`에 Pydantic 모델을 넘겨 에이전트의 최종 답변을 검증하세요: ```python theme={"system"} import os from pydantic import BaseModel, Field from pydantic_ai import Agent from pydantic_ai.models.openai import OpenAIChatModel from pydantic_ai.providers.openai import OpenAIProvider class PrivacySummary(BaseModel): summary: str = Field(description="한 문장 개요") benefits: list[str] = Field(description="주요 프라이버시 이점") recommendation: str = Field(description="이 접근 방식을 선택해야 할 시점") model = OpenAIChatModel( "zai-org-glm-5-1", provider=OpenAIProvider( base_url="https://api.venice.ai/api/v1", api_key=os.environ["VENICE_API_KEY"], ), ) agent = Agent( model, output_type=PrivacySummary, instructions="사용자의 요청에서 구조화된 요약을 추출하세요.", ) result = agent.run_sync("채팅 로그를 보관하는 공급자와 프라이빗 추론을 비교해줘.") print(result.output.summary) print(result.output.benefits) ``` 프로덕션에서 도구 기반 구조화된 출력을 사용하기 전에 [구조화된 응답](/guides/features/structured-responses)과 [함수 호출](/guides/features/function-calling)을 지원하는 모델들을 살펴보세요. ## 도구 `@agent.tool_plain`(에이전트 컨텍스트 없음) 또는 `@agent.tool`(`RunContext` 필요)로 도구를 등록하세요: ```python theme={"system"} import os from dataclasses import dataclass from pydantic_ai import Agent, RunContext from pydantic_ai.models.openai import OpenAIChatModel from pydantic_ai.providers.openai import OpenAIProvider @dataclass class SupportDeps: user_id: str model = OpenAIChatModel( "zai-org-glm-5-1", provider=OpenAIProvider( base_url="https://api.venice.ai/api/v1", api_key=os.environ["VENICE_API_KEY"], ), ) agent = Agent( model, deps_type=SupportDeps, instructions="사용자가 Venice 모델을 고를 수 있도록 도와주세요. 사실 확인이 필요하면 도구를 사용하세요.", ) @agent.tool_plain def list_budget_models() -> list[str]: """예산 친화적인 Venice 텍스트 모델 ID를 반환합니다.""" return ["venice-uncensored", "qwen3-5-9b"] @agent.tool def get_user_tier(ctx: RunContext[SupportDeps]) -> str: """호출자의 계정 등급을 반환합니다.""" return "pro" if ctx.deps.user_id.startswith("pro_") else "standard" result = agent.run_sync( "저렴한 Venice 모델 중 어떤 걸 써보면 좋을까? 그리고 내 등급은 뭐야?", deps=SupportDeps(user_id="pro_42"), ) print(result.output) ``` ## Venice 전용 파라미터 Venice 전용 옵션은 `ModelSettings.extra_body`로 전달하세요. 예를 들어 `venice_parameters`로 내장 웹 검색을 활성화할 수 있습니다: ```python theme={"system"} import os from pydantic_ai import Agent, ModelSettings from pydantic_ai.models.openai import OpenAIChatModel from pydantic_ai.providers.openai import OpenAIProvider model = OpenAIChatModel( "venice-uncensored", provider=OpenAIProvider( base_url="https://api.venice.ai/api/v1", api_key=os.environ["VENICE_API_KEY"], ), ) agent = Agent( model, model_settings=ModelSettings( extra_body={ "venice_parameters": { "enable_web_search": "auto", } } ), ) result = agent.run_sync("이번 주 주목할 만한 AI 프라이버시 관련 소식은 뭐야?") print(result.output) ``` 실행별로 설정을 재정의할 수도 있습니다: ```python theme={"system"} result = agent.run_sync( "오늘 나온 탈중앙 AI 관련 헤드라인을 요약해줘.", model_settings=ModelSettings( extra_body={"venice_parameters": {"enable_web_search": "on"}} ), ) ``` 전체 `venice_parameters` 목록(웹 스크래핑, 인용, 캐릭터, 사고 제어, E2EE 토글)은 [API 사양](/api-reference/api-spec)을 참고하세요. ## 권장 모델 | 사용 사례 | 모델 | 이유 | | --------------- | -------------------------------- | ------------------- | | 일반 에이전트 | `venice-uncensored` | 빠르고, 저렴하고, 비검열 | | 도구 호출 / 구조화된 출력 | `zai-org-glm-5-1` | 에이전트용 강력한 프라이빗 플래그십 | | 복잡한 추론 | `zai-org-glm-5-1` | 더 나은 다단계 계획 수립 | | 예산 / 대량 처리 | `qwen3-5-9b` | 토큰당 저비용 | | 코드 중심 에이전트 | `qwen3-coder-480b-a35b-instruct` | 코드에 최적화 | 모델 ID는 시간이 지남에 따라 변경됩니다 — 현재 ID는 [`GET /models`](/api-reference/endpoint/models/list) 또는 [모델 개요](/models/overview)에서 확인하세요. ## 프라이버시 이점 PydanticAI는 애플리케이션 데이터, 사용자 컨텍스트, 내부 도구를 다루는 에이전트에 자주 사용됩니다. Venice와 함께 사용하면 그러한 워크플로를 프라이빗, 비검열 추론 위에서 유지할 수 있습니다: * 프라이빗 모델의 **데이터 보존 제로(zero data retention)** — 요청 이후 프롬프트와 도구 페이로드가 보관되지 않습니다 * 에이전트가 노골적인 비판이나 레드 티밍이 필요할 때의 **비검열 분석** * **OpenAI 호환 배선** 덕분에 공급자 base URL과 API 키만 바꾸면 기존 PydanticAI 앱을 마이그레이션할 수 있습니다 ## 문제 해결 에이전트를 실행하는 프로세스에 `VENICE_API_KEY`(또는 `OPENAI_API_KEY`)가 설정되어 있는지 확인하세요. 환경 변수를 변경한 후에는 셸이나 프로세스를 재시작하세요. [모델 페이지](/models/overview)에서 최신 모델 ID를 사용하세요. `base_url`은 뒤에 경로 없이 `https://api.venice.ai/api/v1`로 설정하세요 — PydanticAI가 `/chat/completions`를 덧붙입니다. `OpenAIChatModel`을 명시적인 `OpenAIProvider`와 함께 사용하는 것이 좋습니다. Chat Completions 대신 OpenAI의 Responses API를 대상으로 할 수 있는 단순 `openai:` 에이전트 단축 표기는 피하세요. [함수 호출](/guides/features/function-calling)을 지원하는 모델을 선택하고, `instructions`에 도구를 언제 실행해야 하는지 서술하며, 도구 docstring을 정확하게 유지하세요 — PydanticAI는 시그니처와 docstring으로부터 JSON 스키마를 만듭니다. 에이전트, 도구, 의존성, 출력 타입 모델과 지원 기능을 둘러보세요