Oracle AI 向量搜索集成

使用 LangChain Python 集成 Oracle AI vector search - 向量存储。

Oracle AI Database 支持通过 语义（意义）而非关键词查询数据的 AI 工作负载。它将 非结构化内容的语义搜索 与 业务数据的关联过滤 结合在单一系统中——因此您可以在不引入独立的向量数据库的情况下构建检索工作流（如 RAG），并避免将数据分散到多个平台。

本指南演示如何使用 OracleVS（用于 Oracle AI Vector Search 的 LangChain 向量存储集成）来实现：

• 将文档和嵌入导入 Oracle
• 运行相似性搜索
• 创建 HNSW 和 IVF 索引
• 应用元数据过滤器以实现高级检索
• 在 Oracle Database 26ai 中启用混合搜索（关键词 + 语义）
• 使用 Oracle Text 运行全文搜索

前置条件

安装 langchain-oracledb。python-oracledb 驱动程序将作为依赖项自动安装。

pip

pip install -qU langchain-oracledb

连接到 Oracle Database

以下示例代码将展示如何连接到 Oracle Database。默认情况下，python-oracledb 以“Thin”模式运行，直接连接到 Oracle Database。此模式无需 Oracle 客户端库。然而，当 python-oracledb 使用它们时，可以提供一些附加功能。当使用 Oracle 客户端库时，python-oracledb 被称为“Thick”模式。两种模式都具有支持 Python 数据库 API v2.0 规范的全面功能。请参阅以下 指南，了解每种模式下支持的功能。如果您无法使用 Thin 模式，可能需要切换到 Thick 模式。

import oracledb

# Please update with your username, password, hostname, port and service_name
username = "<username>"
password = "<password>"
dsn = "<hostname>:<port>/<service_name>"

connection = oracledb.connect(user=username, password=password, dsn=dsn)
print("Connection successful!")

导入所需的依赖项

langchain-community包已不再维护。从langchain_community导入的示例可能过时或无法使用。请谨慎使用。

from langchain_oracledb.vectorstores import oraclevs
from langchain_oracledb.vectorstores.oraclevs import OracleVS
from langchain_community.vectorstores.utils import DistanceStrategy
from langchain_core.documents import Document
from langchain_huggingface import HuggingFaceEmbeddings

加载文档

# Define a list of documents (The examples below are 5 random documents from Oracle Concepts Manual )

documents_json_list = [
    {
        "id": "cncpt_15.5.3.2.2_P4",
        "text": "If the answer to any preceding questions is yes, then the database stops the search and allocates space from the specified tablespace; otherwise, space is allocated from the database default shared temporary tablespace.",
        "link": "https://docs.oracle.com/en/database/oracle/oracle-database/23/cncpt/logical-storage-structures.html#GUID-5387D7B2-C0CA-4C1E-811B-C7EB9B636442",
    },
    {
        "id": "cncpt_15.5.5_P1",
        "text": "A tablespace can be online (accessible) or offline (not accessible) whenever the database is open.\nA tablespace is usually online so that its data is available to users. The SYSTEM tablespace and temporary tablespaces cannot be taken offline.",
        "link": "https://docs.oracle.com/en/database/oracle/oracle-database/23/cncpt/logical-storage-structures.html#GUID-D02B2220-E6F5-40D9-AFB5-BC69BCEF6CD4",
    },
    {
        "id": "cncpt_22.3.4.3.1_P2",
        "text": "The database stores LOBs differently from other data types. Creating a LOB column implicitly creates a LOB segment and a LOB index. The tablespace containing the LOB segment and LOB index, which are always stored together, may be different from the tablespace containing the table.\nSometimes the database can store small amounts of LOB data in the table itself rather than in a separate LOB segment.",
        "link": "https://docs.oracle.com/en/database/oracle/oracle-database/23/cncpt/concepts-for-database-developers.html#GUID-3C50EAB8-FC39-4BB3-B680-4EACCE49E866",
    },
    {
        "id": "cncpt_22.3.4.3.1_P3",
        "text": "The LOB segment stores data in pieces called chunks. A chunk is a logically contiguous set of data blocks and is the smallest unit of allocation for a LOB. A row in the table stores a pointer called a LOB locator, which points to the LOB index. When the table is queried, the database uses the LOB index to quickly locate the LOB chunks.",
        "link": "https://docs.oracle.com/en/database/oracle/oracle-database/23/cncpt/concepts-for-database-developers.html#GUID-3C50EAB8-FC39-4BB3-B680-4EACCE49E866",
    },
]

# Create LangChain Documents

documents_langchain = []

