· Colinch NAS · 6 min read

Home Assistant 2026.8 llama.cpp 연결 - Synology NAS에서 로컬 AI 대화 에이전트 설정

Home Assistant 2026.8에 추가된 llama.cpp 통합을 Synology NAS Docker 서버와 연결하고, 모델 API 확인·엔티티 공개·보안 설정까지 실제 순서로 정리한다.

Synology NAS와 Home Assistant 로컬 AI 구성

이 그림에서 봐야 할 부분은 Home Assistant가 모델을 직접 실행하는 게 아니라, NAS 안의 llama.cpp 서버에 질문을 보내고 필요한 기기만 제어 대상으로 넘긴다는 점이다.

Home Assistant 2026.8(2026년 8월 5일 공개)부터 llama.cpp가 공식 대화 에이전트 통합으로 들어왔다. OpenAI 호환 Chat Completions API를 제공하는 로컬 서버라면 연결할 수 있다. Synology NAS에서는 모델을 NAS에서 실행하고 Home Assistant는 기존 Docker 또는 VMM 인스턴스를 그대로 쓰는 구성이 관리하기 편했다.

구성과 사전 조건

항목이번 구성
NASSynology DS923+, DSM 7.2.2
Home Assistant2026.8.x, Docker 또는 HA OS VM
AI 서버llama.cpp server, NAS 내부 8080 포트
모델GGUF 형식의 instruct 모델
네트워크같은 내부망, 외부 포트포워딩 없음

RAM이 4GB인 NAS에서 큰 모델을 올리면 답변이 느리거나 컨테이너가 종료된다. 처음에는 3B~4B급 양자화 모델로 테스트하고, 실제 기기 제어보다 상태 조회부터 확인하는 편이 안전하다.

NAS에 llama.cpp 서버 올리기

Container Manager에서 프로젝트를 만들기 전에 /volume1/docker/llama/models에 검증한 GGUF 파일을 넣는다. 아래 Compose는 CPU 실행을 전제로 한 최소 구성이다.

services:
  llama:
    image: ghcr.io/ggml-org/llama.cpp:server
    container_name: llama-home
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - /volume1/docker/llama/models:/models:ro
    command: >-
      -m /models/home-model.gguf
      --host 0.0.0.0
      --port 8080
      --alias home-model

home-model.gguf는 실제 파일명으로 바꾼다. 프로젝트를 배포한 뒤 NAS 터미널에서 API가 응답하는지 확인한다. 이 단계에서 안 되면 Home Assistant 문제가 아니라 모델 경로, 권한, 메모리 문제다.

curl http://127.0.0.1:8080/v1/models

응답의 id가 보이면 Home Assistant가 접근할 준비가 된 상태다. 127.0.0.1은 NAS 터미널에서 실행할 때만 쓰고, 다른 컨테이너에서 접근할 때는 NAS 내부 IP를 사용한다.

Home Assistant 2026.8에서 연결

Home Assistant에서 설정 → 기기 및 서비스 → 통합 추가 → llama.cpp를 연다. URL에는 다음처럼 /v1까지 입력한다.

http://192.168.1.20:8080/v1

API 키를 요구하지 않는 로컬 서버라면 비워 둔다. 모델 선택 화면에서 home-model을 고르고, 옵션에서 지시문과 Home Assistant 제어 권한을 설정한다. 처음부터 모든 조명을 공개하지 말고 sensor, light.test처럼 테스트용 엔티티 1~2개만 노출한다.

내가 여기서 한 번 삽질한 부분은 http://192.168.1.20:8080까지만 입력한 것이다. llama.cpp의 호환 API 기본 경로는 /v1이라 통합 설정은 연결되지만 모델 목록을 못 읽을 수 있다. 또 Home Assistant와 llama 컨테이너를 서로 다른 Docker 네트워크에 두었다면 NAS IP로 접근하는 쪽이 확인하기 쉽다.

제어 권한과 보안 체크

llama.cpp 통합은 노출된 엔티티만 읽거나 제어한다. 설정 → 음성 어시스턴트 → 노출된 엔티티에서 테스트가 끝난 뒤에도 실제 제어가 필요한 장치만 남긴다. 도어락, 차고문, 보안 카메라, NAS 전원 스위치는 로컬 모델이라도 기본 공개 대상에서 빼는 게 맞다.

  • 공유기에서 8080을 인터넷으로 포워딩하지 않는다.
  • NAS 방화벽에서 8080은 내부망 또는 Home Assistant 호스트만 허용한다.
  • 모델 파일과 Compose 환경변수에 토큰·개인정보를 넣지 않는다.
  • 모델이 만든 문장을 자동화의 조건으로 바로 신뢰하지 않는다.
  • 업데이트 전 Home Assistant 백업과 모델 Compose 파일을 함께 보관한다.

짧은 요점 정리

Home Assistant 2026.8의 llama.cpp 통합은 NAS를 로컬 AI 대화 서버로 확장하는 공식 연결 지점이다. 핵심은 OpenAI 호환 API, URL의 /v1, 제한된 엔티티 공개 세 가지다. NAS CPU와 RAM이 빠듯하면 모델 크기를 줄이고, 외부 공개 없이 내부망에서 상태 조회부터 검증하는 순서가 가장 덜 위험하다.

참고: Home Assistant 2026.8 릴리스 노트, llama.cpp 통합 공식 문서

Share:
Back to Blog