企业官网建设流程全解析

LycheeMem 是一个面向 LLM Agent 的轻量级长期记忆框架，它通过.env文件统一管理所有配置项。本文带你逐项看懂.env里的关键参数：LLM 模型怎么选、Embedding 模型怎么选、工作记忆预算怎么调，并附上常见踩坑清单，帮助你一次性配好这个 Agent 记忆系统。

一、配置体系速览：一个 .env 管所有

LycheeMem 的所有配置都集中在项目根目录的.env文件中（模板见 .env.example），由 src/core/config.py 中的Settings类统一读取并映射到全局单例settings。有几个值得知道的机制：

• 加载优先级：.env中的值会覆盖系统环境变量（override=True），开发环境改.env即可生效；
• 存储无需外部数据库：语义记忆使用 SQLite + LanceDB，工作记忆默认写入 SQLite，开箱即用；
• 改动即生效：修改.env后重启lycheemem-cli（或python main.py）即可。

# 最小可用配置：LLM + Embedding + API Key LLM_MODEL=openai/gpt-4o-mini LLM_API_KEY=sk-... EMBEDDING_MODEL=openai/text-embedding-3-small EMBEDDING_DIM=1536

二、LLM 怎么选：litellm 统一格式provider/model

LycheeMem 通过 litellm 调用大模型，模型名遵循provider/model-name的统一格式，同一套配置可切换不同供应商：

选型建议：

• 🆓想省钱/跑得快：gpt-4o-mini这类小模型足够驱动记忆抽取和检索流程（框架内部 LLM 调用多为结构化抽取，任务不难）；
• 🌐内网代理：模型名保持 OpenAI 格式，把网关地址填进LLM_API_BASE即可；
• 🏠完全离线：用 Ollama 起一个本地模型，LLM_API_KEY随意填占位值。

相关参数在 src/core/config.py 中定义：LLM_TEMPERATURE（默认 0.7）、LLM_MAX_TOKENS（0 = 交给 provider 默认）、LLM_TOP_P（默认 0.8）。一般保持默认即可，只有微调回答风格时才需要动它们。

三、Embedding 怎么选：API、本地、共享服务三后端

Embedding 模型决定记忆向量化质量，是最影响检索效果的参数。LycheeMem 支持三种接入方式（见 src/embedder/ 目录下的实现）：

1. 云端 API（默认，最简单）

保持EMBEDDING_BACKEND=litellm，直接填模型名：

EMBEDDING_MODEL=openai/text-embedding-3-small EMBEDDING_DIM=1536 # 若用独立账号，可单独配置；不填则复用 LLM_API_KEY EMBEDDING_API_KEY= EMBEDDING_API_BASE=

2. 本地模型（离线 / 免 API 费用）

开启EMBEDDING_LOCAL=true后，EMBEDDING_MODEL填 HuggingFace 模型路径，由 SentenceTransformerEmbedder 在本地运行：

EMBEDDING_LOCAL=true EMBEDDING_MODEL=Qwen/Qwen3-Embedding-0.6B # 或 BAAI/bge-m3、all-MiniLM-L6-v2 EMBEDDING_DEVICE=auto # auto / cpu / cuda / mps EMBEDDING_DIM=1024 # 支持 Matryoshka 的模型可截断维度

⚠️ 使用本地模型需先安装额外依赖：pip install "lycheemem[local-embed]"（见 pyproject.toml）。

3. 共享 HTTP 服务（多进程复用一套模型）

多个 LycheeMem 实例共用一个远程 embedding 服务时，用EMBEDDING_BACKEND=http并指向服务地址，模板中附有embedding_server.py的启动示例（.env.example）。

关键技巧——EMBEDDING_DIM自动探测：填EMBEDDING_DIM=0时，框架会在启动时真实调用一次接口探测向量维度（本地模型则直接读取模型属性，见 src/core/factory.py）。拿不准维度时填 0 最稳妥，避免维度不匹配导致向量库报错。

四、.env 里的其他关键参数清单

除了模型配置，.env.example 还包含以下常调参数：

🔢 工作记忆预算（影响长对话行为）

上下文较小的模型（如 8K 窗口）应调低WM_MAX_TOKENS，否则压缩触发前上下文就已溢出。

📦 存储路径（一般保持默认）

会话库、技能库、语义记忆库和向量索引默认都在data/下，如SQLITE_DB_PATH=data/sessions.db、COMPACT_MEMORY_DB_PATH=data/compact_memory.db、SKILL_DB_PATH=data/skill_store.db。需要持久化或备份时，改这里即可。

⚖️ 检索增强（可选开关）

👁️ 视觉记忆 / VLM（可选）

VLM_MODEL留空时会自动回退复用主 LLM（见 src/core/factory.py）。若主模型不支持图片识别，建议单独配置视觉模型，例如VLM_MODEL=openai/qwen-vl-max，配合VLM_API_KEY/VLM_API_BASE。

五、常见踩坑清单 🐛

1. EMBEDDING_DIM与模型实际维度不符→ 向量写入/检索报错。对策：填0让框架自动探测，或查官方文档确认维度；
2. 忘了填LLM_API_KEY→ 所有 LLM 环节（记忆抽取、相关性评分、最终回答）全部失败，启动日志会有明确报错；
3. 换了 Embedding 模型但没清旧数据→ 新旧向量维度/空间不一致，建议删除data/下对应目录重建；
4. VLM 没配置却测试图片记忆→ 实际调用的是主 LLM，可能不支持图片，日志中会打印 "未配置 VLM 模型，将复用主 LLM" 的警告。

六、配完怎么验证 ✅

启动服务并做一次端到端验证：

lycheemem-cli # 或 python main.py python examples/api_pipeline_demo.py --multi-turn # 三轮对话 + 自动固化

服务运行在http://localhost:8000，访问/docs可交互式调用 API；用固定--session-id多次运行 demo 还能观察记忆跨会话积累效果。如果对话回答能正确引用你之前说过的偏好与事实，说明 LLM 与 Embedding 配置都已生效。

小结

核心思路一句话：LLM 负责"会说话"，Embedding 负责"找得准"，.env里这两组参数决定 LycheeMem 长期记忆的上限，其余参数按需微调即可。完整模板参考 .env.example，更多架构细节见 README_zh.md。