PraisonAI 接入 Gemini 向量嵌入模型为 Agent 记忆与语义检索配置自定义 Embedder 实战指南【免费下载链接】PraisonAIPraisonAI — Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous self-improving agents that research, plan, code, and execute tasks. Deployed in 5 lines of code with built-in memory, RAG, and support for 100 LLMs.项目地址: https://gitcode.com/GitHub_Trending/pr/PraisonAIPraisonAI 通过 LiteLLM 实现了可配置的 Embedding 模型体系让开发者可以摆脱 OpenAItext-embedding-3-small的默认绑定直接使用 Google Gemini 系列向量模型如text-embedding-004、gemini-embedding-exp-03-07驱动记忆存储与语义检索。本文以 gemini-embeddings.md 为核心脉络结合仓库源码与完整示例系统讲解 embedder 配置原理、参数细节、Mem0 透传机制与向量维度陷阱帮助读者在 5 行配置内完成 Gemini Embedding 的接入与验证。一、功能概览为什么需要可插拔的 EmbedderPraisonAI 的记忆系统Memory依赖向量化表示完成语义检索文本先被转换为向量Embedding再写入向量数据库查询时通过向量相似度召回相关内容。传统方案将 Embedding 模型硬编码为 OpenAI 的text-embedding-3-small而 PraisonAI 现在通过 LiteLLM 统一抽象层支持任意嵌入模型——这意味着 Google Gemini、Cohere、Voyage、Mistral、Jina 乃至本地 Ollama 模型都可以无缝接入。从源码结构看这一设计是协议驱动 适配器注册的记忆架构的一部分memory.py 在初始化时读取embedder配置块并将其中的config.model解析为实际的embedding_model默认值正是text-embedding-3-small随后把该模型传递给底层向量存储适配器Mem0、Chroma、SQLite 等。因此换一种向量模型在 PraisonAI 中本质上就是换一个 embedder 配置块。二、配置方式从默认 OpenAI 切换到 Gemini2.1 默认配置OpenAI不传任何 embedder 参数时PraisonAI 自动使用 OpenAI 的text-embedding-3-smallfrom praisonaiagents import PraisonAIAgents agents PraisonAIAgents( agents[...], tasks[...], memoryTrue # Uses default OpenAI embeddings )源码中的默认值逻辑位于 memory.pyself.embedder_config self.cfg.get(embedder, {}) if isinstance(self.embedder_config, dict): embedder_model_config self.embedder_config.get(config, {}) self.embedding_model embedder_model_config.get(model, text-embedding-3-small)即embedder缺失或为空时embedding_model回退到 OpenAI 默认模型这保证了向后兼容。2.2 使用 Gemini Embeddings只需在embedder参数中声明provider与config.modelfrom praisonaiagents import PraisonAIAgents agents PraisonAIAgents( agents[...], tasks[...], memoryTrue, embedder{ provider: gemini, config: { model: text-embedding-004 # or gemini-embedding-exp-03-07 } } )这里的provider: gemini会被 LiteLLM 识别并路由到 Google 的 Embedding APIconfig.model指定具体的模型标识。在 agents.py 中embedder从解析后的记忆配置中被提取随后在 agents.py 注入到记忆配置中if _embedder: if isinstance(_embedder, dict): mem_cfg[embedder] _embedder else: mem_cfg[embedder_function] _embedder值得注意的是embedder既支持字典形式的声明式配置也支持直接传入一个可调用的 embedding 函数embedder_function后者适用于自定义向量化逻辑的高级场景。三、前置条件API Key设置 Google API 密钥环境变量export GOOGLE_API_KEYyour-api-key依赖安装确保安装了记忆功能依赖pip install praisonaiagents[memory]LiteLLMlitellm随praisonaiagents一并安装它是 Gemini Embedding 调用的底层网关若遇到 LiteLLM 相关报错请确认其已安装且版本较新。在示例脚本 gemini-embedding-example.py 中程序启动时会主动校验GOOGLE_API_KEY是否存在缺失则打印提示并退出避免运行时才暴露密钥问题if not os.environ.get(GOOGLE_API_KEY): print(Error: GOOGLE_API_KEY environment variable not set) print(Please set it with: export GOOGLE_API_KEYyour-api-key) return四、支持的模型与任务类型Task Type4.1 Gemini Embedding 模型模型标识说明text-embedding-004稳定版Stable嵌入模型适合生产环境gemini-embedding-exp-03-07实验版Experimental带更高级的特性4.2 任务类型可选优化Gemini 支持按任务场景做针对性优化通过config.task_type传入SEMANTIC_SIMILARITYCLASSIFICATIONCLUSTERINGRETRIEVAL_DOCUMENTRETRIEVAL_QUERYQUESTION_ANSWERINGFACT_VERIFICATION示例embedder{ provider: gemini, config: { model: text-embedding-004, task_type: RETRIEVAL_DOCUMENT } }对于先入库、后检索的记忆场景推荐在写入阶段使用RETRIEVAL_DOCUMENT、在查询阶段使用RETRIEVAL_QUERY让向量分布贴合检索目标。任务类型是可选参数不传时使用模型默认行为。五、完整示例存储 语义检索 直接内存查询以下完整示例改编自仓库中的 gemini-embedding-example.py它比文档中的最小示例更进一步包含存储型 Agent与检索型 Agent两个角色并在流程结束后直接通过shared_memory.search_long_term验证语义检索效果import os from praisonaiagents import Agent, Task, AgentTeam # Ensure Google API key is set if not os.environ.get(GOOGLE_API_KEY): raise RuntimeError(Please set GOOGLE_API_KEY first) # Create agents for different tasks researcher Agent( nameResearch Agent, roleInformation Researcher, goalResearch and store important information about topics, backstoryExpert at analyzing and documenting information with semantic understanding, llmgpt-4o-mini # Using GPT for chat, Gemini for embeddings ) retriever Agent( nameRetrieval Agent, roleInformation Retriever, goalRetrieve relevant information from memory using semantic search, backstorySpecialist in finding and presenting stored information, llmgpt-4o-mini ) # Task 1: Store information with semantic meaning store_task Task( description Research and store the following information: 1. Gemini is Googles family of multimodal AI models 2. Gemini models support text, image, video, and audio understanding 3. The embedding models provide semantic representations of text 4. Gemini Ultra is the largest and most capable model 5. Gemini was announced in December 2023 Store each fact with its semantic meaning preserved. , expected_outputConfirmation that all facts have been stored in memory, agentresearcher ) # Task 2: Semantic retrieval test retrieve_task Task( description Using semantic search, find information about: 1. Googles AI capabilities 2. Multimodal understanding features 3. When was Googles latest AI announced Note: Use semantic similarity, not exact keyword matching. , expected_outputRetrieved information based on semantic meaning, agentretriever ) # Configure with Gemini embeddings (stable model sqlite vector store) agents AgentTeam( agents[researcher, retriever], tasks[store_task, retrieve_task], memory{ embedder: { provider: gemini, config: { model: text-embedding-004, } }, config: {provider: sqlite}, } ) # Alternative: using experimental model with task type # agents AgentTeam( # agents[researcher, retriever], # tasks[store_task, retrieve_task], # memoryTrue, # embedder{ # provider: gemini, # config: { # model: gemini-embedding-exp-03-07, # task_type: RETRIEVAL_DOCUMENT # } # } # ) # Execute the workflow result agents.start() # Direct memory search with Gemini embeddings if agents.shared_memory: queries [ What are Googles latest AI innovations?, Explain multimodal AI capabilities, Large language model features ] for query in queries: print(f\nSearching for: {query}) results agents.shared_memory.search_long_term(query, limit3) if results: print(fFound {len(results)} semantically similar results:) for i, result in enumerate(results, 1): print(f\n{i}. Relevance Score: {result.get(score, 0):.3f}) print(f Content: {result.get(text, )[:150]}...)示例中的几个关键点LLM 与 Embedding 解耦对话/推理使用gpt-4o-mini向量化使用 Gemini二者互不干扰这正是 embedder 可插拔设计的价值所在。两种写法等价memory{embedder: {...}, config: {...}}的嵌套字典写法与顶层memoryTrue, embedder{...}写法最终都会汇入同一套记忆配置解析流程见 agents.py。语义检索验证查询词如 What are Googles latest AI innovations?与原文Gemini was announced in December 2023没有直接关键词重合却能通过向量相似度命中直观展示了语义理解能力。检索结果附带score相关性评分便于按阈值过滤。六、与 Mem0 组合embedder 配置透传当使用 Mem0 作为记忆 Provider 时embedder 配置被透传到 Mem0 内部。有两种等价写法写法一全局 embedder 参数agents PraisonAIAgents( agents[...], tasks[...], memoryTrue, embedder{ provider: gemini, config: { model: text-embedding-004 } } )写法二嵌套在 memory_config 中Mem0 场景memory_config { provider: mem0, config: { api_key: your-mem0-key, embedder: { provider: gemini, config: { model: text-embedding-004 } } } }在 memory.py 的配置结构注释中可以看到config块除api_key、org_id、project_id等 Mem0 自有字段外还支持llm、embedder、vector_store、graph_store等扩展配置说明 embedder 只是整个记忆配置体系的一个组成部分。从 factories.py 的实现看适配器统一通过config.get(embedder) or {}读取配置未配置时按空字典处理并回退默认模型。七、向后兼容性Gemini Embedding 的接入在不破坏既有使用方式的前提下完成不传 embedder 配置自动使用默认 OpenAItext-embedding-3-small行为与历史版本完全一致既有配置兼容已有的 memory 配置无需任何修改即可继续运行多 Provider 支持由于底层走 LiteLLM理论上任何 LiteLLM 支持的嵌入模型Cohere、Voyage、Mistral、Jina、Ollama 本地模型等都可以用同样的embedder结构接入。从 dimensions.py 维护的模型维度表可以印证这一点表中不仅包含 OpenAI 系列还收录了 Cohere、Voyage、Mistral、Jina 以及nomic-embed-text、bge-m3等本地模型并注明这些本地模型曾默默使用默认维度 1536如今会按实际维度为向量存储正确分配大小。八、向量维度与存储一致性易踩坑点不同 Embedding 模型输出的向量维度不同OpenAItext-embedding-3-small为 1536 维而 Geminitext-embedding-004等其他模型维度各异。PraisonAI 在 dimensions.py 中通过get_dimensions(model_name)按模型名查表确定维度先精确匹配大小写不敏感再剥离 LiteLLM 风格的前缀如ollama/与版本标签如:v1.5后重试匹配最后按最长键优先做包含匹配避免voyage-3-lite被voyage-3前缀误命中未知模型回退到默认维度DEFAULT_DIMENSION 1536。正因为维度随模型变化切换 Embedding 模型后必须清空向量数据库否则旧向量与新向量的维度不匹配会导致检索失败或结果异常。这是文档 Troubleshooting 中明确强调的注意事项也是从 OpenAI 迁移到 Gemini 时最常见的坑。九、常见问题排查Troubleshooting症状排查方向API Key 错误确认GOOGLE_API_KEY已正确导出到环境变量Model Not Found核对模型名拼写确认使用的是上述受支持模型标识LiteLLM Error确认litellm已安装且版本较新随praisonaiagents自带可通过pip install -U litellm升级Embedding Size Mismatch切换模型后向量维度改变需清空向量数据库后重建索引十、延伸阅读完整可运行示例gemini-embedding-example.py记忆系统实现embedder 解析与默认值memory.py多 Agent 记忆配置解析embedder 提取与注入agents.py向量维度查找表单一定义来源dimensions.py记忆配置结构总览含 Mem0 / MongoDB / 图记忆 / vector_store 等字段memory.py 配置注释同目录下的记忆进阶示例advanced-memory-search-optimization.py、graph-memory-agent.py关于 Gemini 官方 Embedding API 与 LiteLLM 支持的完整模型清单请以 Google AI 官方文档与 LiteLLM 文档为准本文聚焦 PraisonAI 侧的配置与集成方式。【免费下载链接】PraisonAIPraisonAI — Hire a 24/7 AI Workforce. Stop writing boilerplate and start shipping autonomous self-improving agents that research, plan, code, and execute tasks. Deployed in 5 lines of code with built-in memory, RAG, and support for 100 LLMs.项目地址: https://gitcode.com/GitHub_Trending/pr/PraisonAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考