Ollama
Ollama
이 문서에서는 pydantic-ai에서 OllamaModel을 설치하고 설정하는 방법을 알려드려요. Ollama는 로컬(또는 원격)의 자체 호스팅 서버와 Ollama Cloud를 모두 지원해요. 기본 URL과 API 키를 환경 변수로 설정한 뒤 모델을 이름으로 사용하거나 직접 초기화하면 돼요. 커스텀 Provider를 넘겨서 구성을 더 세밀하게 조정할 수도 있어요.
출처: 문서
본문
Install
OllamaModel을 사용하려면 pydantic-ai를 설치하거나, openai 옵션 그룹과 함께 pydantic-ai-slim을 설치해야 해요:
Terminal
pip install "pydantic-ai-slim[openai]"
Terminal
uv add "pydantic-ai-slim[openai]"
Configuration
Pydantic AI는 자체 호스팅 Ollama 서버(로컬 또는 원격 실행)와 Ollama Cloud를 모두 지원해요.
로컬에서 실행하는 서버에는 http://localhost:11434/v1 기본 URL을 사용하세요. Ollama Cloud에는 https://ollama.com/v1을 사용하고 API 키가 설정되어 있는지 확인하세요.
역호환성을 위해 OllamaModel은 Ollama의 OpenAI 호환 Chat Completions API(/v1/chat/completions)를 사용해요.
Environment variable
OLLAMA_BASE_URL과 (선택적으로) OLLAMA_API_KEY 환경 변수를 설정하세요:
Terminal
export OLLAMA_BASE_URL='http://localhost:11434/v1'
export OLLAMA_API_KEY='your-api-key' # required for Ollama Cloud
그 다음 이름으로 OllamaModel을 사용할 수 있어요:
from pydantic_ai import Agent
agent = Agent('ollama:qwen3')
...
또는 모델 이름만으로 모델을 직접 초기화할 수도 있어요:
from pydantic_ai import Agent
from pydantic_ai.models.ollama import OllamaModel
model = OllamaModel('qwen3')
agent = Agent(model)
...
provider argument
provider 인자를 통해 커스텀 Provider를 제공할 수 있어요:
from pydantic_ai import Agent
from pydantic_ai.models.ollama import OllamaModel
from pydantic_ai.providers.ollama import OllamaProvider
model = OllamaModel(
'qwen3', provider=OllamaProvider(base_url='http://localhost:11434/v1')
)
agent = Agent(model)
...
Ollama Cloud에는 base_url='https://ollama.com/v1'을 사용하고 OLLAMA_API_KEY 환경 변수를 설정하세요(또는 api_key=로 직접 전달).
Structured output
자체 호스팅 Ollama(v0.5.0+, 2024년 12월 릴리스)는 llama.cpp의 grammar 제약 디코더를 통해 json_schema로 response_format을 강제하므로, NativeOutput이 생성 시점에 스키마를 만족하는 출력을 만들어요:
from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai.models.ollama import OllamaModel
from pydantic_ai.output import NativeOutput
from pydantic_ai.providers.ollama import OllamaProvider
class CityLocation(BaseModel):
city: str
country: str
model = OllamaModel(
'qwen3',
provider=OllamaProvider(base_url='http://localhost:11434/v1'),
)
agent = Agent(model, output_type=NativeOutput(CityLocation))
...
Ollama Cloud는 아직 json_schema를 강제하지 않아요
Ollama Cloud의 추론 백엔드는 json_schema로 response_format을 오류 없이 받아들이지만 grammar 제약 디코딩을 적용하지 않으므로, 스키마가 조용히 강제되지 않아요. 상류 추적 이슈는 ollama/ollama#12362를 참고하세요.
OllamaModel이 Cloud 경로를 감지하면 — ollama.com의 base_url 또는 -cloud로 끝나는 모델 이름 — 프로필에서 supports_json_schema_output을 자동으로 비활성화해요.
Ollama Cloud 모델과 함께 NativeOutput을 사용하면 조용한 재시도 루프 대신 명확한 UserError를 받게 돼요. 대신 기본 ToolOutput 또는 PromptedOutput을 사용하세요 — 둘 다 Cloud에서 동작해요.