Integrations

OpenAIEmbeddings

OpenAI 임베딩 모델 클래스: model, dimensions, 배치 크기, 토큰 길이 처리

#openai#embeddings#rag공식 문서

OpenAIEmbeddings는 OpenAI 임베딩 API를 LangChain Embeddings 인터페이스로 감싼 클래스입니다. 벡터 스토어, InMemoryStore(index=...), 시맨틱 캐시 등 임베딩을 받는 곳에 그대로 넘깁니다. 이 프로젝트의 표준 설정은 OpenAIEmbeddings(model="text-embedding-3-small")입니다.

Import

python
from langchain_openai import OpenAIEmbeddings      # pip install langchain-openai
from langchain.embeddings import init_embeddings   # 문자열로 생성: init_embeddings("openai:text-embedding-3-small")

시그니처

python
OpenAIEmbeddings(
    *,
    model: str = "text-embedding-ada-002",
    dimensions: int | None = None,
    api_key: SecretStr | None | Callable[[], str] | Callable[[], Awaitable[str]] = <env OPENAI_API_KEY>,
    base_url: str | None = <env>,
    organization: str | None = <env>,
    chunk_size: int = 1000,
    embedding_ctx_length: int = 8191,
    check_embedding_ctx_length: bool = True,
    tiktoken_enabled: bool = True,
    tiktoken_model_name: str | None = None,
    max_retries: int = 2,
    timeout: float | tuple[float, float] | Any | None = None,
    retry_min_seconds: int = 4,
    retry_max_seconds: int = 20,
    skip_empty: bool = False,
    show_progress_bar: bool = False,
    model_kwargs: dict[str, Any] = {},
    default_headers: Mapping[str, str] | None = None,
    http_client: Any | None = None,
    # ... deployment, api_version, openai_api_type, openai_proxy, allowed_special,
    #     disallowed_special, headers, default_query, http_async_client
)

파라미터

파라미터타입기본값설명
modelstr"text-embedding-ada-002"임베딩 모델. 기본값이 구형이므로 항상 명시하세요(text-embedding-3-small/-large)
dimensionsint | NoneNone출력 차원 축소(text-embedding-3-*만 지원). None이면 모델 기본(small 1536, large 3072)
api_keySecretStr | CallableOPENAI_API_KEYAPI 키
base_urlstr | None환경변수프록시·호환 서버 주소
chunk_sizeint1000embed_documents에서 한 요청에 묶는 텍스트 수
embedding_ctx_lengthint8191텍스트당 최대 토큰. 넘으면 잘라서 임베딩 후 가중 평균
check_embedding_ctx_lengthboolTrue위 길이 검사/분할 수행 여부. OpenAI 호환 서버에서 토크나이저가 다르면 False
tiktoken_enabledboolTrue토큰 계산에 tiktoken 사용. False면 HuggingFace 토크나이저 사용
max_retriesint2실패 시 재시도 횟수
timeoutfloat | tuple | NoneNone요청 타임아웃(초)
skip_emptyboolFalse빈 문자열을 건너뛸지 여부(False면 오류)
show_progress_barboolFalse대량 임베딩 시 진행 표시(tqdm 필요)
model_kwargsdict{}요청에 추가로 보낼 파라미터

메서드와 반환값

메서드반환설명
embed_documents(texts, chunk_size=None)list[list[float]]여러 문서를 배치로 임베딩
embed_query(text)list[float]질의 1개 임베딩
aembed_documents / aembed_query같음비동기 버전

예제

python
from langchain_openai import OpenAIEmbeddings

emb = OpenAIEmbeddings(model="text-embedding-3-small")

docs = ["LangGraph는 상태 기반 그래프 런타임이다.", "Qdrant는 벡터 데이터베이스다."]
doc_vecs = emb.embed_documents(docs)
q_vec = emb.embed_query("그래프 런타임")
print(len(doc_vecs), "개 문서,", len(q_vec), "차원")
python
from langchain_core.vectorstores import InMemoryVectorStore
from langchain_openai import OpenAIEmbeddings

# 벡터 스토어에 바로 연결
store = InMemoryVectorStore(OpenAIEmbeddings(model="text-embedding-3-small"))
store.add_texts(["사과는 빨갛다", "바나나는 노랗다"])
print(store.similarity_search("노란 과일", k=1)[0].page_content)
python
from langchain_openai import OpenAIEmbeddings

# 차원 축소: 저장 비용 절감 (실제 API에서만 차원이 바뀜)
small = OpenAIEmbeddings(model="text-embedding-3-large", dimensions=256)

주의사항

주의

색인할 때와 검색할 때 **같은 모델·같은 dimensions**를 써야 합니다. 모델을 바꾸면 기존 벡터와 비교가 무의미해지므로 컬렉션 전체를 다시 임베딩해야 합니다. 벡터 DB 컬렉션의 차원 설정도 맞춰야 합니다.

팁

OpenAI 임베딩은 L2 정규화된 벡터를 반환하므로 코사인 유사도와 내적(dot product)이 같은 순위를 줍니다. 벡터 DB에서는 어느 쪽 거리 함수를 써도 됩니다. 자세한 내용은 벡터 DB 개념 참고.

참고

AgentLab Mock 모드에서는 OpenAIEmbeddings가 결정적 해시 기반 가짜 임베딩으로 바뀝니다. 의미적 순위는 기대하지 마세요.

관련 문서