> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# LocalAI

**OpenAI API 호환 로컬 추론 서버**입니다. 텍스트 생성, 임베딩, 이미지 생성, 음성 인식(STT), 음성 합성(TTS) 등 다양한 AI 기능을 하나의 서버에서 제공합니다.

## 어디에 쓰이나요?

* **올인원 AI 서버**: LLM, 임베딩, 이미지 생성, 음성 처리를 하나의 API로 통합
* **OpenAI 대체**: 기존 OpenAI API를 사용하는 코드의 엔드포인트만 변경하여 로컬 모델로 전환
* **CPU 추론**: GPU 없이도 GGUF 포맷 모델을 CPU에서 실행 가능
* **프라이버시**: 데이터가 외부로 전송되지 않는 완전한 로컬 환경

## Docker Compose

### CPU 환경

```yaml docker-compose.yml theme={null}
services:
  localai:
    image: localai/localai:latest-cpu
    container_name: localai
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - localai_data:/build/models
    environment:
      - DEBUG=false
      - THREADS=4

volumes:
  localai_data:
```

### GPU 환경 (NVIDIA CUDA)

```yaml docker-compose.yml theme={null}
services:
  localai:
    image: localai/localai:latest-gpu-nvidia-cuda-12
    container_name: localai
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - localai_data:/build/models
    environment:
      - DEBUG=false
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  localai_data:
```

## 실행

```bash theme={null}
docker compose up -d
```

## 접속 확인

```bash theme={null}
# 모델 목록 확인
curl http://localhost:8080/v1/models

# 텍스트 생성
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

## 기본 정보

| 항목     | 값                  |
| ------ | ------------------ |
| API 포트 | 8080               |
| API 형식 | OpenAI API 호환      |
| GPU    | 선택 (CPU 전용 이미지 제공) |

## 라이선스

| 구분     | 내용                       |
| ------ | ------------------------ |
| 라이선스   | MIT License              |
| 개인 사용  | 자유롭게 사용 가능               |
| 상업적 사용 | 자유롭게 사용 가능, 수정/재배포 제한 없음 |

## 참고

* [LocalAI 공식 문서](https://localai.io/)
* [LocalAI GitHub](https://github.com/mudler/LocalAI)

## 설치 점검 목록

* `docker compose up -d` 후 `docker compose ps`로 컨테이너 상태를 확인했습니다.
* 기본 포트/계정/비밀번호를 문서대로 점검했습니다.
* 운영용으로 사용할 때 기본 비밀번호/시크릿 값을 변경했습니다.
* 장애 분석을 위해 `docker compose logs -f` 확인 방법을 숙지했습니다.

## 문제 해결 가이드

* 컨테이너가 실행되지 않으면 `docker compose logs -f`로 오류 원인을 먼저 확인합니다.
* 포트 충돌이 나면 기존 프로세스를 종료하거나 포트 매핑 값을 변경합니다.
* 이미지 pull 실패 시 네트워크 연결 및 레지스트리 접근 권한을 확인합니다.
* 설정 변경 후 문제가 지속되면 `docker compose down` 후 다시 `up -d`로 재기동합니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Setup 홈" icon="house" href="/setup/index">
    운영체제별 설치 흐름을 다시 확인합니다.
  </Card>

  <Card title="다음: Dify" icon="arrow-right" href="/stacks/dify">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>