이 페이지는 Astra DB를 Vector Store로 사용하기 위한 빠른 시작 가이드를 제공합니다.
DataStax Astra DB는 Apache Cassandra® 기반으로 구축된 서버리스 AI 지원 데이터베이스로, 사용하기 쉬운 JSON API를 통해 편리하게 사용할 수 있습니다.

​
Setup

​
Dependencies

이 통합을 사용하려면 langchain-astradb 파트너 패키지가 필요합니다: 
!pip install \
    "langchain>=0.3.23,<0.4" \
    "langchain-core>=0.3.52,<0.4" \
    "langchain-astradb>=0.6,<0.7"

​
Credentials

AstraDB vector store를 사용하려면 먼저 AstraDB 웹사이트로 이동하여 계정을 생성한 다음 새 데이터베이스를 만들어야 합니다 - 초기화에 몇 분이 걸릴 수 있습니다. 데이터베이스가 초기화되면 곧 필요한 연결 정보를 가져옵니다. 필요한 정보는 다음과 같습니다:
  • API Endpoint, 예: "https://01234567-89ab-cdef-0123-456789abcdef-us-east1.apps.astra.datastax.com/"
  • 그리고 Database Token, 예: "AstraCS:aBcD123......"
선택적으로 keyspace(LangChain 컴포넌트에서는 “namespace”라고 함)를 제공할 수 있으며, 데이터베이스 대시보드의 Data Explorer 탭에서 관리할 수 있습니다. 원하는 경우 아래 프롬프트에서 비워두고 기본 keyspace를 사용할 수 있습니다. 
import getpass

ASTRA_DB_API_ENDPOINT = input("ASTRA_DB_API_ENDPOINT = ").strip()
ASTRA_DB_APPLICATION_TOKEN = getpass.getpass("ASTRA_DB_APPLICATION_TOKEN = ").strip()

desired_keyspace = input("(optional) ASTRA_DB_KEYSPACE = ").strip()
if desired_keyspace:
    ASTRA_DB_KEYSPACE = desired_keyspace
else:
    ASTRA_DB_KEYSPACE = None

ASTRA_DB_API_ENDPOINT =  https://01234567-89ab-cdef-0123-456789abcdef-us-east1.apps.astra.datastax.com
ASTRA_DB_APPLICATION_TOKEN =  ········
(optional) ASTRA_DB_KEYSPACE =
모델 호출에 대한 최고 수준의 자동 추적을 원하시면 아래 주석을 해제하여 LangSmith API 키를 설정할 수 있습니다: 
os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")
os.environ["LANGSMITH_TRACING"] = "true"

​
Initialization

Astra DB vector store를 생성하는 다양한 방법이 있습니다:

​
Method 1: Explicit embeddings

langchain_core.embeddings.Embeddings 클래스를 별도로 인스턴스화하여 AstraDBVectorStore 생성자에 전달할 수 있습니다. 이는 대부분의 다른 LangChain vector store와 동일한 방식입니다.

​
Method 2: Server-side embeddings (‘vectorize’)

또는 Astra DB의 서버 측 임베딩 계산 기능(‘vectorize’)을 사용하여 store의 서버 인프라를 생성할 때 임베딩 모델을 지정하기만 하면 됩니다. 그러면 이후의 읽기 및 쓰기 작업에서 임베딩 계산이 데이터베이스 내에서 완전히 처리됩니다. (이 방법을 진행하려면 문서에 설명된 대로 데이터베이스에 대해 원하는 임베딩 통합을 활성화해야 합니다.)

​
Method 3: Auto-detect from a pre-existing collection

Astra DB에 이미 collection이 있을 수 있으며, 다른 수단(예: Astra UI 또는 타사 애플리케이션)을 통해 데이터가 미리 채워져 있고 LangChain 내에서 쿼리를 시작하고 싶을 수 있습니다. 이 경우 올바른 접근 방식은 vector store 생성자에서 autodetect_collection 모드를 활성화하고 클래스가 세부 정보를 파악하도록 하는 것입니다. (물론 collection에 ‘vectorize’가 없는 경우 여전히 Embeddings 객체를 제공해야 합니다.)

