Zep 使用教程：为 AI 助手接入长期记忆的配置方法

知识分享

2026-10-30 18:00

27 阅读

Zep 是一个专门给 AI 助手提供长期记忆的服务。
它把对话历史压缩成可检索的记忆片段，让助手在后续对话中记住用户之前说过的话。
这篇教程面向第一次接触 Zep 的读者，从本地部署讲到客户端接入和效果验证，每一步都给出可执行的命令和检查方式。

先确认你的使用场景和前置条件

Zep 适合需要跨会话记忆的 AI 应用，比如客服机器人、个人助理或长期跟进任务的代理。
如果你只是做一次性问答，不涉及多轮记忆，不必引入 Zep。

部署前需要准备：

一台能运行 Docker 的 Linux 服务器或本地开发机，建议 2 核 4G 以上内存
已安装 Docker 和 Docker Compose，用 docker --version 确认
一个可用的 OpenAI API Key 或兼容的模型服务地址，Zep 在生成记忆摘要时会调用模型
客户端项目能读取环境变量，Python、Node.js 均可

用 Docker 启动 Zep 服务

Zep 官方提供 Docker 镜像，本地部署最简单的方式是用 Compose 启动服务和依赖的数据库。
以下配置片段可作为起点，实际镜像标签以你拉取到的稳定版本为准：

services:
  zep:
    image: ghcr.io/getzep/zep:latest
    ports:
      - "8000:8000"
    environment:
      - ZEP_STORE_TYPE=postgres
      - ZEP_DB_HOST=postgres
      - ZEP_DB_NAME=zep
      - ZEP_DB_USER=zep
      - ZEP_DB_PASSWORD=zep_password
      - OPENAI_API_KEY=你的模型APIKey
    depends_on:
      - postgres
  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=zep
      - POSTGRES_USER=zep
      - POSTGRES_PASSWORD=zep_password
    volumes:
      - zep_pgdata:/var/lib/postgresql/data
volumes:
  zep_pgdata:

把文件保存为 docker-compose.yml，在同目录执行 docker compose up -d。
启动后用 docker compose ps 查看容器状态，两个服务都应为 running。
再访问 http://服务器IP:8000/healthz，返回正常状态码说明服务已就绪。

如果容器反复重启，先看日志 docker compose logs zep，常见原因是数据库连接参数不一致或模型 API Key 无效。

获取 API Key 并接入客户端

服务启动后，需要在 Zep 中创建项目并拿到 API Key。
本地部署版本通常在服务启动日志中会输出初始密钥，或在管理接口中生成。
拿到密钥后，在客户端项目中配置两个环境变量：

export ZEP_API_URL="http://服务器IP:8000"
export ZEP_API_KEY="你的Zep密钥"

Python 项目可以用官方 SDK 初始化客户端：

from zep_cloud.client import Zep

client = Zep(
    api_key=os.environ["ZEP_API_KEY"],
    base_url=os.environ["ZEP_API_URL"],
)

注意 base_url 要填完整的协议和端口，不要只写 IP。
如果客户端和服务在同一台机器，可以用 127.0.0.1；
跨机器访问时，防火墙需要放行 8000 端口。

写入对话并验证记忆是否生效

接入后先创建一个会话，写入几条消息，再调用记忆检索接口检查返回内容：

session_id = "demo-session-001"
client.memory.add_session(session_id=session_id, user_id="user-001")
client.memory.add(
    session_id=session_id,
    messages=[{"role": "user", "content": "我下周要去杭州出差"}],
)
result = client.memory.get(session_id=session_id)
print(result)

预期结果是检索接口返回与“杭州出差”相关的记忆摘要。
如果返回为空，按顺序检查：消息是否写入成功、模型 API Key 是否有效、Zep 服务日志是否有摘要生成失败记录。

验证通过后，就可以在每次对话前调用记忆检索，把相关片段拼接到提示词中，让助手带上长期记忆。

容易踩坑的几个地方

端口和地址写错：base_url 必须是 http://IP:8000 形式，漏掉协议或端口会直接连接失败。
数据库密码不一致：Compose 里 Zep 和 Postgres 的密码必须完全相同，否则服务起不来。
忘记放行防火墙：跨机器访问时，除了容器端口映射，还要检查服务器安全组或 ufw 规则。
模型 Key 无效：Zep 生成记忆摘要依赖模型服务，Key 失效时写入可能成功但检索为空。
把一次性问答也接入记忆：不是所有场景都需要长期记忆，无关对话写入反而增加检索噪声。

怎么判断配置已经完成

满足以下三点即可认为 Zep 接入成功：服务健康检查返回正常、客户端能创建会话并写入消息、检索接口能返回与写入内容相关的记忆片段。
之后可以逐步调整记忆保留策略和检索条数，观察助手回答是否更连贯。
如果后续换服务器或改端口，记得同步更新客户端的 ZEP_API_URL，避免连接超时。

Letta 使用教程：Docker 部署与本地模型接入

Weaviate 本地 Docker 部署与向量检索入门