for doc in documents_json_list:
    metadata = {"id": doc["id"], "link": doc["link"]}
    doc_langchain = Document(page_content=doc["text"], metadata=metadata)
    documents_langchain.append(doc_langchain)

使用不同的距离度量创建向量存储

首先，我们将创建三个使用不同距离函数的向量存储。由于我们尚未在这些向量存储中创建索引，它们目前只会创建表。稍后，我们将使用这些向量存储来创建 HNSW 索引。要了解 Oracle AI Vector Search 支持的索引类型更多信息，请参阅以下 指南。

您可以手动连接到 Oracle Database，并将看到三个表： Documents_DOT、Documents_COSINE 和 Documents_EUCLIDEAN。

然后，我们将创建三个额外的表 Documents_DOT_IVF、Documents_COSINE_IVF 和 Documents_EUCLIDEAN_IVF，这些表将用于在表上创建 IVF 索引，而不是 HNSW 索引。

# Ingest documents into Oracle Vector Store using different distance strategies

# When using our API calls, start by initializing your vector store with a subset of your documents
# through from_documents(), then incrementally add more documents using add_texts().
# This approach prevents system overload and ensures efficient document processing.

model = HuggingFaceEmbeddings(model_name="sentence-transformers/all-mpnet-base-v2")

vector_store_dot = OracleVS.from_documents(
    documents_langchain,
    model,
    client=connection,
    table_name="Documents_DOT",
    distance_strategy=DistanceStrategy.DOT_PRODUCT,
)
vector_store_max = OracleVS.from_documents(
    documents_langchain,
    model,
    client=connection,
    table_name="Documents_COSINE",
    distance_strategy=DistanceStrategy.COSINE,
)
vector_store_euclidean = OracleVS.from_documents(
    documents_langchain,
    model,
    client=connection,
    table_name="Documents_EUCLIDEAN",
    distance_strategy=DistanceStrategy.EUCLIDEAN_DISTANCE,
)

# Ingest documents into Oracle Vector Store using different distance strategies
vector_store_dot_ivf = OracleVS.from_documents(
    documents_langchain,
    model,
    client=connection,
    table_name="Documents_DOT_IVF",
    distance_strategy=DistanceStrategy.DOT_PRODUCT,
)
vector_store_max_ivf = OracleVS.from_documents(
    documents_langchain,
    model,
    client=connection,
    table_name="Documents_COSINE_IVF",
    distance_strategy=DistanceStrategy.COSINE,
)
vector_store_euclidean_ivf = OracleVS.from_documents(
    documents_langchain,
    model,
    client=connection,
    table_name="Documents_EUCLIDEAN_IVF",
    distance_strategy=DistanceStrategy.EUCLIDEAN_DISTANCE,
)

文本的添加和删除操作，以及基本的相似性搜索

def manage_texts(vector_stores):
    """
    Adds texts to each vector store, demonstrates error handling for duplicate additions,
    and performs deletion of texts. Showcases similarity searches and index creation for each vector store.

    Args:
    - vector_stores (list): A list of OracleVS instances.
    """
    texts = ["Rohan", "Shailendra"]
    metadata = [
        {"id": "100", "link": "Document Example Test 1"},
        {"id": "101", "link": "Document Example Test 2"},
    ]

    for i, vs in enumerate(vector_stores, start=1):
        # Adding texts
        try:
            vs.add_texts(texts, metadata)
            print(f"\n\n\nAdd texts complete for vector store {i}\n\n\n")
        except Exception as ex:
            print(f"\n\n\nExpected error on duplicate add for vector store {i}\n\n\n")

        # Deleting texts using the value of 'id'
        vs.delete([metadata[0]["id"]])
        print(f"\n\n\nDelete texts complete for vector store {i}\n\n\n")

        # Similarity search
        results = vs.similarity_search("How are LOBS stored in Oracle Database", 2)
        print(f"\n\n\nSimilarity search results for vector store {i}: {results}\n\n\n")


vector_store_list = [
    vector_store_dot,
    vector_store_max,
    vector_store_euclidean,
    vector_store_dot_ivf,
    vector_store_max_ivf,
    vector_store_euclidean_ivf,
]
manage_texts(vector_store_list)

具有特定参数的索引创建

