OpenAI 임베딩 통합

OpenAI 임베딩 통합 (OpenAIEmbeddings)

LangChain에서 OpenAI 임베딩 모델을 처음 쓸 때 가장 먼저 보는 문서예요. OpenAIEmbeddings 클래스 하나로 임베딩 생성은 물론, RAG 흐름의 인덱싱과 검색까지 자연스럽게 이어지거든요. 자세한 기능과 설정은 API 레퍼런스를 참고하면 돼요.

출처: 공식문서

개요

OpenAI 임베딩 모델에 접근하려면 OpenAI 계정을 만들고 API 키를 발급받은 뒤 langchain-openai 통합 패키지를 설치해야 해요.

설정

자격 증명 (Credentials)

platform.openai.com에서 가입하고 API 키를 생성해요. 그다음 OPENAI_API_KEY 환경 변수를 설정하면 돼요.

import getpass
import os

if not os.getenv("OPENAI_API_KEY"):
    os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter your OpenAI API key: ")

프록시나 서비스 에뮬레이터를 통해 요청을 보낸다면, base_url을 직접 넘기는 대신 환경 변수로 베이스 URL을 설정할 수 있어요. 해석 순서(먼저 매칭되는 것 우선)는 다음과 같아요.

1. 명시적인 base_url(또는 openai_api_base) 인자
2. OPENAI_API_BASE — LangChain이 초기화 시 읽음
3. OPENAI_BASE_URL — 내부 openai SDK 클라이언트가 읽음

모델 호출을 자동으로 트레이싱하고 싶다면 LangSmith API 키를 설정해요.

os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")

설치

LangChain OpenAI 통합은 langchain-openai 패키지에 들어 있어요.

pip install -qU langchain-openai

인스턴스화

이제 모델 객체를 만들고 임베딩을 생성해요.

from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(
    model="text-embedding-3-large",
    # With the `text-embedding-3` class
    # of models, you can specify the size
    # of the embeddings you want returned.
    # dimensions=1024
)

Azure OpenAI v1 API 지원

langchain-openai>=1.0.1부터 OpenAIEmbeddings는 새로운 v1 API를 통해 Azure OpenAI 엔드포인트에서 바로 사용할 수 있어요. Microsoft Entra ID 인증도 지원해요. 자세한 내용은 아래 Azure OpenAI와 함께 사용하기 섹션을 참고하세요.

인덱싱과 리트리벌 (Indexing and retrieval)

임베딩 모델은 RAG(retrieval-augmented generation) 흐름에서 데이터 인덱싱과 이후 검색 양쪽에 자주 쓰여요. 더 자세한 지침은 RAG 튜토리얼을 참고하세요.

아래는 위에서 만든 embeddings 객체로 데이터를 인덱싱하고 검색하는 예시예요. 이 예시에서는 샘플 문서를 InMemoryVectorStore에 인덱싱하고 검색해요.

# Create a vector store with a sample text
from langchain_core.vectorstores import InMemoryVectorStore

text = "LangChain is the framework for building context-aware reasoning applications"

vectorstore = InMemoryVectorStore.from_texts(
    [text],
    embedding=embeddings,
)

# Use the vectorstore as a retriever
retriever = vectorstore.as_retriever()

# Retrieve the most similar text
retrieved_documents = retriever.invoke("What is LangChain?")

# show the retrieved document's content
retrieved_documents[0].page_content

'LangChain is the framework for building context-aware reasoning applications'

직접 사용하기

기본적으로 vectorstore와 리트리버는 내부적으로 embeddings.embed_documents(...)와 embeddings.embed_query(...)를 호출해요. 필요한 경우 이 메서드들을 직접 호출해서 자신만의 용도로 임베딩을 만들 수도 있어요.

단일 텍스트 임베딩

embed_query로 텍스트나 문서 하나를 임베딩할 수 있어요.

single_vector = embeddings.embed_query(text)
print(str(single_vector)[:100])  # Show the first 100 characters of the vector

여러 텍스트 임베딩

embed_documents로 여러 텍스트를 한 번에 임베딩할 수 있어요.

text2 = (
    "LangGraph is a library for building stateful, multi-actor applications with LLMs"
)
two_vectors = embeddings.embed_documents([text, text2])
for vector in two_vectors:
    print(str(vector)[:100])  # Show the first 100 characters of the vector

Azure OpenAI와 함께 사용하기

Azure OpenAI v1 API를 API 키로 사용하기

base_url에 /openai/v1/을 붙인 Azure 엔드포인트를 설정하면 OpenAIEmbeddings를 바로 쓸 수 있어요.

from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(
    model="text-embedding-3-large",  # Your Azure deployment name
    base_url="https://{your-resource-name}.openai.azure.com/openai/v1/",
    api_key="your-azure-api-key"
)

# Use as normal
vector = embeddings.embed_query("Hello world")

Azure OpenAI를 Microsoft Entra ID로 사용하기

v1 API는 자동 토큰 갱신과 함께 Microsoft Entra ID 인증을 네이티브로 지원해요. 토큰 프로바이더 콜러블(callable)을 api_key 파라미터로 전달하면 돼요.

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from langchain_openai import OpenAIEmbeddings

# Create a token provider that handles automatic refresh
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default"
)

embeddings = OpenAIEmbeddings(
    model="text-embedding-3-large",  # Your Azure deployment name
    base_url="https://{your-resource-name}.openai.azure.com/openai/v1/",
    api_key=token_provider  # Callable that handles token refresh
)

# Use as normal
vectors = embeddings.embed_documents(["Hello", "World"])

설치 요구사항

Microsoft Entra ID 인증을 사용하려면 Azure Identity 라이브러리를 설치해야 해요.

pip install azure-identity

비동기 함수에서도 토큰 프로바이더 콜러블을 api_key로 전달할 수 있어요. 이때 DefaultAzureCredential은 azure.identity.aio에서 import 해야 해요.

from azure.identity.aio import DefaultAzureCredential
from langchain_openai import OpenAIEmbeddings

credential = DefaultAzureCredential()

embeddings_async = OpenAIEmbeddings(
    model="text-embedding-3-large",
    api_key=credential
)

# Use async methods when using async callable
vectors = await embeddings_async.aembed_documents(["Hello", "World"])

주의: API 키로 비동기 콜러블을 사용할 때는 반드시 비동기 메서드(aembed_query, aembed_documents)를 써야 해요. 동기 메서드는 오류를 뱉어요.

API 레퍼런스

OpenAIEmbeddings의 기능과 설정 옵션에 대한 자세한 문서는 API 레퍼런스를 참고하세요.

더 알아보기 (Learn more)

• OpenAIEmbeddings API 레퍼런스
• RAG 튜토리얼
• AzureOpenAIEmbeddings (Azure 전용 기존 구현)