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

Letta（前身为 MemGPT）是一个让 AI 代理具备长期记忆的开源框架。
如果你已经装好 Docker 和本地模型服务，下一步的核心操作只有两步：用 Docker 启动 Letta 服务，再修改配置让它指向你的模型提供方。
下面按顺序说明。

开始前确认三件事

Letta 本身不负责运行大模型，它需要连接一个模型提供方。
因此动手之前，先确认以下条件：

• Docker 与 Docker Compose：用 docker --version 和 docker compose version 检查，两条命令都能输出版本号即可。
• 模型提供方可用：本地 Ollama 用 curl http://127.0.0.1:11434/api/tags 验证，能返回模型列表说明服务正常；也可以准备 OpenAI 兼容接口的地址和 API Key。
• 端口规划：Letta 默认使用 8283 端口，如果该端口已被占用，启动前要改映射端口。

用 Docker 启动 Letta 服务

先创建一个工作目录，用于存放配置和持久化数据：

mkdir -p ~/letta && cd ~/letta

使用官方镜像启动容器，把配置目录挂载出来：

docker run -d \
  --name letta \
  -p 8283:8283 \
  -v ~/letta/data:/app/letta/data \
  -v ~/letta/config:/app/letta/config \
  letta/letta:latest

启动后查看日志，确认服务是否真正就绪：

docker logs -f letta

当日志出现服务监听 8283 端口的提示后，用下面的命令验证接口是否可访问：

curl http://127.0.0.1:8283/v1/health

如果返回健康状态，说明 Letta 服务本身已经跑起来了。
注意这一步只验证服务，不代表模型可用，下一步还要配置模型提供方。

把模型提供方指向 Ollama 或兼容接口

Letta 的模型配置通常位于挂载出来的配置目录中。
在 ~/letta/config 下找到配置文件（常见为 config.yaml 或类似命名的文件），按你的提供方填写。

本地 Ollama 的写法示例：

model:
  provider: ollama
  base_url: http://host.docker.internal:11434
  model_name: qwen2.5:7b

这里的关键是 base_url：
容器内的 127.0.0.1 指向容器自己，
不是宿主机，
所以要用 host.docker.internal（Docker Desktop 环境）或宿主机局域网 IP（Linux 环境）。model_name 必须与 Ollama 中已拉取的模型名一致，
否则会报模型不存在。

如果使用 OpenAI 兼容接口，则改为：

model:
  provider: openai
  base_url: https://你的接口地址/v1
  api_key: 你的密钥
  model_name: 你的模型名

修改配置后重启容器使配置生效：

docker restart letta

重启后再看一次日志，确认没有配置解析错误或连接超时。

创建第一个带记忆的代理并验证

配置通过后，可以用接口创建一个代理来做最小验证。
先准备一个请求体文件 agent.json：

{
  "name": "test-agent",
  "model": "qwen2.5:7b",
  "persona": "你是一个简洁的助手"
}

然后调用创建接口：

curl -X POST http://127.0.0.1:8283/v1/agents \
  -H "Content-Type: application/json" \
  -d @agent.json

如果返回中包含代理 ID，说明创建成功。
接着向该代理发送一条消息，观察是否有正常回复：

curl -X POST http://127.0.0.1:8283/v1/agents/你的代理ID/messages \
  -H "Content-Type: application/json" \
  -d '{"message":"你好，请记住我的名字叫小林"}'

能收到回复即代表整条链路打通。
你还可以再发一条询问“我叫什么”，观察代理是否通过记忆模块保留信息。

常见连接问题与避坑

容器内连不上 Ollama：这是最常见的问题。
先进入容器测试 curl http://host.docker.internal:11434/api/tags，如果失败，改用宿主机局域网 IP，并确认 Ollama 监听在 0.0.0.0:11434 而不是仅 127.0.0.1。

端口冲突：如果启动时报 port is already allocated，把映射改为 -p 8284:8283，之后所有请求地址同步换成 8284。

模型名不一致：Ollama 中的模型名带版本标签，配置里少写标签会导致找不到模型，用 ollama list 核对完整名称。

修改配置不生效：确认修改的是挂载目录里的文件，而不是容器内部临时路径；
改完必须重启容器。

数据丢失风险：删除容器前确认 -v 挂载的目录已存在且包含数据，否则重建容器后代理和记忆会清空。

验证与后续使用

完成上述步骤后，建议按以下清单复查：

• curl http://127.0.0.1:8283/v1/health 返回正常；
• 日志中没有模型连接错误；
• 创建代理接口返回了代理 ID；
• 发送消息能收到模型回复；
• 再次提问时代理能引用之前对话中的信息。

如果以上都通过，Letta 已经可以正常使用。
后续可以继续在配置中调整记忆策略、增加工具或更换模型，每次改动后重启容器并复查日志即可。
遇到异常时，优先检查模型地址和模型名这两项，它们覆盖了大部分启动失败的情况。