def create_search_indices(connection):
    """
    Creates search indices for the vector stores, each with specific parameters tailored to their distance strategy.
    """
    # Index for DOT_PRODUCT strategy
    # Notice we are creating a HNSW index with default parameters
    # This will default to creating a HNSW index with 8 Parallel Workers and use the Default Accuracy used by Oracle AI Vector Search
    oraclevs.create_index(
        connection,
        vector_store_dot,
        params={"idx_name": "hnsw_idx1", "idx_type": "HNSW"},
    )

    # Index for COSINE strategy with specific parameters
    # Notice we are creating a HNSW index with parallel 16 and Target Accuracy Specification as 97 percent
    oraclevs.create_index(
        connection,
        vector_store_max,
        params={
            "idx_name": "hnsw_idx2",
            "idx_type": "HNSW",
            "accuracy": 97,
            "parallel": 16,
        },
    )

    # Index for EUCLIDEAN_DISTANCE strategy with specific parameters
    # Notice we are creating a HNSW index by specifying Power User Parameters which are neighbors = 64 and efConstruction = 100
    oraclevs.create_index(
        connection,
        vector_store_euclidean,
        params={
            "idx_name": "hnsw_idx3",
            "idx_type": "HNSW",
            "neighbors": 64,
            "efConstruction": 100,
        },
    )

    # Index for DOT_PRODUCT strategy with specific parameters
    # Notice we are creating an IVF index with default parameters
    # This will default to creating an IVF index with 8 Parallel Workers and use the Default Accuracy used by Oracle AI Vector Search
    oraclevs.create_index(
        connection,
        vector_store_dot_ivf,
        params={
            "idx_name": "ivf_idx1",
            "idx_type": "IVF",
        },
    )

    # Index for COSINE strategy with specific parameters
    # Notice we are creating an IVF index with parallel 32 and Target Accuracy Specification as 90 percent
    oraclevs.create_index(
        connection,
        vector_store_max_ivf,
        params={
            "idx_name": "ivf_idx2",
            "idx_type": "IVF",
            "accuracy": 90,
            "parallel": 32,
        },
    )

    # Index for EUCLIDEAN_DISTANCE strategy with specific parameters
    # Notice we are creating an IVF index by specifying Power User Parameters which is neighbor_part = 64
    oraclevs.create_index(
        connection,
        vector_store_euclidean_ivf,
        params={"idx_name": "ivf_idx3", "idx_type": "IVF", "neighbor_part": 64},
    )

    print("Index creation complete.")


create_search_indices(connection)

高级搜索

Oracle Database 23ai 支持预过滤、内过滤和后过滤，以增强 AI Vector Search 功能。这些过滤机制允许用户在执行向量相似性搜索之前、期间和之后应用约束，从而提高搜索性能和准确性。

Oracle 23ai 中过滤的关键点：

1. 预过滤 在执行向量相似性搜索之前应用传统的 SQL 过滤器，以减少数据集。 通过限制 AI 算法处理的数据量，有助于提高效率。
2. 内过滤 利用 AI Vector Search 直接在向量嵌入上执行相似性搜索，使用优化的索引和算法。 基于向量相似性高效过滤结果，无需扫描完整数据集。
3. 后过滤 在向量相似性搜索后应用额外的 SQL 过滤器，以细化结果。 允许根据业务逻辑或额外的元数据条件进行进一步细化。

为什么这很重要？

• 性能优化：预过滤显著减少查询执行时间，使在大型数据集上的搜索更高效。
• 准确性增强：内过滤确保向量搜索具有语义意义，提高搜索结果的质量。

过滤详情

OracleVS 支持一组可以应用于 metadata 字段的过滤器，使用 filter 参数。这些过滤器允许您根据各种标准选择和细化数据。

可用的过滤运算符：

操作符	描述
\$exists	字段存在。
\$eq	字段值等于操作数值（=）。
\$ne	字段存在且值不等于操作数值（!=）。
\$gt	字段值大于操作数值（>）。
\$lt	字段值小于操作数值（<）。
\$gte	字段值大于或等于操作数值（>=）。
\$lte	字段值小于或等于操作数值（<=）。
\$between	字段值在操作数数组中的两个值之间（或等于）。
\$startsWith	字段值以操作数值开头。
\$hasSubstring	字段值包含操作数作为子字符串。
\$instr	字段值包含操作数作为子字符串。
\$regex	字段值匹配给定的正则表达式模式。
\$like	字段值匹配操作数模式（使用类似 SQL 的语法）。
\$in	字段值等于操作数数组中的至少一个值。
\$nin	字段存在，但其值不等于操作数数组中的任何值，或字段不存在。
\$all	字段值是一个数组，包含操作数数组中的所有项，或是一个与单个操作数匹配的标量。

• 您可以使用逻辑运算符组合这些过滤器：

逻辑运算符	描述
\$and	逻辑 AND
\$or	逻辑 OR
\$nor	逻辑 NOR

示例过滤器：

