在 Haystack 中使用 Oracle AI Vector SearchOracleDocumentStore 与 OracleEmbeddingRetriever 集成实战【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack本文以 Haystack 仓库中 Oracle 集成 API 参考文档docs-website/reference_versioned_docs/version-2.23/integrations-api/oracle.md为核心骨架系统讲解如何在 Haystack 中接入 Oracle AI Vector Search从OracleConnectionConfig的连接模式、OracleDocumentStore的初始化与索引管理到OracleEmbeddingRetriever的向量检索与全套元数据操作方法。读完本文你将掌握在 Oracle Database 23ai 之上搭建可运行的向量检索与 RAG 管线的完整技能。一、集成概览Oracle AI Vector Search 与 HaystackOracle AI Vector Search 是 Oracle Database 23ai 及更高版本内置的向量检索能力。Haystack 通过oracle-haystack集成包将其封装为标准组件提供两个核心模块对应 API 参考文档中的两个章节haystack_integrations.document_stores.oracle.document_storeOracleDocumentStore把文档连同稠密向量存储在数据库原生的VECTOR列中并借助自动管理的DBMS_SEARCH索引同时支持向量相似度检索与关键词全文检索OracleConnectionConfig负责连接参数配置。haystack_integrations.components.retrievers.oracle.embedding_retrieverOracleEmbeddingRetriever通过向量相似度从OracleDocumentStore中取回相关文档通常置于文本嵌入器Text Embedder之后。在 docs-website/docs/concepts/document-store/choosing-a-document-store.mdx 的文档存储选型表中Oracle 被标记为支持 Embedding 与 Keyword 两类检索方式定位为「带原生 AI Vector Search、HNSW 向量索引与 DBMS_SEARCH 全文关键词索引的关系型数据库」方案——这意味着你可以在不引入额外向量数据库的前提下让现有 Oracle 数据资产直接参与 RAG 与语义搜索。二、环境准备本地启动 Oracle 23ai 并安装集成包依据 OracleEmbeddingRetriever 使用指南可先用 Docker 在本地运行 Oracle Database 23ai 免费版docker run -d --name oracle23ai \ -p 1521:1521 \ -e ORACLE_PASSWORDoracle \ -e ORACLE_INIT_PARAMSvector_memory_size512M \ gvenzl/oracle-free:23-slim随后安装集成包与配套的 Sentence Transformers 嵌入器pip install oracle-haystack pip install sentence-transformers-haystack前提与限制OracleDocumentStore要求 Oracle Database23ai 或更高版本——这是VECTOR数据类型与IF NOT EXISTSDDL 支持的前提见 API 参考文档中OracleDocumentStore的说明。若你只需纯关键词检索而不使用嵌入器sentence-transformers-haystack可省略。三、连接配置OracleConnectionConfig 的 Thin 与 Thick 双模式OracleConnectionConfig封装了 Oracle 数据库的连接参数API 参考文档明确指出它支持两种连接模式Thin 模式默认直接基于 TCP 连接无需安装 Oracle Instant Client适合本地或普通网络可达的数据库。Thick 模式当提供wallet_location时自动激活用于 Oracle Autonomous DatabaseADB-S等需要钱包Wallet认证的场景。推荐通过环境变量注入敏感信息配合Secret.from_env_var既符合 Haystack 的密钥管理规范也避免凭据硬编码export ORACLE_USERhaystack export ORACLE_PASSWORDsecret export ORACLE_DSNlocalhost:1521/freepdb1两种模式的构造方式完整示例见 oracledocumentstore.mdxfrom haystack.utils import Secret from haystack_integrations.document_stores.oracle import ( OracleDocumentStore, OracleConnectionConfig, ) # Thin 模式无需 Instant Client store OracleDocumentStore( connection_configOracleConnectionConfig( userSecret.from_env_var(ORACLE_USER), passwordSecret.from_env_var(ORACLE_PASSWORD), dsnSecret.from_env_var(ORACLE_DSN), ), embedding_dim1536, ) # Thick 模式ADB-S提供钱包路径即自动激活 store OracleDocumentStore( connection_configOracleConnectionConfig( userSecret.from_env_var(ORACLE_USER), passwordSecret.from_env_var(ORACLE_PASSWORD), dsnSecret.from_env_var(ORACLE_DSN), wallet_location/path/to/wallet, wallet_passwordSecret.from_env_var(WALLET_PASSWORD), ), embedding_dim1536, )OracleConnectionConfig与 Haystack 组件一致地实现了to_dict()/from_dict()便于将连接配置随管线一起序列化与反序列化。四、OracleDocumentStore初始化参数与存储语义OracleDocumentStore是集成的中枢组件其__init__签名来自 API 参考文档如下__init__( *, connection_config: OracleConnectionConfig, table_name: str haystack_documents, embedding_dim: int, distance_metric: Literal[COSINE, EUCLIDEAN, DOT] COSINE, create_table_if_not_exists: bool True, create_index: bool False, hnsw_neighbors: int 32, hnsw_ef_construction: int 200, hnsw_accuracy: int 95, hnsw_parallel: int 4 ) - None各参数含义与取值约束参数默认值说明connection_config必填Oracle 连接设置user、password、DSN、可选 wallet见上文双模式说明table_namehaystack_documents存储文档的 Oracle 表名。必须是合法 Oracle 标识符仅字母、数字、_、$、#最长 128 字符不能以数字开头否则抛出ValueErrorembedding_dim必填嵌入向量维度必须与生成向量的模型一致如 OpenAItext-embedding-3-small为 1536MiniLM-L6-v2 为 384非正整数抛出ValueErrordistance_metricCOSINE相似度计算的向量距离函数可选COSINE、EUCLIDEAN、DOT需与嵌入模型的语义空间匹配create_table_if_not_existsTrue首次使用时自动建表并创建DBMS_SEARCH关键词索引连接已存在的表时应设为Falsecreate_indexFalse初始化时是否创建 HNSW 向量索引等价于手动调用create_hnsw_index()hnsw_neighbors32HNSW 图中的邻居数量越大召回越好但索引体积与构建时间增加hnsw_ef_construction200HNSW 构建时的动态候选列表大小越大召回越好但构建越慢hnsw_accuracy95HNSW 索引的目标召回准确率百分比0–100hnsw_parallel4构建 HNSW 索引时的并行度关于 HNSW 索引的一个重要行为差异默认情况下create_indexFalse存储执行的是精确向量检索当数据集变大时可通过create_indexTrue在启动时创建 HNSW 索引切换到近似最近邻检索以换取更快的查询速度。使用指南中的推荐配置如下document_store OracleDocumentStore( connection_configOracleConnectionConfig( userSecret.from_env_var(ORACLE_USER), passwordSecret.from_env_var(ORACLE_PASSWORD), dsnSecret.from_env_var(ORACLE_DSN), ), embedding_dim768, distance_metricCOSINE, create_indexTrue, # 启动时创建 HNSW 索引 hnsw_neighbors32, hnsw_ef_construction200, hnsw_accuracy95, )五、索引管理关键词索引与向量索引的创建时机API 参考文档为OracleDocumentStore提供了两组索引管理方法create_keyword_index()在表上创建DBMS_SEARCH关键词索引关键词检索的前提。可安全多次调用——索引已存在时静默跳过。当create_table_if_not_existsTrue时会自动调用连接已存在的表时则必须显式调用。create_hnsw_index()/create_hnsw_index_async()在嵌入列上创建 HNSW 向量索引同样可安全多次调用使用IF NOT EXISTS。异步版本用于不阻塞事件循环的场景。这与上文create_index参数互为补充create_indexTrue相当于在初始化时自动执行create_hnsw_index()而手动调用则赋予你更灵活的控制时机例如在大量写入完成之后再构建索引。六、向量检索OracleEmbeddingRetrieverOracleEmbeddingRetriever从OracleDocumentStore中按向量相似度取回文档是 RAG 与语义搜索管线中的关键一环。6.1 方法签名与运行语义run与run_async异步变体签名一致run( query_embedding: list[float], filters: dict[str, Any] | None None, top_k: int | None None, ) - dict[str, list[Document]]参数语义query_embedding来自嵌入器组件的稠密浮点向量是必填运行参数filters运行时过滤器按filter_policy与构造时的过滤器合并元数据过滤规则详见 Haystack 的 metadata filtering 规范top_k本次调用对构造时top_k的覆盖值用于控制返回文档数量上限。返回值为{documents: [Document, ...]}。此外组件还实现了close()释放底层 Document Store 的同步资源以及标准的to_dict()/from_dict()序列化接口。6.2 独立使用from haystack.utils import Secret from haystack_integrations.document_stores.oracle import ( OracleDocumentStore, OracleConnectionConfig, ) from haystack_integrations.components.retrievers.oracle import OracleEmbeddingRetriever document_store OracleDocumentStore( connection_configOracleConnectionConfig( userSecret.from_env_var(ORACLE_USER), passwordSecret.from_env_var(ORACLE_PASSWORD), dsnSecret.from_env_var(ORACLE_DSN), ), embedding_dim768, ) retriever OracleEmbeddingRetriever(document_storedocument_store) # 使用假向量保持示例简洁768 维 retriever.run(query_embedding[0.1] * 768)6.3 在管线中使用OracleEmbeddingRetriever的典型位置是文本嵌入器之后、PromptBuilder之前的 RAG 管线或语义搜索管线的末位组件详见 oracleembeddingretriever.mdx 中的位置说明。其必需初始化变量为document_store必需运行变量为query_embedding输出变量为documents。from haystack import Document, Pipeline from haystack.document_stores.types import DuplicatePolicy from haystack_integrations.components.embedders.sentence_transformers import ( SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder, ) from haystack.utils import Secret from haystack_integrations.document_stores.oracle import ( OracleDocumentStore, OracleConnectionConfig, ) from haystack_integrations.components.retrievers.oracle import OracleEmbeddingRetriever document_store OracleDocumentStore( connection_configOracleConnectionConfig( userSecret.from_env_var(ORACLE_USER), passwordSecret.from_env_var(ORACLE_PASSWORD), dsnSecret.from_env_var(ORACLE_DSN), ), embedding_dim768, ) documents [ Document(contentThere are over 7,000 languages spoken around the world today.), Document(contentElephants have been observed to behave in a way that indicates a high level of self-awareness, such as recognizing themselves in mirrors.), Document(contentIn certain parts of the world, like the Maldives, Puerto Rico, and San Diego, you can witness the phenomenon of bioluminescent waves.), ] # 索引阶段文档嵌入器生成向量后写入 document_embedder SentenceTransformersDocumentEmbedder( modelsentence-transformers/all-MiniLM-L6-v2, ) documents_with_embeddings document_embedder.run(documents) document_store.write_documents( documents_with_embeddings[documents], policyDuplicatePolicy.OVERWRITE, ) # 查询阶段文本嵌入器 → 向量检索器 query_pipeline Pipeline() query_pipeline.add_component( text_embedder, SentenceTransformersTextEmbedder(modelsentence-transformers/all-MiniLM-L6-v2), ) query_pipeline.add_component( retriever, OracleEmbeddingRetriever(document_storedocument_store), ) query_pipeline.connect(text_embedder.embedding, retriever.query_embedding) query How many languages are there? result query_pipeline.run({text_embedder: {text: query}}) print(result[retriever][documents][0])关键点在于索引时用 Document Embedder 为文档生成向量查询时用 Text Embedder 为查询生成向量二者模型必须一致本例均为all-MiniLM-L6-v2与embedding_dim768对应。距离度量COSINE / EUCLIDEAN / DOT在OracleDocumentStore上配置。七、关键词检索OracleKeywordRetriever与向量检索互补的是 OracleKeywordRetriever——它利用初始化时自动创建的DBMS_SEARCH全文索引按关键词相关性检索文档无需任何嵌入向量适合纯关键词管线或混合检索Hybrid Search的关键词分支。其必需运行变量为query字符串输出同样为documents列表。from haystack_integrations.document_stores.oracle import ( OracleDocumentStore, OracleConnectionConfig, ) from haystack_integrations.components.retrievers.oracle import OracleKeywordRetriever document_store OracleDocumentStore( connection_configOracleConnectionConfig( userSecret.from_env_var(ORACLE_USER), passwordSecret.from_env_var(ORACLE_PASSWORD), dsnSecret.from_env_var(ORACLE_DSN), ), embedding_dim768, ) retriever OracleKeywordRetriever(document_storedocument_store) retriever.run(querymy keyword query)同样的它接受top_k与filters来收窄检索范围并可接入 RAG 管线检索器 →ChatPromptBuilder→OpenAIChatGenerator。八、文档写入与重复策略write_documents/write_documents_async将文档列表写入存储并通过DuplicatePolicy控制重复文档的处理write_documents( documents: list[Document], policy: DuplicatePolicy DuplicatePolicy.NONE ) - int返回值为实际写入的文档数量当某个文档 id 已存在且策略为DuplicatePolicy.FAIL或DuplicatePolicy.NONE时抛出DuplicateDocumentError使用指南中的索引示例采用DuplicatePolicy.OVERWRITE覆盖写入关键词检索示例则使用DuplicatePolicy.SKIP跳过已存在文档可按幂等需求灵活选用。九、元数据查询与过滤全套管理方法API 参考文档为OracleDocumentStore提供了丰富的元数据能力每个方法均配套_async异步变体filter_documents(filters)返回匹配过滤条件的文档列表过滤规则遵循 Haystack 的 metadata filtering 规范count_documents()统计库内文档总数count_documents_by_filter(filters)统计匹配过滤器的文档数空字典匹配全部文档delete_documents(document_ids)按文档 id 列表删除文档delete_by_filter(filters)删除匹配过滤器的文档返回删除数量空字典视为 no-op返回 0 且不触碰表update_by_filter(filters, meta)把meta合并进匹配文档的元数据——底层使用 Oracle 的JSON_MERGEPATCH已存在的键被更新、新键被添加、meta中值为null的键被移除meta为空字典时抛出ValueErrorcount_unique_metadata_by_filter(filters, metadata_fields)统计各元数据字段在匹配文档中的不同取值数量。字段名可带meta.前缀如meta.lang或langmetadata_fields为空或字段名含[A-Za-z0-9_.]之外的字符时抛出ValueErrorget_metadata_fields_info()返回{field_name: {type: type}, ...}形式的字段类型映射类型为text、number或boolean。底层使用 Oracle 的JSON_DATAGUIDE聚合函数对元数据列进行结构探查表为空时返回空字典get_metadata_field_min_max(metadata_field)返回{min: value, max: value}。实现上先尝试用TO_NUMBER做数值比较使MAX(1, 5, 10)正确返回10而非字典序下胜出的5字段含非数值内容时回退到纯字符串比较数值字符串在结果中自动转为int或float表为空或字段不存在时两个值均为Noneget_metadata_field_unique_values(metadata_field, search_term, from_, size, filters)返回(values, total)元组——values是分页的不同取值列表from_为零基偏移size默认 10传None时返回from_之后全部total是分页前的总不同值数。search_term是对字段自身值的不区分大小写的子串过滤。该方法的文档还揭示了一个值得注意的类型语义不同 JSON 类型类别的值彼此独立——字符串、数字、布尔值即使文本形式相同如字符串1与数字1也不会合并。唯一的例外是由于metadata列是 Oracle 原生JSON类型会对数值存储做规范化因此整数值浮点1.0与数值相等的整数1会合并为同一值而带小数部分的浮点如1.5不受影响。十、生命周期管理删除、清空与资源释放delete_table()/delete_table_async()永久删除文档表及其关联的DBMS_SEARCH关键词索引。底层使用DROP TABLE ... PURGE绕过 Oracle 回收站、不可恢复索引在表之后删除任一操作失败均抛出DocumentStoreError。delete_all_documents()/delete_all_documents_async()使用TRUNCATE清空表中全部文档。TRUNCATE不可回滚、绕过行级触发器但表结构与索引会被保留。close()释放底层 Document Store 关联的同步资源。这些破坏性操作的语义PURGE 与 TRUNCATE 的不可恢复性在 API 参考文档中被明确强调生产环境中应谨慎调用。十一、序列化to_dict 与 from_dict集成中的所有类OracleEmbeddingRetriever、OracleConnectionConfig、OracleDocumentStore都实现了标准的 Haystack 序列化协议to_dict() - dict[str, Any]将组件序列化为字典便于保存到 YAML/JSON 或随Pipeline.dumps()持久化from_dict(data) - 对应类实例从字典反序列化还原组件实例如from_dict(data) - OracleEmbeddingRetriever。这意味着基于 Oracle 的检索与索引配置可以完整地进入 Haystack 的管线序列化体系支持声明式定义与跨环境复用。十二、完整实战基于 Oracle 的 RAG 问答管线综合以上能力一个端到端的 RAG 管线如下完整示例见 oracledocumentstore.mdxfrom haystack import Document, Pipeline from haystack.document_stores.types import DuplicatePolicy from haystack_integrations.components.embedders.sentence_transformers import ( SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder, ) from haystack.components.builders import ChatPromptBuilder from haystack.components.generators.chat import OpenAIChatGenerator from haystack.dataclasses import ChatMessage from haystack.utils import Secret from haystack_integrations.document_stores.oracle import ( OracleDocumentStore, OracleConnectionConfig, ) from haystack_integrations.components.retrievers.oracle import OracleEmbeddingRetriever document_store OracleDocumentStore( connection_configOracleConnectionConfig( userSecret.from_env_var(ORACLE_USER), passwordSecret.from_env_var(ORACLE_PASSWORD), dsnSecret.from_env_var(ORACLE_DSN), ), embedding_dim384, ) # 1) 索引文档 documents [ Document(contentThere are over 7,000 languages spoken around the world today.), Document(contentElephants have been observed to behave in a way that indicates a high level of self-awareness.), Document(contentIn certain places, you can witness the phenomenon of bioluminescent waves.), ] doc_embedder SentenceTransformersDocumentEmbedder( modelsentence-transformers/all-MiniLM-L6-v2, ) embedded_docs doc_embedder.run(documents)[documents] document_store.write_documents(embedded_docs, policyDuplicatePolicy.OVERWRITE) # 2) 构建 RAG 管线 template [ ChatMessage.from_user( Given the following context, answer the question. Context: {% for doc in documents %}{{ doc.content }}{% endfor %} Question: {{ query }} , ), ] pipeline Pipeline() pipeline.add_component( embedder, SentenceTransformersTextEmbedder(modelsentence-transformers/all-MiniLM-L6-v2), ) pipeline.add_component( retriever, OracleEmbeddingRetriever(document_storedocument_store, top_k3), ) pipeline.add_component(prompt_builder, ChatPromptBuilder(templatetemplate)) pipeline.add_component( llm, OpenAIChatGenerator(api_keySecret.from_env_var(OPENAI_API_KEY)), ) pipeline.connect(embedder.embedding, retriever.query_embedding) pipeline.connect(retriever.documents, prompt_builder.documents) pipeline.connect(prompt_builder.prompt, llm.messages) result pipeline.run( { embedder: {text: How many languages are there?}, prompt_builder: {query: How many languages are there?}, }, ) print(result[llm][replies][0].text)十三、总结与最佳实践要点版本前提使用OracleDocumentStore前确认数据库为Oracle 23ai本地开发可用 Docker 启动gvenzl/oracle-free:23-slim并设置vector_memory_size初始化参数。连接模式自选普通 TCP 用 Thin 模式零客户端依赖ADB-S 提供wallet_location即自动切换 Thick 模式敏感凭据统一走环境变量 Secret.from_env_var。维度一致性embedding_dim必须与嵌入模型输出维度严格一致这是向量检索正确性的根基。索引按需创建关键词检索依赖DBMS_SEARCH索引向量检索默认精确搜索数据量大时用create_indexTrue或create_hnsw_index()启用 HNSW 近似检索并权衡hnsw_neighbors/hnsw_ef_construction/hnsw_accuracy/hnsw_parallel的精度与构建成本。同步/异步双 API写入、过滤、计数、删除、元数据探查与索引创建均提供_async变体适配异步管线与高并发场景。破坏性操作需谨慎delete_tableDROP TABLE ... PURGE与delete_all_documentsTRUNCATE均不可恢复。通过上述组件Haystack 用户可以在一套统一的 Pipeline 抽象下让 Oracle 数据库同时承担关系数据存储、向量检索与全文检索三种职责是构建企业级 RAG、语义搜索与对话式应用的务实选择。【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
