🧠 Motorhead（已弃用）

该项目已不再提供支持。

Motorhead 是一个用于大语言模型的记忆与信息检索服务器。

为什么使用 Motorhead？

在使用大语言模型构建聊天应用时，记忆管理往往需要从头开发。Motorhead 是一个专门为此设计的服务器，它提供了三个简单的 API：

• GET /sessions/:id/memory 返回最多 MAX_WINDOW_SIZE 条消息。

{
    "messages": [
        {
            "role": "AI",
            "content": "电子音乐和萨尔萨舞是两种截然不同的音乐类型，人们跳这两种舞的方式也大不相同。"
        },
        {
            "role": "Human",
            "content": "那它和萨尔萨舞相比如何呢？"
        },
        {
            "role": "AI",
            "content": "电子音乐是一个涵盖多种风格的广泛流派，因此并没有一种‘正确’的跳舞方式。"
        },
        {
            "role": "Human",
            "content": "那电子音乐该怎么跳呢？"
        },
        {
            "role": "AI",
            "content": "哥伦比亚拥有充满活力的电子音乐场景，许多才华横溢的DJ和制作人已经获得了国际认可。"
        },
        {
            "role": "Human",
            "content": "哥伦比亚有哪些著名的DJ呢？"
        },
        {
            "role": "AI",
            "content": "Baum俱乐部于2014年开业，很快就成为波哥大最受欢迎的电子音乐俱乐部之一。"
        }
    ],
    "context": "本次对话涵盖了波哥大电子音乐俱乐部、该市热门旅游景点以及哥伦比亚的基本情况等内容。AI提到了诸如Baum和Video Club等知名电子音乐俱乐部，还有在波哥大举办的电子音乐节。此外，AI还推荐了拉坎德拉里亚区、蒙塞拉特山和锡帕基拉盐教堂等旅游景点，并介绍了哥伦比亚多元的文化、地貌及野生动物等信息。",
    "tokens": 744 // 用于增量摘要的token数量
}

• POST /sessions/:id/memory - 向 Motorhead 发送消息数组以进行存储。

curl --location 'localhost:8080/sessions/${SESSION_ID}/memory' \
--header 'Content-Type: application/json' \
--data '{
    "messages": [{ "role": "Human", "content": "ping" }, { "role": "AI", "content": "pong" }]
}'

存储消息时可以使用现有的或新的 SESSION_ID，如果会话尚不存在，则会自动创建。

可选地，如果需要从其他数据存储加载上下文，也可以一并发送 context。

• DELETE /sessions/:id/memory - 删除该会话的消息列表。

为便于大语言模型跟踪对话，设置了最大窗口大小。一旦达到此限制，Motorhead 将处理其中的一半消息并生成摘要。随着消息数量的增加，后续的摘要将以增量方式进行更新。

• POST /sessions/:id/retrieval - 使用向量相似性搜索（VSS）按文本查询进行检索。

curl --location 'localhost:8080/sessions/${SESSION_ID}/retrieval' \
--header 'Content-Type: application/json' \
--data '{
    "text": "将军们如黑弥撒中的女巫般集结成群"
}'

搜索会根据提供的会话ID自动进行分段（过滤）。

配置

• MOTORHEAD_MAX_WINDOW_SIZE（默认：12）- 服务器返回的最大消息数。当达到此数量时，系统会触发任务将其减半。
• MOTORHEAD_LONG_TERM_MEMORY（默认：false）- 启用基于 Redisearch VSS 的长期记忆功能。
• MOTORHEAD_MODEL（默认：gpt-3.5-turbo）- 用于执行增量摘要的大语言模型。请使用 gpt-3.5-turbo 或 gpt-4，否则可能会出现异常情况。
• PORT（默认：8000）- Motorhead 服务器端口。
• OPENAI_API_KEY - 您的 OpenAI API 密钥，用于连接 OpenAI。
• REDIS_URL（必填）- 连接 Redis 的 URL。
• OPENAI_API_BASE（默认：https://api.openai.com/v1）- OpenAI API 的基础 URL。

Azure 部署

Azure 部署还需要以下环境变量：

• AZURE_DEPLOYMENT_ID
• AZURE_DEPLOYMENT_ID_ADA
• AZURE_API_BASE
• AZURE_API_KEY

如何运行

使用 docker-compose：

docker-compose build && docker-compose up

或者您可以直接使用镜像 docker pull ghcr.io/getmetal/motorhead:latest：

docker run --name motorhead -p 8080:8080 -e PORT=8080 -e REDIS_URL='redis://redis:6379' -d ghcr.io/getmetal/motorhead:latest

示例

