서론
Ollama는 로컬 LLM의 실행 환경으로 간편하지만, GUI나 CLI뿐만 아니라 HTTP API도 제공합니다. 본 기사에서는 PowerShell 5.1의 Invoke-RestMethod만을 사용하여 추가 도구 없이 Ollama의 API를 다뤄본 결과를 정리했습니다. 네이티브한 /api 계열과 OpenAI 호환인 /v1 계열 두 가지 모두 확인해 보겠습니다.
환경
- Windows 11 (빌드 10.0.26200)
- PowerShell 5.1
- Ollama 0.40.4 (공식 앱. 서버는 기본
http://127.0.0.1:11434)
- 모델:
qwen2.5:0.5b (검증용 소형 모델)
진행 과정
1. 버전 및 연결 확인
(Invoke-RestMethod http://127.0.0.1:11434/api/version).version
실행 결과:
(Invoke-RestMethod http://127.0.0.1:11434/api/tags).models | Select-Object name, size
실행 결과 (발췌):
name size
----
qwen2.5:0.5b 397821319
...
size는 바이트 단위입니다. /api/ps가 아니라 **/api/tags**가 '디스크 상의 모델 목록'이라는 점에 유의하세요.
3. 텍스트 생성 (/api/generate)
stream을 false로 설정하면, 생성이 끝난 후에 JSON이 일괄적으로 반환됩니다.
$body = @{
model = "qwen2.5:0.5b"
prompt = "Reply with exactly: connection-ok"
...
실행 결과:
응답에는 생성 결과 외에도 eval_count (생성 토큰 수)나 total_duration (나노초) 등의 통계가 포함됩니다. 실측 기준으로 첫 번째 요청의 total_duration이 약 30초였습니다. 이는 소형 모델이라도 모델 로드 시간이 포함되기 때문이며, 두 번째 요청부터는 크게 단축됩니다.
4. OpenAI 호환 엔드포인트 (/v1)
OpenAI API 클라이언트에서 익숙한 형식도 제공됩니다.
# 모델 목록
(Invoke-RestMethod http://127.0.0.1:11434/v1/models).data.id
# 채팅 완성
...
실행 결과:
/v1 계열은 max_tokens, messages[].role 등 OpenAI 호환 필드명으로 통신할 수 있습니다. Ollama용 클라이언트를 작성할 때 기존의 OpenAI 클라이언트를 재사용하고 싶다면 이곳이 편리합니다.
어려웠던 점 (주의사항)
- JSON 본문의 한글이나 특수문자:
charset=utf-8을 명시하는 `-ContentType
첫 로드 시간(initial load time)의 3가지.
다음으로 API를 가지고 놀아보고 싶다면, stream = $true로 하는 스트리밍 표시나, /api/chat에서의 대화 기록 처리를 다루는 것이 재미있을 것입니다.
관련 도서
이 기사에서 다룬 API의 후속 내용(스트리밍, VRAM, 정기 실행, 운영)을 한 권에 모았습니다. 제1장과 제2장은 무료로 읽으실 수 있습니다.
토론
