9분 읽기 2026년 6월 7일

Odysseus AI Ollama 설정: 로컬 모델 연결 방법

Docker와 native 환경의 Odysseus AI Ollama 설정을 endpoint 예시, 모델 확인, provider 오류 점검과 함께 설명합니다.

Odysseus AI Wiki
Odysseus AI Wiki
Odysseus AI 공개 문서와 로컬 셀프 호스팅 사례를 바탕으로 작성한 비공식 편집 노트입니다.
Odysseus AI와 Ollama 로컬 모델 endpoint 연결을 보여 주는 설정 다이어그램

빠른 답변: Odysseus AI가 Docker에서 실행되고 Ollama가 host에서 실행되면 먼저 http://host.docker.internal:11434/v1을 사용합니다. 같은 컴퓨터에서 둘 다 native로 실행하면 http://127.0.0.1:11434/v1부터 확인하세요. Ollama가 실행 중이고 모델 목록에 대상 모델이 있는지 확인한 뒤 provider를 바꾸세요.

이 가이드의 내용

Odysseus AI Ollama 설정은 두 가지를 분리해서 확인해야 합니다. Ollama 서버가 응답해야 하고, Odysseus AI가 현재 runtime 네트워크에서 올바른 엔드포인트에 도달해야 합니다. 이 가이드는 Docker-to-host 연결, Windows/Linux/macOS 네이티브 설정, 로컬 모델 확인 예시, 프로바이더는 연결되지만 모델이 보이지 않는 경우를 다룹니다.

실행 환경에 맞는 Ollama endpoint 선택

Odysseus AI Ollama 설정에서 가장 흔한 실수는 native localhost URL을 Docker container 안에 그대로 넣는 것입니다. endpoint는 Ollama가 설치된 위치가 아니라 Odysseus 프로세스에서 접근 가능한 주소로 선택해야 합니다.

Odysseus AI가 Docker, Ollama가 host라면 host.docker.internal:11434/v1을 사용합니다. 둘 다 같은 컴퓨터에서 native로 실행하면 127.0.0.1:11434/v1부터 시도하세요. prompt나 agent를 점검하기 전에 Ollama와 모델 목록을 먼저 확인합니다.

Docker에서 host Ollama로 연결하는 endpoint
http://host.docker.internal:11434/v1

Docker에서 host Ollama로 연결하고 확인하기

Docker 기반 Odysseus AI Ollama 설정은 네트워크 경계를 넘습니다. container 안의 localhost는 container 자체를 가리키므로 host endpoint를 명시하고 Ollama가 접근 가능한 주소에서 대기해야 합니다.

첫 테스트는 로컬로 제한하세요. 포트를 공개하거나 모델 tag를 바꾸기 전에 container에서 Ollama로 가는 한 경로가 정상인지 확인합니다.

1. 필요할 때 Ollama가 자체 loopback 밖에서도 수신하도록 시작

Docker가 Ollama에 도달하지 못하면 명시적인 host binding으로 Ollama를 시작하세요. 네트워크 노출을 이해하지 못한다면 신뢰할 수 있는 로컬 사용으로 제한합니다.

OLLAMA_HOST=0.0.0.0:11434 ollama serve

2. Ollama에 모델이 하나 이상 있는지 확인

Ollama가 아직 모델을 가져오지 않았다면 Odysseus AI가 endpoint에 연결되어도 사용할 모델이 표시되지 않을 수 있습니다. 연결만 테스트한다면 먼저 작은 모델을 받으세요.

ollama list
ollama pull llama3.2:3b

3. Odysseus AI 설정에 Docker 엔드포인트 입력

모델 또는 서비스 설정에서 OpenAI 호환 base URL을 사용하세요. Docker 플랫폼을 다르게 구성하지 않았다면 이 Docker-to-host 경로에서 localhost를 사용하지 않습니다.

http://host.docker.internal:11434/v1

4. 프롬프트를 디버깅하기 전에 컨테이너 상태 확인

Odysseus 서비스가 불안정하다면 먼저 이를 수정하세요. 모델 endpoint로는 깨진 컨테이너 시작, 누락된 환경 파일 또는 비정상 dependency를 고칠 수 없습니다.

docker compose ps
docker compose logs --tail=120 odysseus

Windows·Linux·macOS native Ollama 설정

Odysseus AI와 Ollama를 같은 OS 세션에서 native로 실행하면 localhost는 보통 예상한 컴퓨터를 가리킵니다. UI 포트는 설치 방식에 따라 달라질 수 있지만 OLLAMA_HOST를 바꾸지 않았다면 Ollama는 보통 11434를 사용합니다.

Mac 설치 선택은 기존 macOS 가이드를, Windows와 하드웨어 계획은 requirements 및 플랫폼 가이드를 다음 단계로 사용해 이 연결 페이지의 의도를 유지하세요.

설정 먼저 시도할 엔드포인트 확인할 점
Windows native Odysseus + Windows Ollama http://127.0.0.1:11434/v1 두 서비스를 같은 Windows 컴퓨터에서 native로 실행하면 localhost를 사용합니다.
Linux native Odysseus + Ollama http://127.0.0.1:11434/v1 프로세스가 백그라운드 서비스로 실행된다면 서비스 권한을 확인하세요.
macOS 또는 Apple Silicon native 경로 http://127.0.0.1:11434/v1 Odysseus UI 포트는 다를 수 있지만 Ollama는 보통 11434를 유지합니다.
Docker의 Odysseus + host Ollama http://host.docker.internal:11434/v1 컨테이너 localhost는 host 머신이 아니므로 Docker host 이름을 사용합니다.

Odysseus AI Ollama 프로바이더와 엔드포인트 오류 해결

