技术栈与环境要求
技术栈与环境要求
本节摘要:动手前的第一步是凑齐环境。TencentDB Agent Memory 是一套由三个服务组成的系统,跑起来需要四类前置条件:运行时(Node 与 Docker)、LLM 凭证(而且要两组)、若干端口、以及一个用来接入的 Coding Agent。本节帮你逐项核对清单,重点说清「为什么要两组 LLM 凭证」这个最容易踩的坑——一组给记忆系统做抽取用,一组给代理层做转发用,两者职责不同、模型可以不同。读完本节你会拥有一份明确的「开跑前检查表」,避免跑到一半才发现少配了参数。
一、四类前置条件总览
把整套系统跑起来,需要的东西可以归成四类:
| 类别 | 具体内容 | 用途 |
|---|---|---|
| 运行时 | Node(22.16 及以上)、Docker | 跑服务与容器化部署 |
| LLM 凭证 | 两组模型密钥与配置 | 一组给记忆抽取,一组给请求转发 |
| 端口 | 8096、8125、8420、8421 等 | 代理、控制台、核心、知识各占端口 |
| 接入对象 | 一个 Coding Agent(如 Claude Code) | 用来验证记忆是否生效 |
关键概念:前三类是「系统要跑起来」的硬条件,第四类是「跑起来后要验证」的软条件。初学者常忽略第四类,结果系统跑起来了却不知道怎么确认记忆生效——本节末尾与下一节会补上。
二、为什么需要两组 LLM 凭证
这是环境准备里最反直觉、也最容易踩的坑。先看这两组凭证各干什么:
┌─────────────────────────────────────────────────────────┐ │ memory 组凭证 │ │ 用途:记忆核心服务内部做「抽取」——把对话提炼成记忆 │ │ 特点:量大、异步、对推理质量敏感(影响记忆好不好) │ │ 建议模型:推理强的模型(抽取质量直接决定记忆质量) │ └─────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────┐ │ proxy 组凭证 │ │ 用途:代理层把请求「转发」给真正的 LLM 回答用户 │ │ 特点:就是你日常用的那个模型(直接决定回答质量) │ │ 建议模型:你本来就想用的模型(如 Claude、GPT 等) │ └─────────────────────────────────────────────────────────┘
为什么要分两组?因为它们职责不同、模型可以不同、成本也可以分开核算。最典型的搭配是:memory 组用性价比高的模型做抽取(因为抽取量大),proxy 组用你心仪的强模型做回答(因为直接面向用户)。
⚠️ 注意:两组凭证填反了或者只填了一组,会导致「抽取不工作」或「转发不工作」——这是初学者最高频的故障,排查时先查这里。
三、端口规划与占用检查
每个服务占用一个端口,部署前确认这些端口没被占用:
| 服务 | 默认端口 | 你会怎么用到它 |
|---|---|---|
| 代理层 | 8096 | Coding Agent 的 baseURL 指向这里 |
| 记忆中枢(控制台) | 8125 | 浏览器打开这个端口看面板 |
| 记忆核心服务 | 8420 | 内部 Gateway,一般不直接访问 |
| 知识服务 | 8421 / 8424 | Wiki 与 CodeGraph 引擎 |
用一条命令快速检查端口是否空闲(概念示例):
# 检查某个端口是否被占用(以 8096 为例) # 占用则需先释放,或调整部署脚本里的端口映射 netstat -ano | findstr :8096 # Windows lsof -i :8096 # Linux / macOS
四、最小检查表与常见坑
把上面的内容压成一份开跑前的检查表:
开跑前检查表 [ ] Node 版本 ≥ 22.16 (node -v) [ ] Docker 可用 (docker info) [ ] memory 组 LLM 凭证已备齐 (密钥 + 模型名 + 接口地址) [ ] proxy 组 LLM 凭证已备齐 (可与 memory 组不同) [ ] 端口 8096/8125/8420/8421 空闲 [ ] 有一个可接入的 Coding Agent (如 Claude Code 已安装)
💡 技巧:如果你只是想先体验、不想凑两组凭证,可以从「只跑记忆核心服务 + 控制台」的最小形态开始(单凭证),把代理层接入留到后面。但完整体验「Agent 记住你」需要代理层或 SDK,这二者都依赖两组凭证。
一个常见的认知坑是:把这套系统当成「单一进程」来理解。它其实是三个分工不同的服务协同工作——理解了这一点,环境准备里「为什么有三个端口、两组凭证」就都顺理成章了。下一节我们就把这三个服务一起拉起来。
本节要点回顾
- 四类前置:运行时(Node/Docker)、两组 LLM 凭证、若干端口、一个接入用的 Coding Agent。
- 两组凭证的分工:memory 组给抽取用(量大、可性价比优先),proxy 组给转发用(面向用户、要强模型)。
- 端口规划:代理 8096、控制台 8125、核心 8420、知识 8421/8424,部署前逐一检查空闲。
- 最小检查表:把六项核对一遍,能避免 80% 的「跑到一半才发现少东西」。
- 认知前提:这是三个协同的服务,不是单一进程——这是理解后续所有架构的起点。
准备好了环境,下一节我们就用一条 start-all.sh 把三件套一次性拉起来,并确认它们都健康运行。