{
  "age": 65,
  "name": {"$regex": "*rk"},
  "$or": [
    {
      "$and": [
        {"name": "Jason"},
        {"drinks": {"$in": ["tea", "soda"]}}
      ]
    },
    {
      "$nor": [
        {"age": {"$lt": 65}},
        {"name": "Jason"}
      ]
    }
  ]
}

附加使用提示：

• 当对象中的所有过滤器都必须满足时，可以省略 $and。这两个是等效的：

{ "$and": [
    { "name": { "$startsWith": "Fred" } },
    { "salary": { "$gt": 10000, "$lte": 20000 } }
]}

{
  "name": { "$startsWith": "Fred" },
  "salary": { "$gt": 10000, "$lte": 20000 }
}

• $not 子句可以否定比较运算符：

{ "address.zip": { "$not": { "$eq": "90001" } } }

• 使用 field: scalar 等同于 field: { "$eq": scalar }：

{ "animal": "cat" }

有关更多过滤器示例，请参阅 测试规范。

# Conduct advanced searches after creating the indices
def conduct_advanced_searches(vector_stores):
    query = "How are LOBS stored in Oracle Database"
    # Constructing a filter for direct comparison against document metadata
    # This filter aims to include documents whose metadata 'id' is exactly '2'
    db_filter = {
        "$and": [
            {"id": "101"},  # FilterCondition
            {
                "$or": [  # FilterGroup
                    {"status": "approved"},
                    {"link": "Document Example Test 2"},
                    {
                        "$and": [  # Nested FilterGroup
                            {"status": "approved"},
                            {"link": "Document Example Test 2"},
                        ]
                    },
                ]
            },
        ]
    }

    for i, vs in enumerate(vector_stores, start=1):
        print(f"\n--- Vector Store {i} Advanced Searches ---")
        # Similarity search without a filter
        print("\nSimilarity search results without filter:")
        print(vs.similarity_search(query, 2))

        # Similarity search with a filter
        print("\nSimilarity search results with filter:")
        print(vs.similarity_search(query, 2, filter=db_filter))

        # Similarity search with relevance score
        print("\nSimilarity search with relevance score:")
        print(vs.similarity_search_with_score(query, 2))

        # Similarity search with relevance score with filter
        print("\nSimilarity search with relevance score with filter:")
        print(vs.similarity_search_with_score(query, 2, filter=db_filter))

        # Max marginal relevance search
        print("\nMax marginal relevance search results:")
        print(vs.max_marginal_relevance_search(query, 2, fetch_k=20, lambda_mult=0.5))

        # Max marginal relevance search with filter
        print("\nMax marginal relevance search results with filter:")
        print(
            vs.max_marginal_relevance_search(
                query, 2, fetch_k=20, lambda_mult=0.5, filter=db_filter
            )
        )


conduct_advanced_searches(vector_store_list)

混合搜索

Oracle Database 26ai 支持混合搜索，将关键字（全文）和语义（向量）搜索结合为单一检索功能。langchain-oracledb 集成暴露了：

• OracleVectorizerPreference：创建用于混合索引的 DB 端向量化偏好设置。
• create_hybrid_index / acreate_hybrid_index：创建 HYBRID VECTOR INDEX。
• OracleHybridSearchRetriever：对 OracleVS 表执行关键字、语义或混合检索。

前置条件和模型配置

使用混合搜索时，请使用 OracleVS 配置 OracleEmbeddings，以便向量化偏好设置与嵌入配置完全匹配。您可以通过 OracleVectorizerPreference 提供附加参数来进一步微调混合向量索引。详细信息，请参阅 文档。

from langchain_core.documents import Document
from langchain_oracledb.embeddings import OracleEmbeddings
from langchain_oracledb.vectorstores.oraclevs import OracleVS
from langchain_oracledb.retrievers.hybrid_search import (
    OracleVectorizerPreference,
    create_hybrid_index,
    OracleHybridSearchRetriever,
)

# Use OracleEmbeddings (database-resident model shown)
embeddings = OracleEmbeddings(conn=connection, params={"provider": "database", "model": "DB_MODEL"})

# Create/load your vector store
vs = OracleVS(connection, table_name="DOCS", embedding_function=embeddings)

# Create a vectorizer preference
pref = OracleVectorizerPreference.create_preference(
    vector_store=vs, preference_name="PREF_DOCS"
)

# Create a HYBRID VECTOR INDEX
create_hybrid_index(
    connection,
    idx_name="IDX_DOCS_HYB",
    vectorizer_preference=pref
)

# Build a retriever and search
retriever = OracleHybridSearchRetriever(
    vector_store=vs,
    idx_name="IDX_DOCS_HYB",
    search_mode="hybrid",     # "hybrid" | "keyword" | "semantic"
    k=5,
    return_scores=True,       # includes score, text_score, vector_score in metadata
)