​
“hybrid search”에 대한 참고사항

Astra DB vector store는 vector 검색에서 메타데이터 검색을 지원합니다. 또한 버전 0.6에서는 findAndRerank 데이터베이스 primitive를 통한 _hybrid search_에 대한 완전한 지원이 도입되었습니다: 문서는 vector 유사도 및 키워드 기반(“lexical”) 검색 모두에서 검색되고, reranker 모델을 통해 병합됩니다. 서버 측에서 완전히 처리되는 이 검색 전략은 결과의 정확도를 높여 RAG 애플리케이션의 품질을 향상시킬 수 있습니다. 사용 가능한 경우 hybrid search는 vector store에서 자동으로 사용됩니다(원하는 경우 수동으로 제어할 수 있습니다).

​
추가 정보

AstraDBVectorStore는 다양한 방식으로 구성할 수 있습니다. 비동기 초기화, 비 Astra-DB 데이터베이스, 사용자 정의 인덱싱 허용/거부 목록, 수동 hybrid-search 제어 등을 다루는 전체 가이드는 API Reference를 참조하세요.

​
Explicit embedding initialization (method 1)

명시적 embedding 클래스를 사용하여 vector store를 인스턴스화합니다: 
# | output: false
# | echo: false
from langchain_openai import OpenAIEmbeddings

embeddings = OpenAIEmbeddings(model="text-embedding-3-large")

from langchain_astradb import AstraDBVectorStore

vector_store_explicit_embeddings = AstraDBVectorStore(
    collection_name="astra_vector_langchain",
    embedding=embeddings,
    api_endpoint=ASTRA_DB_API_ENDPOINT,
    token=ASTRA_DB_APPLICATION_TOKEN,
    namespace=ASTRA_DB_KEYSPACE,
)

​
Server-side embedding initialization (“vectorize”, method 2)

이 예제 코드에서는 다음을 가정합니다:
  • Astra DB 조직에서 OpenAI 통합을 활성화했습니다.
  • 통합에 "OPENAI_API_KEY"라는 이름의 API Key를 추가하고 사용 중인 데이터베이스로 범위를 지정했습니다.
provider/model을 전환하는 방법을 포함한 자세한 내용은 문서를 참조하세요. 
from astrapy.info import VectorServiceOptions

openai_vectorize_options = VectorServiceOptions(
    provider="openai",
    model_name="text-embedding-3-small",
    authentication={
        "providerKey": "OPENAI_API_KEY",
    },
)

vector_store_integrated_embeddings = AstraDBVectorStore(
    collection_name="astra_vectorize_langchain",
    api_endpoint=ASTRA_DB_API_ENDPOINT,
    token=ASTRA_DB_APPLICATION_TOKEN,
    namespace=ASTRA_DB_KEYSPACE,
    collection_vector_service_options=openai_vectorize_options,
)

​
Auto-detect initialization (method 3)

collection이 데이터베이스에 이미 존재하고 AstraDBVectorStore가 이를 사용해야 하는 경우(읽기 및 쓰기) 이 패턴을 사용할 수 있습니다. LangChain 컴포넌트는 collection을 검사하고 세부 정보를 파악합니다. 이는 collection이 생성되었고 — 가장 중요하게는 — LangChain이 아닌 다른 도구로 채워진 경우, 예를 들어 Astra DB 웹 인터페이스를 통해 데이터가 수집된 경우 권장되는 접근 방식입니다. Auto-detect 모드는 collection 설정(유사도 메트릭 등)과 공존할 수 없습니다. 반면에 서버 측 임베딩이 사용되지 않는 경우 여전히 생성자에 Embeddings 객체를 전달해야 합니다. 다음 예제 코드에서는 위의 method 2(“vectorize”)에서 생성된 동일한 collection을 “auto-detect”합니다. 따라서 Embeddings 객체를 제공할 필요가 없습니다. 
vector_store_autodetected = AstraDBVectorStore(
    collection_name="astra_vectorize_langchain",
    api_endpoint=ASTRA_DB_API_ENDPOINT,
    token=ASTRA_DB_APPLICATION_TOKEN,
    namespace=ASTRA_DB_KEYSPACE,
    autodetect_collection=True,
)

