TEI (Text Embeddings Inference)

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

어디에 쓰이나요?

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

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

Docker Compose

GPU 환경

docker-compose.yml

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 전용 이미지를 사용합니다.

docker-compose.yml

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:

실행

docker compose up -d

접속 확인

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
개인 사용	자유롭게 사용 가능
상업적 사용	자유롭게 사용 가능. 단, 사용하는 모델의 라이선스는 별도 확인 필요

참고

설치 점검 목록

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

문제 해결 가이드

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

Setup 홈

운영체제별 설치 흐름을 다시 확인합니다.

다음: LocalAI

다음 설치 단계를 이어서 진행합니다.

00. 배움 에이아이 소개

01. OS별 개발환경

02. 컨테이너 스택

03. Python 환경 설정

어디에 쓰이나요?

Docker Compose

GPU 환경

CPU 환경

실행

접속 확인

기본 정보

주요 실행 옵션

추천 임베딩 모델

라이선스

참고

설치 점검 목록

문제 해결 가이드

관련 문서

Setup 홈

다음: LocalAI

​어디에 쓰이나요?

​Docker Compose

​GPU 환경

​CPU 환경

​실행

​접속 확인

​기본 정보

​주요 실행 옵션

​추천 임베딩 모델

​라이선스

​참고

​설치 점검 목록

​문제 해결 가이드

​관련 문서

Setup 홈

다음: LocalAI

어디에 쓰이나요?

Docker Compose

GPU 환경

CPU 환경

실행

접속 확인

기본 정보

주요 실행 옵션

추천 임베딩 모델

라이선스

참고

설치 점검 목록

문제 해결 가이드

관련 문서