> ## 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.

# TEI (Text Embeddings Inference)

HuggingFace에서 개발한 **임베딩 추론 서버**입니다. 텍스트를 벡터(임베딩)로 변환하는 작업에 최적화되어 있습니다.

## 어디에 쓰이나요?

* **RAG 파이프라인**: 문서를 임베딩으로 변환하여 벡터 DB(Qdrant, Milvus 등)에 저장
* **시맨틱 검색**: 사용자 질문을 임베딩으로 변환하여 유사한 문서 검색
* **문장 유사도**: 두 텍스트 간의 의미적 유사도 계산
* **리랭킹(Reranking)**: 검색 결과의 관련성을 재평가하여 순위 재정렬

OpenAI Embeddings API와 호환되는 형식으로 서빙하므로, 기존 OpenAI 임베딩을 사용하던 코드를 수정 없이 로컬 모델로 전환할 수 있습니다.

## Docker Compose

### GPU 환경

```yaml docker-compose.yml theme={null}
services:
  tei:
    image: ghcr.io/huggingface/text-embeddings-inference:latest
    container_name: tei
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - tei_data:/data
    command: >
      --model-id BAAI/bge-m3
      --max-client-batch-size 64
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

volumes:
  tei_data:
```

### CPU 환경

GPU가 없는 환경에서는 CPU 전용 이미지를 사용합니다.

```yaml docker-compose.yml theme={null}
services:
  tei:
    image: ghcr.io/huggingface/text-embeddings-inference:cpu-latest
    container_name: tei
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - tei_data:/data
    command: >
      --model-id BAAI/bge-m3
      --max-client-batch-size 32

volumes:
  tei_data:
```

## 실행

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

## 접속 확인

```bash theme={null}
curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "input": "안녕하세요, 임베딩 테스트입니다.",
    "model": "BAAI/bge-m3"
  }'
```

## 기본 정보

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

## 주요 실행 옵션

| 옵션                          | 설명                    |
| --------------------------- | --------------------- |
| `--model-id`                | HuggingFace 임베딩 모델 ID |
| `--max-client-batch-size`   | 최대 배치 크기              |
| `--max-concurrent-requests` | 최대 동시 요청 수            |
| `--tokenization-workers`    | 토크나이저 워커 수            |

## 추천 임베딩 모델

| 모델                                       | 차원   | 다국어 | 용도         |
| ---------------------------------------- | ---- | --- | ---------- |
| `BAAI/bge-m3`                            | 1024 | O   | 범용 다국어 임베딩 |
| `BAAI/bge-large-en-v1.5`                 | 1024 | X   | 영어 고성능     |
| `intfloat/multilingual-e5-large`         | 1024 | O   | 다국어 검색     |
| `sentence-transformers/all-MiniLM-L6-v2` | 384  | X   | 경량 영어 임베딩  |

## 라이선스

| 구분     | 내용                                     |
| ------ | -------------------------------------- |
| 라이선스   | Apache License 2.0                     |
| 개인 사용  | 자유롭게 사용 가능                             |
| 상업적 사용 | 자유롭게 사용 가능. 단, 사용하는 모델의 라이선스는 별도 확인 필요 |

## 참고

* [TEI 공식 문서](https://huggingface.co/docs/text-embeddings-inference)
* [TEI GitHub](https://github.com/huggingface/text-embeddings-inference)

## 설치 점검 목록

* `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="다음: LocalAI" icon="arrow-right" href="/stacks/localai">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>