Skip to main content
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-idHuggingFace 임베딩 모델 ID
--max-client-batch-size최대 배치 크기
--max-concurrent-requests최대 동시 요청 수
--tokenization-workers토크나이저 워커 수

​
추천 임베딩 모델

모델차원다국어용도
BAAI/bge-m31024O범용 다국어 임베딩
BAAI/bge-large-en-v1.51024X영어 고성능
intfloat/multilingual-e5-large1024O다국어 검색
sentence-transformers/all-MiniLM-L6-v2384X경량 영어 임베딩

​
라이선스

구분내용
라이선스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

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