Haystack 集成 Eden AI通过统一 OpenAI 兼容 API 实现多供应商 Embedding 与 Chat 生成【免费下载链接】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 生态中的 Eden AI 集成组件edenai-haystack系统讲解EdenAIDocumentEmbedder、EdenAITextEmbedder与EdenAIChatGenerator三个组件的初始化参数、运行契约、序列化方式及流水线集成方案。读完本文你将掌握如何用一把 Eden AI API Key 在 Haystack 中路由 OpenAI、Mistral、Cohere、Google、Anthropic 等多家供应商的嵌入与对话模型并搭建出带欧盟数据驻留EU data residency特性的 RAG 流水线。一、集成背景Eden AI 是什么为什么要接入 HaystackEden AI 是一个统一的多供应商 AI API 网关通过单个 API Key 即可访问来自 OpenAI、Mistral、Cohere、Google、Jina、Anthropic 等 500 模型并且内置供应商回退provider fallback与欧盟数据驻留能力。对于 Haystack 用户而言它的核心价值在于一套代码、多模型可选模型使用provider/model命名约定例如openai/text-embedding-3-small、mistral/mistral-embed、openai/gpt-4o-mini、anthropic/claude-sonnet-4-5切换供应商只需改一个字符串。OpenAI 兼容协议Eden AI 提供 OpenAI-compatible 端点因此集成组件可以复用 Haystack 中成熟的 OpenAI 系列组件OpenAIDocumentEmbedder、OpenAITextEmbedder、OpenAIChatGenerator的全部配置与调用链路仅替换api_base_url。主权友好sovereignty-friendly数据默认停留在欧盟区域处理适合对数据驻留有合规要求的场景。从源码结构看三个 Eden 组件都继承自对应的 OpenAI 组件见 haystack/components/embedders/openai_document_embedder.py、haystack/components/embedders/openai_text_embedder.py、haystack/components/generators/chat/openai.py因此底层复用 OpenAI Python SDK 的客户端管理与 HTTP 调用机制本仓库内的 API 参考文档收录于 docs-website/reference_versioned_docs/version-2.19/integrations-api/edenai.md。二、安装与密钥配置2.1 安装集成包Eden AI 集成作为独立包发布需额外安装pip install edenai-haystack安装后即可从haystack_integrations命名空间导入三个组件from haystack_integrations.components.embedders.edenai import EdenAIDocumentEmbedder, EdenAITextEmbedder from haystack_integrations.components.generators.edenai import EdenAIChatGenerator2.2 API Key 的两种注入方式三个组件都通过api_key: Secret参数接收密钥默认从EDENAI_API_KEY环境变量读取。推荐方式与直接注入方式的对比# 方式一推荐环境变量组件默认行为 # 先执行 export EDENAI_API_KEYyour-key然后 embedder EdenAIDocumentEmbedder(modelopenai/text-embedding-3-small) # 方式二初始化时用 Secret 显式传入 from haystack.utils import Secret embedder EdenAITextEmbedder( api_keySecret.from_token(your-api-key), modelopenai/text-embedding-3-small, )使用Secret而非裸字符串的好处在于序列化to_dict时不会把明文密钥写入磁盘符合 Haystack 的密钥管理最佳实践详见 docs-website/docs/concepts/secret-management.mdx。三、EdenAIDocumentEmbedder批量文档向量化3.1 组件定位EdenAIDocumentEmbedder用于为一组Document批量计算 Embedding并把结果写入每个Document的embedding字段。在索引流水线中它通常位于 DocumentWriter 之前即「转换器 → 向量化 → 写入文档库」的标准位置。3.2 初始化参数全解来自 docs-website/reference_versioned_docs/version-2.19/integrations-api/edenai.md 的完整签名__init__( *, model: str openai/text-embedding-3-small, api_key: Secret Secret.from_env_var(EDENAI_API_KEY), api_base_url: str | None https://api.edenai.run/v3, prefix: str , suffix: str , batch_size: int 32, progress_bar: bool True, meta_fields_to_embed: list[str] | None None, embedding_separator: str \n, timeout: float | None None, max_retries: int | None None, http_client_kwargs: dict[str, Any] | None None ) - None参数默认值说明modelopenai/text-embedding-3-smallEden AI 嵌入模型名采用provider/model格式api_keyEDENAI_API_KEY环境变量Eden AI API 密钥api_base_urlhttps://api.edenai.run/v3Eden AI API 基础地址OpenAI 兼容端点prefix/suffix拼接到每条文本开头/结尾的字符串可用于给待嵌入文本附加指令batch_size32每次编码的 Document 数量progress_barTrue是否显示进度条生产环境建议关闭以保持日志干净meta_fields_to_embedNone需要随正文一起嵌入的元数据字段列表embedding_separator\n元数据字段与正文拼接时的分隔符timeoutNoneAPI 调用超时未设置时回退到OPENAI_TIMEOUT环境变量否则默认 30 秒max_retriesNone遇到内部错误时的最大重试次数未设置时回退到OPENAI_MAX_RETRIES环境变量否则默认 5 次http_client_kwargsNone自定义httpx.Client/httpx.AsyncClient的关键字参数字典参数背后的实现细节在 haystack/components/embedders/openai_document_embedder.py 的_client_kwargs()中timeout与max_retries的取值逻辑是「显式传参优先其次读OPENAI_TIMEOUT/OPENAI_MAX_RETRIES环境变量最后落到默认值」Eden 组件继承该机制文本构造逻辑见同文件_prepare_texts_to_embed()第 227-241 行它将prefix embedding_separator.join(meta_values [content]) suffix拼成最终待嵌入文本meta_fields_to_embed中缺失或为None的字段会被自动跳过。3.3 支持的模型列表组件暴露了非穷举的SUPPORTED_MODELS常量完整清单以 Eden AI 官方模型目录为准SUPPORTED_MODELS: list[str] [ openai/text-embedding-3-small, openai/text-embedding-3-large, mistral/mistral-embed, cohere/embed-english-v3.0, google/text-embedding-004, ]3.4 单独使用与索引流水线单独使用from haystack import Document from haystack_integrations.components.embedders.edenai import EdenAIDocumentEmbedder doc Document(contentI love pizza!) document_embedder EdenAIDocumentEmbedder(modelmistral/mistral-embed) result document_embedder.run([doc]) print(result[documents][0].embedding) # [0.017020374536514282, -0.023255806416273117, ...]run方法接收documents: list[Document]返回documents已填充embedding的文档列表与meta包含模型名与 token 用量统计。将向量化嵌入索引流水线from haystack import Pipeline from haystack.components.converters import TextFileToDocument from haystack.components.writers import DocumentWriter from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack_integrations.components.embedders.edenai import EdenAIDocumentEmbedder document_store InMemoryDocumentStore() indexing_pipeline Pipeline() indexing_pipeline.add_component(converter, TextFileToDocument()) indexing_pipeline.add_component( embedder, EdenAIDocumentEmbedder(modelopenai/text-embedding-3-small) ) indexing_pipeline.add_component(writer, DocumentWriter(document_storedocument_store)) indexing_pipeline.connect(converter, embedder) indexing_pipeline.connect(embedder, writer) indexing_pipeline.run({converter: {sources: [./my_document.txt]}})四、EdenAITextEmbedder查询字符串向量化4.1 组件定位EdenAITextEmbedder用于把单个字符串典型场景是用户查询转成向量在查询/RAG 流水线中通常位于 Embedding Retriever 之前。它与EdenAIDocumentEmbedder的分工是后者处理文档列表并回写Document.embedding前者处理单条文本并直接返回embedding与meta。4.2 初始化参数签名相对 Document 版本少了batch_size、progress_bar、meta_fields_to_embed、embedding_separator四个批量相关参数__init__( *, model: str openai/text-embedding-3-small, api_key: Secret Secret.from_env_var(EDENAI_API_KEY), api_base_url: str | None https://api.edenai.run/v3, prefix: str , suffix: str , timeout: float | None None, max_retries: int | None None, http_client_kwargs: dict[str, Any] | None None ) - None各参数含义与 Document 版一致prefix/suffix拼接进待嵌入文本timeout与max_retries同样遵循「显式参数 →OPENAI_TIMEOUT/OPENAI_MAX_RETRIES环境变量 → 30 秒/5 次」的取值链路见 haystack/components/embedders/openai_text_embedder.py 的_client_kwargs()。SUPPORTED_MODELS与 Document 版完全相同。4.3 单独使用与查询流水线单独使用from haystack.utils import Secret from haystack_integrations.components.embedders.edenai import EdenAITextEmbedder embedder EdenAITextEmbedder( api_keySecret.from_token(your-api-key), modelopenai/text-embedding-3-small, ) result embedder.run(textHow can I use the Eden AI embedding models with Haystack?) print(result[embedding]) # [-0.0015687942504882812, 0.052154541015625, 0.037109375...]run方法接收text: str非字符串输入会抛出TypeError返回{embedding: [...], meta: {model: ..., usage: ...}}。将其接入一个端到端语义检索流水线与EdenAIDocumentEmbedder形成「索引 查询」闭环from haystack import Pipeline from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever from haystack.document_stores.in_memory import InMemoryDocumentStore from haystack.dataclasses import Document from haystack_integrations.components.embedders.edenai import ( EdenAIDocumentEmbedder, EdenAITextEmbedder, ) document_store InMemoryDocumentStore(embedding_similarity_functioncosine) documents [ Document(contentMy name is Wolfgang and I live in Berlin), Document(contentI saw a black horse running), Document(contentGermany has many big cities), ] document_embedder EdenAIDocumentEmbedder(modelopenai/text-embedding-3-small) documents_with_embeddings document_embedder.run(documents)[documents] document_store.write_documents(documents_with_embeddings) query_pipeline Pipeline() query_pipeline.add_component( text_embedder, EdenAITextEmbedder(modelopenai/text-embedding-3-small) ) query_pipeline.add_component( retriever, InMemoryEmbeddingRetriever(document_storedocument_store) ) query_pipeline.connect(text_embedder.embedding, retriever.query_embedding) result query_pipeline.run({text_embedder: {text: Who lives in Berlin?}}) print(result[retriever][documents][0])注意上述示例中索引与查询两侧必须使用同一嵌入模型否则向量空间不一致会直接导致检索失效。五、EdenAIChatGenerator多供应商 Chat 生成5.1 组件定位EdenAIChatGenerator通过 Eden AI 的 OpenAI 兼容端点执行对话补全。它继承 Haystack 的OpenAIChatGenerator把api_base_url指向 Eden AI同时保留 OpenAI 版本的全部标准配置能力。它输入/输出均为ChatMessage列表在对话流水线中通常位于 ChatPromptBuilder 之后。5.2 初始化参数全解__init__( *, api_key: Secret Secret.from_env_var(EDENAI_API_KEY), model: str openai/gpt-4o-mini, streaming_callback: StreamingCallbackT | None None, generation_kwargs: dict[str, Any] | None None, timeout: int | None None, max_retries: int | None None, tools: ToolsType | None None, tools_strict: bool False, http_client_kwargs: dict[str, Any] | None None ) - None参数默认值说明api_keyEDENAI_API_KEY环境变量Eden AI API 密钥modelopenai/gpt-4o-mini模型名采用provider/model格式如anthropic/claude-sonnet-4-5、mistral/mistral-large-latest、google/gemini-2.5-flashstreaming_callbackNone流式输出回调每个响应分块被调用一次generation_kwargsNone透传给底层生成 API 的额外参数如max_tokens、temperature、top_pEden AI 特有参数例如回退模型 fallback会原样转发timeoutNone等待 API 响应的最大秒数max_retriesNone请求失败的最大重试次数toolsNone供模型进行函数调用的工具列表可传Tool对象列表、单个Toolset或二者混合tools_strictFalse为True时启用工具调用的严格 Schema 遵守http_client_kwargsNone透传给底层 HTTP 客户端的可选参数5.3 单独使用与流式输出基础对话from haystack_integrations.components.generators.edenai import EdenAIChatGenerator from haystack.dataclasses import ChatMessage messages [ChatMessage.from_user(Whats Natural Language Processing?)] client EdenAIChatGenerator(modelmistral/mistral-large-latest) response client.run(messages) print(response[replies][0].text)启用流式输出只需传入一个流式回调Haystack 内置print_streaming_chunk可即时打印每个 tokenfrom haystack_integrations.components.generators.edenai import EdenAIChatGenerator from haystack.components.generators.utils import print_streaming_chunk from haystack.dataclasses import ChatMessage from haystack.utils import Secret generator EdenAIChatGenerator( api_keySecret.from_env_var(EDENAI_API_KEY), modelmistral/mistral-large-latest, streaming_callbackprint_streaming_chunk, ) message ChatMessage.from_user(Whats Natural Language Processing? Be brief.) print(generator.run([message]))5.4 基于网页内容的 RAG 流水线下面是一个完整的 RAG 示例抓取 URL 内容 → 转成文档 → 拼进提示词 → 用EdenAIChatGenerator生成回答完整覆盖了「抓取—转换—提示—生成」四条连接from haystack import Pipeline from haystack.components.builders import ChatPromptBuilder from haystack.components.fetchers import LinkContentFetcher from haystack.components.converters import HTMLToDocument from haystack.dataclasses import ChatMessage from haystack_integrations.components.generators.edenai import EdenAIChatGenerator fetcher LinkContentFetcher() converter HTMLToDocument() prompt_builder ChatPromptBuilder(variables[documents]) llm EdenAIChatGenerator(modelmistral/mistral-large-latest) message_template Answer the following question based on the contents of the article: {{query}}\n Article: {{documents[0].content}} \n messages [ChatMessage.from_user(message_template)] rag_pipeline Pipeline() rag_pipeline.add_component(namefetcher, instancefetcher) rag_pipeline.add_component(nameconverter, instanceconverter) rag_pipeline.add_component(prompt_builder, prompt_builder) rag_pipeline.add_component(llm, llm) rag_pipeline.connect(fetcher.streams, converter.sources) rag_pipeline.connect(converter.documents, prompt_builder.documents) rag_pipeline.connect(prompt_builder.prompt, llm.messages) question What is Eden AI? result rag_pipeline.run( { fetcher: {urls: [https://www.edenai.co/]}, prompt_builder: { template_variables: {query: question}, template: messages, }, }, ) print(result[llm][replies][0].text)六、序列化与组件生命周期三个 Eden 组件均实现to_dict()用于把组件序列化为字典例如用于保存/加载流水线定义。to_dict返回包含初始化参数的字典其中api_key以Secret形式序列化而非明文避免密钥落盘。从基类源码可以确认更多生命周期细节见 haystack/components/embedders/openai_document_embedder.pywarm_up()/warm_up_async()惰性创建同步/异步 OpenAI 客户端调用发生在首次run之前close()/close_async()释放客户端连接供流水线结束或组件回收时调用_embed_batch()内部按batch_size分批请求失败时默认记录日志并跳过该批raise_on_failureTrue时改为抛异常并累加usage.prompt_tokens/usage.total_tokens到meta。Eden 组件继承上述全部机制因此以EdenAIDocumentEmbedder等组件构建的流水线同样支持to_dict序列化、warm_up预热与close释放行为与原生 OpenAI 组件保持一致。七、生产实践建议密钥安全始终通过EDENAI_API_KEY环境变量注入密钥不要硬编码如需在初始化时传入使用Secret.from_token(...)而非裸字符串。超时与重试无需逐组件传参时可统一设置OPENAI_TIMEOUT与OPENAI_MAX_RETRIES环境变量所有 Eden 组件都会自动读取默认分别为 30 秒与 5 次。进度条开关文档 Embedder 的progress_bar在 CI/生产日志环境中建议置为False保持日志干净。模型一致性同一 RAG 系统中 Document Embedder 与 Text Embedder 必须使用同一嵌入模型切换模型后需重新索引全部文档。多供应商容灾借助generation_kwargs透传 Eden AI 的回退模型参数可为 Chat 生成配置供应商级 fallback提升流水线可用性。完整模型清单SUPPORTED_MODELS仅为常用子集最新可用模型请查阅 Eden AI 官方模型目录。通过以上三个组件Haystack 开发者可以在不修改流水线结构的前提下自由切换嵌入与生成模型的底层供应商兼顾模型选型的灵活性、数据驻留的合规性以及单一密钥的运维简洁性。【免费下载链接】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），仅供参考