diff --git a/README.md b/README.md
index 09b3370..18de780 100644
--- a/README.md
+++ b/README.md
@@ -18,22 +18,75 @@
 
 ---
 
-## 快速开始
+## 本地部署（用户侧）
 
+### 1. 前置
+- Go 1.26、Node 22（前端构建用）、Docker（**可选**，用于 PostgreSQL + pgvector / 本地 embedding）。
+
+### 2. 配置 `.env`（复制 `.env.example`）
 ```bash
-# 前端（go:embed 需要构建产物，先 build）
-cd frontend/web && npm ci && npm run build && cd ../..
+# 认证
+JWT_SECRET=<≥32 字符随机串>
+ADMIN_USERNAME=admin
+ADMIN_PASSWORD=<你的密码>
 
-# 配置
-cp .env.example .env   # 至少配置 LLM_API_KEY / JWT_SECRET
+# LLM（LLM_PROVIDER 显式声明协议：openai / anthropic）
+LLM_PROVIDER=anthropic
+ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
+ANTHROPIC_API_KEY=<key>
+ANTHROPIC_MODEL=deepseek-chat
+# 或 OpenAI 兼容：LLM_PROVIDER=openai + LLM_BASE_URL/API_KEY/MODEL
 
-# 启动（单二进制）
-go run ./cmd/cyrene/   # 访问 http://localhost:8080
-
-# 或构建发布用单文件
-go build -ldflags="-s -w" -trimpath -o cyrene ./cmd/cyrene/
+# 数据库（可选增强：PG + pgvector 向量检索）
+DB_PG_URL=postgres://cyrene:cyrene_pass@localhost:5432/cyrene_ai?sslmode=disable
 ```
 
+### 3. 可选依赖（Docker；PG+pgvector 必需可加，embedding 可选）
+```bash
+docker compose -f docker-compose.dev.yml up -d          # PG + pgvector
+docker compose -f docker-compose.dev.yml --profile embedding up -d embedding   # 可选：本地 embedding(Ollama)
+# 若用 embedding：docker exec -it cyrene-embedding ollama pull <model>
+```
+
+### 4. 构建并启动（单二进制，go:embed 前端）
+```bash
+cd frontend/web && npm ci && npm run build && cd ../..   # 产 dist（含拷到 internal/webui/dist）
+go build -ldflags="-s -w" -trimpath -o cyrene ./cmd/cyrene/
+./cyrene       # 访问 http://localhost:8080（按 .env 的 PORT）
+```
+
+---
+
+## Embedding 模型推荐
+
+> 用于长记忆/知识库**语义向量检索**（默认不配 = 内置 n-gram 向量，dim=256，离线但质量一般）。
+> 配了 `EMBEDDING_API_URL/MODEL` 后走**真语义**。维度 = 模型 dim，与向量索引一致的；**切换模型会改维度，需清空旧向量数据**。
+
+| 模型 | dim | 大小 | 推理内存 | 质量 | 建议 |
+|------|-----|------|---------|------|------|
+| **bge-m3** | 1024 | ~2.2GB(fp16) / ~1.2GB(Q4) | ~2–3GB | ★★★★★（跨语言最强） | ⭐ **首选**（内存充足/GPU 时） |
+| **bge-small-zh-v1.5** | 512 | ~30–100MB | ~几十MB | ★★★★ | ✅ **当前开发环境采用**（内存受限，轻且稳） |
+| nomic-embed-text | 768 | ~270MB | ~400–600MB | ★★★☆ | 可 |
+| mxbai-embed-large | 768 | ~350–670MB | ~0.8–1GB | ★★★★ | 可 |
+
+> **说明**：bge-m3 质量最好、跨语言首推；但本开发机**可用内存仅 ~2.9GB（无 GPU、swap 已用 12G）**，跑 bge-m3 会明显 swap、偏慢。故**开发环境用 `bge-small-zh-v1.5`**（轻、快、稳，中文/多语言够用）——质量换性能，生产/有 GPU 再上 bge-m3。
+
+`.env` 示例（本地 Ollama）：
+```bash
+EMBEDDING_API_URL=http://localhost:11434/v1
+EMBEDDING_MODEL=bge-small-zh-v1.5
+# EMBEDDING_API_KEY=
+```
+
+**llama.cpp 能替代 Ollama 吗？** —— 能。llama.cpp 的 `llama-server`（服务模式）同样暴露 **OpenAI 兼容 `/v1/embeddings`**，用单二进制 + 一个 GGUF 嵌入模型即可：
+```bash
+./llama-server -m bge-small-zh-v1.5-Q4.gguf --embedding --port 11434
+# 然后 EMBEDDING_API_URL=http://localhost:11434/v1 照用
+```
+- **Ollama**：模型管理方便（`pull`）、开箱即用，但常驻偏重。
+- **llama.cpp**：单文件更轻（内存更省，适合本机）、可离线自制 GGUF；但模型要自己下/转（无 registry）。
+- 二者对上层代码**等价**（都是 OpenAI 兼容 embedding 端点）。本机内存吃紧时，llama.cpp 通常更划算。
+
 ---
 
 ## 技术栈