오류는 Ollama 프로세스, 접근 가능한 endpoint, 모델 목록, provider 설정, prompt 순서로 확인합니다. 그러면 네트워크 문제를 모델 품질 문제로 착각하지 않습니다.

증상 가능한 원인 해결 방법
연결 거부 Ollama가 실행되지 않았거나 Odysseus가 접근할 수 없는 곳에서만 수신 중입니다. Ollama를 시작하고 11434 포트를 확인한 뒤 Docker-to-host 테스트에 명시적 OLLAMA_HOST 바인딩을 사용하세요.
host 브라우저는 작동하지만 Docker는 실패 endpoint가 컨테이너 내부의 localhost를 사용합니다. endpoint를 http://host.docker.internal:11434/v1 로 변경하세요.
모델이 표시되지 않음 모델을 받지 않았거나 모델 tag가 잘못되었습니다. ollama list를 실행하고 작은 모델을 받은 뒤 정확한 tag를 선택하세요.
첫 응답이 느림 모델을 로드 중이거나 시스템에 비해 너무 큽니다. agent, tool 또는 문서보다 먼저 더 작은 모델을 테스트하세요.
예상하지 못한 LAN 노출 신뢰 경계 없이 서비스가 모든 인터페이스에 바인딩되었습니다. 방화벽, VPN, 인증을 의도적으로 설정한 경우가 아니라면 localhost 전용 바인딩으로 돌아가세요.

설정을 신뢰하기 전 최종 체크리스트

정상적인 설정은 이 점검을 순서대로 통과해야 합니다. 첫 번째 실패에서 멈추고 해당 계층을 먼저 수정하세요.

  1. 호스트의 Ollama가 응답하고 ollama list에 모델이 표시됩니다.
  2. Odysseus 서비스가 Docker 또는 native 로그에서 정상입니다.
  3. endpoint가 runtime 구성과 일치합니다.
  4. 더 큰 agent나 문서 workflow 전에 작은 prompt가 동작합니다.
  5. LAN에 노출되는 경우 인증되며 의도된 설정이어야 합니다.
첫 설정은 로컬로 유지

Odysseus AI를 Ollama에 연결하기 위해 두 서비스를 인터넷에 공개할 필요는 없습니다. 인증, 방화벽, reverse proxy 동작을 의도적으로 정하기 전까지는 로컬로 유지하세요.

2026년 Odysseus AI Ollama 설정 확인 메모

모델 이름을 바꾸기 전에 runtime 경계와 base URL을 확인하세요. 같은 Ollama 서버도 native에서는 localhost, container에서는 host.docker.internal이 필요할 수 있습니다.

모델 목록을 확인하고 Odysseus AI와 같은 실행 계층에서 endpoint를 테스트한 뒤 provider 설정을 저장하세요. 첫 요청이 실패해도 연결을 확인하기 전에는 모델 tag를 바꾸지 않습니다.

확인 항목 정상 결과 실패 시 조치
호스트 Ollama API Odysseus를 사용하기 전에 호스트가 http://127.0.0.1:11434에 연결됩니다. Ollama를 시작하고 작은 모델을 받은 뒤 API를 먼저 테스트합니다.
Docker에서 호스트로 연결 컨테이너의 Odysseus는 host.docker.internal:11434/v1을 사용합니다. 컨테이너 안에서 localhost를 사용하지 않는지 확인하고 경계를 분리해 점검합니다.
네이티브 경로 같은 컴퓨터의 네이티브 Odysseus와 Ollama는 127.0.0.1:11434/v1을 사용합니다. Docker용 호스트 이름을 제거하고 작은 프롬프트로 테스트합니다.
  1. 앱 실행 확인, Ollama API 확인, 모델 태그 확인을 순서대로 진행합니다.
  2. 설정은 한 번에 하나만 바꾸고 성공한 엔드포인트를 기록합니다.
  3. 이 페이지의 의도를 관련 설정 가이드와 분리해 유지합니다.

Odysseus AI Ollama 설정 FAQ

Odysseus AI가 Docker, Ollama가 host라면 먼저 http://host.docker.internal:11434/v1을 사용합니다. 연결되지 않으면 모델을 바꾸기 전에 Ollama binding과 Docker network를 확인하세요.

provider가 OpenAI 호환 형식을 요구하면 /v1이 포함된 base URL을 사용합니다. 문서에 맞는 URL을 입력하고 동일한 주소를 직접 테스트하세요.

아니요. 이 구성에서 Ollama는 별도의 모델 서버입니다. Odysseus AI는 연결만 하며 컨테이너 안에서 Ollama를 시작하지 않습니다.

Odysseus AI와 Ollama를 Windows에서 native로 실행한다면 먼저 http://127.0.0.1:11434/v1 을 시도하세요. Odysseus가 Docker에 있고 Ollama가 host에 있을 때만 host.docker.internal을 사용합니다.

Ollama가 응답해도 모델을 pull하지 않았거나 tag가 다를 수 있습니다. ollama list로 tag를 확인한 뒤 Odysseus AI 모델 필드를 점검하세요.

일반적으로 따로 설치합니다. Ollama는 모델 서버이고 Odysseus AI는 연결하는 workspace입니다. 각 계층을 따로 시작한 뒤 연결을 확인하세요.

출처와 공식 참고 자료

  1. Odysseus AI 공식 GitHub 저장소 - Docker, Windows, Apple Silicon, Ollama 엔드포인트 안내입니다.
  2. Ollama API 문서 - 로컬 모델 서버 API의 동작을 설명합니다.
  3. Docker Desktop 네트워킹 문서 - host.docker.internal을 통한 호스트 네트워크 동작입니다.

관련 Odysseus AI 설정 가이드

최종 업데이트: 2026년 8월 13일

Odysseus AI Wiki로 돌아가기