Ollama API로 첫 로컬 AI 앱 만들기

Ollama가 실행 중이고 모델이 다운로드되어 있다면 로컬 기본 주소에서 요청을 받을 수 있습니다. 먼저 curl로 서버·모델·응답을 한 번에 확인하세요.

공식 API는 로컬과 클라우드 주소가 다릅니다. 민감한 데이터라면 코드의 base URL이 localhost인지 반드시 확인합니다.

curl http://localhost:11434/api/generate -d '{
  "model": "gemma3:4b",
  "prompt": "로컬 AI를 한 문장으로 설명해줘",
  "stream": false
}'

`/api/chat`은 model과 messages가 핵심입니다. system, user, assistant 역할을 순서대로 보관하면 여러 턴의 문맥을 구성할 수 있습니다. 서버가 과거 대화를 자동으로 기억한다고 가정하지 말고 애플리케이션이 필요한 메시지를 명시적으로 관리하세요.

긴 대화를 전부 다시 보내면 메모리와 지연이 커집니다. 오래된 대화는 요약하거나 새 세션으로 나누고, 중요한 원문은 별도의 검색 단계에서 가져오는 편이 좋습니다.

curl http://localhost:11434/api/chat -d '{
  "model": "gemma3:4b",
  "messages": [{"role": "user", "content": "세 가지 핵심만 알려줘"}],
  "stream": false
}'

Chat API는 기본적으로 스트리밍하며 여러 JSON 조각을 연속으로 보냅니다. 빠르게 첫 글자를 보여주는 UI에는 유리하지만 클라이언트가 조각을 순서대로 합치고 중단·오류를 처리해야 합니다.

초기 개발과 자동화는 `stream:false`로 전체 응답을 한 번에 받아 구조를 확인한 뒤 스트리밍을 추가하는 편이 단순합니다. 응답의 load_duration, eval_duration, 토큰 수는 병목을 비교하는 관찰값으로 활용할 수 있습니다.

공식 Structured Outputs 기능은 `format`에 JSON 스키마를 넣어 응답 구조를 제한합니다. temperature를 낮추면 반복 실행의 변동을 줄이는 데 도움이 됩니다.

스키마를 지정해도 내용의 사실성까지 보장되지는 않습니다. JSON 파싱, 필수 필드, 값 범위와 원문 근거를 애플리케이션에서 다시 검사하세요.

• 스키마에 필수 필드 명시
• temperature 낮게 설정
• 파싱 실패 재시도 제한
• 값 범위와 길이 검증
• 원문에 없는 사실은 별도 확인

모델이 없거나 서버가 꺼졌을 때, 요청이 너무 길 때, 사용자가 생성을 취소할 때의 동작을 정합니다. 무한 재시도는 메모리와 전력을 낭비하므로 횟수와 시간 제한을 둡니다.

API 호출 로그에 프롬프트 전체를 남기면 로컬 처리의 장점을 잃을 수 있습니다. 기본 로그는 요청 ID, 모델, 지연, 오류 코드처럼 진단에 필요한 최소 정보로 제한합니다.

같은 사용자 계정에서 실행되는 다른 프로그램은 로컬 포트에 접근할 수 있습니다. 서버를 0.0.0.0이나 외부 네트워크에 노출하면 위험이 더 커집니다.

외부 공개가 필요하다면 인증 프록시, 허용 IP, TLS, 요청 제한과 감사 로그를 먼저 구성하세요. 개인용 첫 앱은 localhost 범위에서 완성하는 것이 안전합니다.