​
Manage vector store

vector store를 생성한 후에는 다양한 항목을 추가하고 삭제하여 상호 작용할 수 있습니다. vector store와의 모든 상호 작용은 초기화 방법에 관계없이 진행됩니다: 원하는 경우 다음 셀을 조정하여 생성하고 테스트하려는 vector store를 선택하세요. 
# If desired, uncomment a different line here:

# vector_store = vector_store_explicit_embeddings
vector_store = vector_store_integrated_embeddings
# vector_store = vector_store_autodetected

​
Add items to vector store

add_documents 메서드를 사용하여 vector store에 문서를 추가합니다. “id” 필드는 add_documents의 일치하는 ids=[...] 매개변수에 별도로 제공하거나, 완전히 생략하여 store가 ID를 생성하도록 할 수 있습니다. 
from langchain_core.documents import Document

documents_to_insert = [
    Document(
        page_content="ZYX, just another tool in the world, is actually my agent-based superhero",
        metadata={"source": "tweet"},
        id="entry_00",
    ),
    Document(
        page_content="I had chocolate chip pancakes and scrambled eggs "
        "for breakfast this morning.",
        metadata={"source": "tweet"},
        id="entry_01",
    ),
    Document(
        page_content="The weather forecast for tomorrow is cloudy and "
        "overcast, with a high of 62 degrees.",
        metadata={"source": "news"},
        id="entry_02",
    ),
    Document(
        page_content="Building an exciting new project with LangChain "
        "- come check it out!",
        metadata={"source": "tweet"},
        id="entry_03",
    ),
    Document(
        page_content="Robbers broke into the city bank and stole $1 million in cash.",
        metadata={"source": "news"},
        id="entry_04",
    ),
    Document(
        page_content="Thanks to her sophisticated language skills, the agent "
        "managed to extract strategic information all right.",
        metadata={"source": "tweet"},
        id="entry_05",
    ),
    Document(
        page_content="Is the new iPhone worth the price? Read this review to find out.",
        metadata={"source": "website"},
        id="entry_06",
    ),
    Document(
        page_content="The top 10 soccer players in the world right now.",
        metadata={"source": "website"},
        id="entry_07",
    ),
    Document(
        page_content="LangGraph is the best framework for building stateful, "
        "agentic applications!",
        metadata={"source": "tweet"},
        id="entry_08",
    ),
    Document(
        page_content="The stock market is down 500 points today due to "
        "fears of a recession.",
        metadata={"source": "news"},
        id="entry_09",
    ),
    Document(
        page_content="I have a bad feeling I am going to get deleted :(",
        metadata={"source": "tweet"},
        id="entry_10",
    ),
]


vector_store.add_documents(documents=documents_to_insert)

['entry_00',
 'entry_01',
 'entry_02',
 'entry_03',
 'entry_04',
 'entry_05',
 'entry_06',
 'entry_07',
 'entry_08',
 'entry_09',
 'entry_10']

​
Delete items from vector store

delete 함수를 사용하여 ID로 항목을 삭제합니다. 
vector_store.delete(ids=["entry_10", "entry_02"])

True

​
Query the vector store

vector store가 생성되고 채워지면 쿼리할 수 있습니다(예: chain 또는 agent의 일부로).

​
Query directly

제공된 텍스트와 유사한 문서를 검색하며, 원하는 경우 추가 메타데이터 필터를 사용할 수 있습니다: 
results = vector_store.similarity_search(
    "LangChain provides abstractions to make working with LLMs easy",
    k=3,
    filter={"source": "tweet"},
)
for res in results:
    print(f'* "{res.page_content}", metadata={res.metadata}')

