使用 OpenSearch 存储

opensearch 后端使用 OpenSearch 作为向量存储。记忆文本先经 embedding 模型向量化，再写入 OpenSearch，并按用户隔离索引（实际索引名为 {index}_{user_id}），检索时按相似度召回。它是 LongTermMemory 的默认后端。

何时使用

已有 OpenSearch 集群，希望自建向量检索；
需要持久化、可跨进程与多实例共享，并对索引与检索有完全掌控。

依赖

pip install "veadk-python[extensions]"

使用示例

运行前准备可达的 OpenSearch 集群、可创建和访问索引的账号、有效 CA 证书，并设置下文的连接与 embedding 环境变量。向量维度必须与已有索引一致；更换维度需要新建索引并重新写入记忆

from veadk import Agent
from veadk.memory.long_term_memory import LongTermMemory

# index 需为小写，仅含 a-z0-9_-. 且不以 _ 或 - 开头
ltm = LongTermMemory(backend="opensearch", index="ltm_demo")

agent = Agent(
    name="demo",
    instruction="回答用户问题，必要时用 `load_memory` 工具检索过往对话。",
    long_term_memory=ltm,
)

也可以通过 backend_config 显式传入连接与 embedding 配置：

import os

from veadk.memory.long_term_memory import LongTermMemory
from veadk.configs.database_configs import OpensearchConfig

ltm = LongTermMemory(
    backend="opensearch",
    index="ltm_demo",
    backend_config={
        "index": "ltm_demo",
        "opensearch_config": OpensearchConfig(
            host="localhost",
            port=9200,
            username="admin",
            password=os.environ["DATABASE_OPENSEARCH_PASSWORD"],
            use_ssl=True,
            cert_path="/path/to/ca.pem",
        ),
    },
)

参数

LongTermMemory 参数

参数	类型	默认值	说明
`backend`	`str \| BaseLongTermMemoryBackend`	`"opensearch"`	本页使用 `opensearch`；也可传入已配置的后端实例
`backend_config`	`dict`	`{}`	后端配置；显式后端实例优先于此配置
`index`	`str`	`""`	未提供 backend_config 时依次使用 index、app_name、default_app；提供配置字典时应明确指定非空索引
`app_name`	`str`	`""`	index 的回退值；实际用户来自保存的 Session 或检索参数
`top_k`	`int`	`5`	检索片段数量；配置为正整数
`user_id`	`str`	`""`	已废弃；不用于运行时用户隔离

构造参数

backend_config 支持以下配置项：

参数	类型	默认值	说明
`index`	`str`	无默认，由 `LongTermMemory` 传入	记忆索引名，须符合 OpenSearch 命名规则
`opensearch_config`	`OpensearchConfig`	自动从 `DATABASE_OPENSEARCH_*` 环境变量读取	OpenSearch 连接配置
`embedding_config`	`EmbeddingModelConfig`	自动从 `MODEL_EMBEDDING_*` 环境变量读取	embedding 模型配置

OpenSearch 连接配置

opensearch_config 为 OpensearchConfig，环境变量前缀 DATABASE_OPENSEARCH_：

配置项	环境变量	类型	默认值	说明
`host`	`DATABASE_OPENSEARCH_HOST`	`str`	`""`	OpenSearch 主机地址
`port`	`DATABASE_OPENSEARCH_PORT`	`int`	`9200`	端口
`use_ssl`	`DATABASE_OPENSEARCH_USE_SSL`	`bool`	`true`	是否启用 SSL
`username`	`DATABASE_OPENSEARCH_USERNAME`	`str`	`""`	用户名
`password`	`DATABASE_OPENSEARCH_PASSWORD`	`str`	`""`	密码
`cert_path`	`DATABASE_OPENSEARCH_CERT_PATH`	`str`	`""`	CA 证书路径。为空时不校验证书，存在安全风险并会告警
`secret_token`	`DATABASE_OPENSEARCH_SECRET_TOKEN`	`str`	`""`	当前 OpenSearch 长期记忆连接不使用此字段

embedding 配置

embedding_config 为 EmbeddingModelConfig，环境变量前缀 MODEL_EMBEDDING_：

配置项	环境变量	类型	默认值	说明
`name`	`MODEL_EMBEDDING_NAME`	`str`	`doubao-embedding-vision-250615`	embedding 模型名
`dim`	`MODEL_EMBEDDING_DIM`	`int`	`2048`	embedding 向量维度，用于创建索引的向量字段
`api_base`	`MODEL_EMBEDDING_API_BASE`	`str`	`https://ark.cn-beijing.volces.com/api/v3/`	embedding 服务的 API 地址
`api_key`	`MODEL_EMBEDDING_API_KEY`	`str`	依次回退到 `MODEL_AGENT_API_KEY` 或自动获取的 Ark 令牌	访问 embedding 服务的密钥

环境变量配置

# OpenSearch 连接
export DATABASE_OPENSEARCH_HOST="localhost"
export DATABASE_OPENSEARCH_PORT=9200
export DATABASE_OPENSEARCH_USERNAME="admin"
export DATABASE_OPENSEARCH_PASSWORD="admin"
export DATABASE_OPENSEARCH_USE_SSL=true
export DATABASE_OPENSEARCH_CERT_PATH="/path/to/ca.pem"

# embedding 模型
export MODEL_EMBEDDING_NAME="doubao-embedding-vision-250615"
export MODEL_EMBEDDING_DIM=2048
export MODEL_EMBEDDING_API_KEY="your-ark-api-key"

index 必须符合 OpenSearch 命名规则：全小写，仅含 a-z0-9_-.，且不以 _ 或 - 开头，否则会报错。生产环境请配置 cert_path 以启用证书校验，避免安全风险。

验证写入和检索

配置本页依赖与凭证后运行此独立示例。它直接保存用户文本，再检索同一用户的记忆，不需要调用对话模型

import asyncio

from google.adk.events import Event
from google.adk.sessions import Session
from google.genai import types
from veadk.memory.long_term_memory import LongTermMemory

async def main():
    memory = LongTermMemory(backend="opensearch", index="ltm_demo")
    session = Session(
        id="memory_check", app_name="ltm_demo", user_id="user_42",
        events=[Event(author="user", content=types.Content(
            role="user", parts=[types.Part(text="My preferred language is Chinese")]
        ))],
    )
    await memory.add_session_to_memory(session)
    result = await memory.search_memory(
        app_name="ltm_demo", user_id="user_42", query="preferred language"
    )
    for entry in result.memories:
        print(entry.content)

asyncio.run(main())

结果应包含所保存的语言偏好。托管服务可能异步完成记忆提取，写入返回不保证立刻可检索；空结果也可能来自权限、网络或服务失败，应结合错误日志与服务端记录判断。此方法不返回保存成功的布尔值最终索引名包含 user_id，因此用户标识也必须符合索引字符要求。相同 index 与 user_id 会访问相同记忆，search_memory(app_name=...) 不会额外隔离索引

概览

快速开始

核心组件

可观测

扩展

前端

安全

部署

何时使用

依赖

使用示例

参数

LongTermMemory 参数

构造参数

OpenSearch 连接配置

embedding 配置

环境变量配置

验证写入和检索

​何时使用

​依赖

​使用示例

​参数

​LongTermMemory 参数

​构造参数

​OpenSearch 连接配置

​embedding 配置

​环境变量配置

​验证写入和检索

何时使用

依赖

使用示例

参数

LongTermMemory 参数

构造参数

OpenSearch 连接配置

embedding 配置

环境变量配置

验证写入和检索