• Chat JS 示例
• Chat JS 原生示例
• Chat JS 原生托管示例
• Chat Python 示例

Motorhead 快速上手指南

⚠️ 重要提示：本项目（Motorhead）已标记为 DEPRECATED（弃用），官方不再提供维护支持。本文档仅作为历史参考或学习 LLM 记忆管理机制之用，生产环境请谨慎评估风险。

Motorhead 是一个专为大语言模型（LLM）设计的记忆与信息检索服务器，旨在简化聊天应用中的上下文记忆管理。

环境准备

在部署前，请确保满足以下系统要求和前置依赖：

• 操作系统：Linux, macOS 或 Windows (需安装 Docker)
• 核心依赖：
  • Docker & Docker Compose：推荐使用的运行环境。
  • Redis：Motorhead 必须连接 Redis 实例来存储数据。
  • OpenAI API Key：用于执行增量摘要总结（若使用 Azure 部署则需 Azure 相关凭证）。
• 网络要求：能够访问 ghcr.io (GitHub Container Registry) 拉取镜像，以及访问 OpenAI API 服务。

安装步骤

推荐使用 Docker 进行快速部署。你可以选择 docker-compose 或直接使用 docker run 命令。

方式一：使用 Docker Compose（推荐）

如果你克隆了源代码仓库，可以直接在项目根目录运行：

docker-compose build && docker-compose up

方式二：直接使用 Docker 命令

如果你只想快速启动一个实例，可以使用以下命令。请确保将 <YOUR_REDIS_URL> 替换为你实际的 Redis 连接地址，并将 <YOUR_OPENAI_API_KEY> 替换为你的密钥。

docker run --name motorhead \
  -p 8080:8080 \
  -e PORT=8080 \
  -e REDIS_URL='redis://<YOUR_REDIS_URL>:6379' \
  -e OPENAI_API_KEY='<YOUR_OPENAI_API_KEY>' \
  -d ghcr.io/getmetal/motorhead:latest

关键环境变量配置说明：

变量名	默认值/必填	说明
REDIS_URL	必填	Redis 连接地址 (例如: redis://localhost:6379)
OPENAI_API_KEY	必填	你的 OpenAI API 密钥
PORT	8000	服务监听端口
MOTORHEAD_MAX_WINDOW_SIZE	12	LLM 保留的最大消息数量，超出后将触发摘要
MOTORHEAD_MODEL	gpt-3.5-turbo	用于摘要的模型 (支持 gpt-3.5-turbo 或 gpt-4)
MOTORHEAD_LONG_TERM_MEMORY	false	是否启用基于 Redisearch VSS 的长期记忆

注：若使用 Azure OpenAI 部署，还需额外配置 AZURE_DEPLOYMENT_ID, AZURE_API_BASE 等变量。

基本使用

启动成功后，Motorhead 将在指定端口（默认 8080）提供 HTTP API。以下是三个核心接口的使用方法。

1. 存储对话记忆 (POST)

向特定会话 ID 发送消息数组。如果会话 ID 不存在，系统将自动创建新会话。

curl --location 'localhost:8080/sessions/test-session-001/memory' \
--header 'Content-Type: application/json' \
--data '{
    "messages": [
        { "role": "Human", "content": "你好，介绍一下电子音乐。" }, 
        { "role": "AI", "content": "电子音乐是一种主要使用电子乐器和电子技术制作的音乐流派。" }
    ]
}'

2. 获取当前上下文 (GET)

获取指定会话的记忆内容。系统会自动返回最近 MAX_WINDOW_SIZE 条消息，并包含由 AI 生成的上下文摘要（Context）和 Token 统计。

curl --location 'localhost:8080/sessions/test-session-001/memory'

返回示例：

{
    "messages": [
        { "role": "Human", "content": "你好，介绍一下电子音乐。" },
        { "role": "AI", "content": "电子音乐是一种主要使用电子乐器和电子技术制作的音乐流派。" }
    ],
    "context": "用户询问了关于电子音乐的基本定义，AI 进行了简要介绍。",
    "tokens": 45
}

3. 语义检索 (POST) - 需开启长期记忆

如果启用了 MOTORHEAD_LONG_TERM_MEMORY，可以通过文本查询在该会话的历史记录中进行向量搜索。

curl --location 'localhost:8080/sessions/test-session-001/retrieval' \
--header 'Content-Type: application/json' \
--data '{
    "text": "之前提到的音乐流派有什么特点？"
}'

4. 清除会话记忆 (DELETE)

删除指定会话的所有消息记录。

curl --request DELETE 'localhost:8080/sessions/test-session-001/memory'

---

更多代码示例（JavaScript/Python）可参考原仓库 examples/ 目录。