Sentence Transformers

만든 곳 Hugging Face

임베딩 모델(bge-m3 등)을 로컬에서 실행해 텍스트를 벡터로 바꿉니다 — RAG·메모리용, API 불필요

웹사이트 ↗ 저장소 ↗ 문서 ↗

v5.6.12026-07-23PythonApache-2.0

#embeddings #rag #local #python

18.9k 완전 무료 오픈소스

문서버전 1.0 · 업데이트 2026년 6월 28일

개요

Sentence Transformers(SBERT)는 다국어 bge-m3 같은 임베딩 모델을 내 컴퓨터에서 직접 실행해, API 호출 없이 텍스트를 벡터로 바꿉니다.
RAG 파이프라인의 로컬·제공자 독립적인 절반입니다 — 임베딩은 여기서 만들고, 저장·검색은 벡터 스토어에서 합니다.

flowchart LR
  text[text] --> st[SentenceTransformer]
  st --> vec[vector]
  vec --> store[(vector store)]

코드 샘플 탭에는 텍스트 인코딩과 내장 유사도 검색 예시가 있습니다 — 선택기에서 골라 비교해 보세요.

언제 쓰면 좋은가

비용·프라이버시·오프라인 때문에 호스티드 임베딩 API 대신 로컬에서 임베딩을 계산하고 싶을 때 Sentence Transformers를 쓰세요.

예제

Python · encode

언제 쓰나

임베딩을 로컬에서 계산할 때 쓰세요 — 제공자 키 없이 오프라인에서 동작합니다.

흐름

encode가 Hugging Face 모델을 불러와, 저장하거나 비교할 수 있는 벡터 NumPy 배열을 돌려줍니다.

구조

flowchart LR
  text[text] --> st[SentenceTransformer]
  st --> vec[vector]
  vec --> use[store / compare]

from sentence_transformers import SentenceTransformer

# bge-m3 is multilingual and runs on CPU — no API key needed.
model = SentenceTransformer("BAAI/bge-m3")

vectors = model.encode(["how do I reset my password?", "비밀번호 재설정 방법"])
print(vectors.shape)  # (2, 1024)

언제 쓰나

벡터 DB 없이 빠르게 의미 검색을 하고 싶을 때 내장 similarity를 쓰세요.

흐름

말뭉치와 질의를 임베딩한 뒤, 코사인 유사도로 문서를 정렬합니다.

구조

flowchart LR
  docs[documents] --> emb[embeddings]
  q[query] --> qe[query vector]
  emb --> sim[cosine similarity]
  qe --> sim
  sim --> top[best match]

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("BAAI/bge-m3")
docs = ["cats are great pets", "the stock market fell", "kittens love to play"]
doc_emb = model.encode(docs)

query = model.encode("tell me about cats")
scores = model.similarity(query, doc_emb)[0]  # cosine similarity
print(docs[int(scores.argmax())])  # -> a cat-related sentence

예제

Sentence Transformers — 로컬 임베딩 + 유사도

실제로 실행 가능한 미니 프로젝트입니다. 받아서 Docker로 실행해 보세요.

GitHub에서 samples/sentence-transformers_1 보기 ↗

2026년 6월 28일

Sentence Transformers — 로컬 임베딩 + 유사도

아주 작은 Sentence Transformers 데모입니다. 문서 몇 개와 질의를 CPU에서 임베딩한 뒤, 코사인 유사도로 문서를 정렬합니다. API 키가 필요 없습니다 — 모델이 로컬에서 돕니다.

무거운 이미지. PyTorch(수 GB)를 받으므로 첫 빌드가 느립니다.

Docker로 실행

cd samples/sentence-transformers_1
docker build -t aas-sentence-transformers .
docker run --rm aas-sentence-transformers "tell me about young cats"

첫 실행에서 모델(all-MiniLM-L6-v2, 약 80 MB)을 받으므로 한 번은 인터넷이 필요합니다. 다국어가 필요하면 app.py에서 BAAI/bge-m3로 바꾸세요.

Docker로 실행 (DooD를 쓰는 devcontainer에서)

호스트 Docker 데몬과 통신하는 dev container(Docker-outside-of-Docker)에서는 attach된 docker run이 실제로 실행했는데도 출력을 안 보여줄 수 있습니다. 실시간 attach 스트림이 VM 경계에서 출력을 흘려버리기 때문이니, detached로 실행하고 로그로 확인하세요:

cd samples/sentence-transformers_1
docker build -t aas-sentence-transformers .
docker logs -f "$(docker run -d aas-sentence-transformers "tell me about young cats")"

로컬에서 실행

cd samples/sentence-transformers_1
pip install -r requirements.txt
python app.py "tell me about young cats"

실행 결과

임베딩은 고정 모델 + 입력이라 결정적입니다. 그래서 순위는 매번 같고, 첫 실행에서만 모델을 내려받습니다.

nearest to 'tell me about young cats' by cosine similarity:
  0.5793  A kitten is a young cat that loves to play and nap.
  0.4883  Cats are independent pets that purr and chase laser pointers.
  0.0734  A rocket is propelled by ejecting exhaust gas at high speed.

파일

app.py

"""Sentence Transformers: local embeddings + similarity search, no API key.

Embeds a few documents and a query with a model running on CPU, then ranks the
documents by cosine similarity. This is the local, provider-independent half of
a RAG pipeline.

Run:
    docker build -t aas-sentence-transformers .
    docker run --rm aas-sentence-transformers "tell me about young cats"
"""

import sys

from sentence_transformers import SentenceTransformer

DOCS = [
    "Cats are independent pets that purr and chase laser pointers.",
    "The stock market fell sharply today.",
    "A kitten is a young cat that loves to play and nap.",
    "A rocket is propelled by ejecting exhaust gas at high speed.",
]


def main() -> None:
    query = " ".join(sys.argv[1:]) or "tell me about young cats"

    # all-MiniLM-L6-v2 is small and fast; swap in BAAI/bge-m3 for multilingual.
    model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")

    doc_emb = model.encode(DOCS)
    query_emb = model.encode(query)
    scores = model.similarity(query_emb, doc_emb)[0]  # cosine similarity

    print(f"nearest to {query!r} by cosine similarity:")
    for doc, score in sorted(zip(DOCS, scores.tolist()), key=lambda x: -x[1])[:3]:
        print(f"  {score:.4f}  {doc}")


if __name__ == "__main__":
    main()

Dockerfile

# Image for the Sentence Transformers sample. Pulls PyTorch, so it is several GB
# and the first build is slow. No API key — the model runs on CPU.
FROM python:3.13-slim

ENV PYTHONUNBUFFERED=1

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

ENTRYPOINT ["python", "app.py"]

Sentence Transformers

관련 도구

개요

언제 쓰면 좋은가

가격

언제 쓰나

흐름

언제 쓰나

흐름

Docker로 실행

Docker로 실행 (DooD를 쓰는 devcontainer에서)

로컬에서 실행

실행 결과