* "Building an exciting new project with LangChain - come check it out!", metadata={'source': 'tweet'}
* "LangGraph is the best framework for building stateful, agentic applications!", metadata={'source': 'tweet'}
* "Thanks to her sophisticated language skills, the agent managed to extract strategic information all right.", metadata={'source': 'tweet'}

​
Similarity search with score

유사도 점수도 함께 반환할 수 있습니다: 
results = vector_store.similarity_search_with_score(
    "LangChain provides abstractions to make working with LLMs easy",
    k=3,
    filter={"source": "tweet"},
)
for res, score in results:
    print(f'* [SIM={score:.2f}] "{res.page_content}", metadata={res.metadata}')

* [SIM=0.71] "Building an exciting new project with LangChain - come check it out!", metadata={'source': 'tweet'}
* [SIM=0.70] "LangGraph is the best framework for building stateful, agentic applications!", metadata={'source': 'tweet'}
* [SIM=0.61] "Thanks to her sophisticated language skills, the agent managed to extract strategic information all right.", metadata={'source': 'tweet'}
참고: 이 셀은 collection이 find-and-rerank 명령을 지원하고 vector store가 이 사실을 인식하는 경우에만 실행할 수 있습니다.
vector store가 hybrid 지원 collection을 사용하고 이 사실을 감지한 경우, 기본적으로 검색을 실행할 때 해당 기능을 사용합니다. 이 경우 find-and-rerank 프로세스의 vector 유사도 및 lexical 기반 검색 단계 모두에 동일한 쿼리 텍스트가 사용됩니다. 후자에 대해 명시적으로 다른 쿼리를 제공하지 않는 한: 
results = vector_store_autodetected.similarity_search(
    "LangChain provides abstractions to make working with LLMs easy",
    k=3,
    filter={"source": "tweet"},
    lexical_query="agent",
)
for res in results:
    print(f'* "{res.page_content}", metadata={res.metadata}')

* "Building an exciting new project with LangChain - come check it out!", metadata={'source': 'tweet'}
* "LangGraph is the best framework for building stateful, agentic applications!", metadata={'source': 'tweet'}
* "ZYX, just another tool in the world, is actually my agent-based superhero", metadata={'source': 'tweet'}
위의 예제는 collection을 검사하고 hybrid를 사용할 수 있는지 확실히 파악한 “autodetected” vector store를 하드코딩합니다. 또 다른 옵션은 생성자에 hybrid-search 매개변수를 명시적으로 제공하는 것입니다(자세한 내용/예제는 API Reference 참조).

​
Other search methods

이 노트북에서 다루지 않는 MMR 검색 및 vector별 검색과 같은 다양한 다른 검색 방법이 있습니다. AstraDBVectorStore에서 사용 가능한 검색 모드의 전체 목록은 API reference를 확인하세요.

​
Query by turning into retriever

vector store를 retriever로 만들어 chain에서 더 쉽게 사용할 수도 있습니다. vector store를 retriever로 변환하고 간단한 쿼리 + 메타데이터 필터로 호출합니다: 
retriever = vector_store.as_retriever(
    search_type="similarity_score_threshold",
    search_kwargs={"k": 1, "score_threshold": 0.5},
)
retriever.invoke("Stealing from the bank is a crime", filter={"source": "news"})

[Document(id='entry_04', metadata={'source': 'news'}, page_content='Robbers broke into the city bank and stole $1 million in cash.')]

​
Usage for retrieval-augmented generation

retrieval-augmented generation(RAG)에 이 vector store를 사용하는 방법에 대한 가이드는 다음 섹션을 참조하세요: 자세한 내용은 Astra DB를 사용하는 완전한 RAG 템플릿을 여기에서 확인하세요.

​
Cleanup vector store

Astra DB 인스턴스에서 collection을 완전히 삭제하려면 다음을 실행하세요. (저장한 데이터가 손실됩니다.) 
vector_store.delete_collection()

​
API reference

모든 AstraDBVectorStore 기능 및 구성에 대한 자세한 문서는 API reference를 참조하세요.
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.
⌘I