docs = retriever.invoke("refund policy for premium plan")
for d in docs:
    print(d.page_content, d.metadata.get("score"), d.metadata.get("text_score"), d.metadata.get("vector_score"))

# Optional cleanup when done with the preference:
# pref.drop_preference()

替代 创建索引而不显式指定偏好设置：

• 如果您不想管理命名的偏好设置，请传递 vector_store。该函数将创建临时偏好设置，构建索引，然后自动删除偏好设置。

create_hybrid_index(
    connection,
    idx_name="IDX_DOCS_HYB2",
    vector_store=vs,          # mutually exclusive with vectorizer_preference
    params={"parallel": 8},
)

注意事项和提示：

• search_mode 决定使用的信号：
  • “keyword”：仅关键字
  • “semantic”：仅向量
  • “hybrid”（默认）：两者结合
• 通过检索器的 params 参数传递 DBMS_HYBRID_VECTOR 参数。
• return_scores=True 向 Document.metadata 添加整体分数和组件 text_score 和 vector_score。
• 通过 acreate_hybrid_index 和 OracleHybridSearchRetriever.ainvoke 支持异步使用。

更多信息：

• 理解混合搜索
• CREATE_PREFERENCE
• CREATE_HYBRID_VECTOR_INDEX
• DBMS_HYBRID_VECTOR.SEARCH

全文搜索（Oracle Text）

您可以使用 Oracle Text 直接在 Oracle 数据库上运行高质量的关键字搜索。langchain-oracledb 集成暴露了：

• create_text_index / acreate_text_index：在列上创建 Oracle Text SEARCH INDEX。
• OracleTextSearchRetriever：运行 CONTAINS 查询并返回 LangChain Document 对象。

索引选项：

• 如果您有一个 OracleVS 向量存储，您可以索引其内置的 “text” 列。
• 您也可以通过直接提供 table_name + column_name 来索引任何其他表/列。

from langchain_oracledb.retrievers.text_search import create_text_index, OracleTextSearchRetriever

# Using an OracleVS table (indexes the 'text' column)
retriever_text = None
create_text_index(
    connection,
    idx_name="IDX_DOCS_TEXT",
    vector_store=vs,
)

# Build a retriever. With OracleVS, returned_columns defaults to ["metadata"].
retriever_text = OracleTextSearchRetriever(
    vector_store=vs,
    k=5,
    fuzzy=True,          # applies Oracle Text FUZZY per token when operator_search=False
    return_scores=True,  # adds SCORE(1) as metadata["score"]
)
docs = retriever_text.invoke("refund policy")
for d in docs:
    print(d.page_content, d.metadata.get("score"))

# Alternatively, index an arbitrary table/column:
# create_text_index(connection, idx_name="IDX_MYDOCS_TEXT", table_name="MYDOCS", column_name="CONTENT")
# retriever_text = OracleTextSearchRetriever(client=connection, table_name="MYDOCS", column_name="CONTENT", k=5)

运算符模式和高级查询：

• 默认行为（operator_search=False）：
  • 输入被视为字面文本，在非单词字符上分词，并重写为 ACCUM 表达式。
  • 使用 fuzzy=True 时，每个标记都被包装为 FUZZY("token") 以匹配拼写错误。
• 运算符模式（operator_search=True）：
  • 传递未更改的 Oracle Text 表达式（NEAR、ABOUT、AND、OR、NOT、WITHIN 等）。在此模式下，模糊被忽略。

返回的列：

• 当针对原始表时，通过 returned_columns 在结果中包含附加列；它们附加到 Document.metadata。
• 使用 OracleVS 时，returned_columns 默认为 [“metadata”]。

# Operator mode example
retriever_text_ops = OracleTextSearchRetriever(
    vector_store=vs,
    operator_search=True,   # pass Oracle Text expression directly
    return_scores=True,
)
docs = retriever_text_ops.invoke('NEAR((policy, refund), 2, TRUE)')

注意事项和提示：

• 使用 operator_search=True 时，模糊被忽略（按设计）。
• 通过 acreate_text_index 和 OracleTextSearchRetriever.ainvoke 支持异步使用。

更多信息：

• Oracle Text CONTAINS 查询运算符
• 模糊匹配和词干提取

端到端演示

请参考我们的完整演示指南 Oracle AI Vector Search 端到端演示指南，使用 Oracle AI Vector Search 帮助您构建端到端 RAG 管道。

---

官方原文：src/oss/python/integrations/vectorstores/oracle.mdx · 非官方翻译，译文由 AI 生成，以英文原文为准。