A FULL local version use of vllm and llamacpp to host

.env.example

@@ -4,13 +4,54 @@
 LLM_API_KEY=your_api_key_here
 LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
 LLM_MODEL_NAME=qwen-plus
+LLM_CONTEXT_WINDOW=8192
+LLM_MAX_CONCURRENCY=1
+LLM_JSON_MAX_RETRIES=2
+ONTOLOGY_MAX_OUTPUT_TOKENS=2048
+ONTOLOGY_PROMPT_MARGIN_TOKENS=512
+ONTOLOGY_MAX_CHUNKS=8
+LOCAL_ZEP_EXTRACT_MAX_OUTPUT_TOKENS=2048
+LOCAL_ZEP_EXTRACT_MAX_RETRIES=2
 
-# ===== ZEP记忆图谱配置 =====
-# 每月免费额度即可支撑简单使用：https://app.getzep.com/
-ZEP_API_KEY=your_zep_api_key_here
+# ===== Local Zep / Embeddings 配置 =====
+# 使用 OpenAI-compatible embeddings 接口，vLLM 可作为首选后端
+EMBEDDING_API_KEY=local-embedding-key
+EMBEDDING_BASE_URL=http://localhost:8001/v1
+EMBEDDING_MODEL_NAME=your_embedding_model_here
+
+# 可选：cross_encoder reranker 接口；不配置时本地图谱会自动回退到 RRF
+RERANKER_API_KEY=local-reranker-key
+RERANKER_BASE_URL=http://localhost:8002/v1
+RERANKER_MODEL_NAME=your_reranker_model_here
+LOCAL_ZEP_RERANK_TOP_K=50
+
+# 本地图谱 SQLite 路径（可选）
+LOCAL_ZEP_DB_PATH=backend/data/local_zep.sqlite3
+
+# Optional: Python executable for the original OASIS/CAMEL simulation runner.
+# Use this when the backend runs on Python 3.13 but OASIS is installed in a Python 3.11 venv.
+# OASIS_PYTHON=/absolute/path/to/oasis-venv/bin/python
+
+# ===== Tailscale / Remote Access（可选）=====
+# 前端开发模式默认会通过 /api 代理访问后端，适合直接用 Tailscale 访问 http://<tailnet-host>:3000
+VITE_API_BASE_URL=
+VITE_DEV_HOST=0.0.0.0
+VITE_DEV_PORT=3000
+VITE_DEV_PROXY_TARGET=http://127.0.0.1:5001
+VITE_ALLOWED_HOSTS=localhost,127.0.0.1,.ts.net,.beta.tailscale.net
+
+# 如果通过 MagicDNS 访问时 HMR 需要显式指定，可取消注释
+# VITE_HMR_HOST=your-machine.your-tailnet.ts.net
+# VITE_HMR_CLIENT_PORT=3000
+
+FLASK_HOST=0.0.0.0
+FLASK_PORT=5001
+ENABLE_PROXY_FIX=false
+PUBLIC_BASE_URL=
+TAILSCALE_URL=
 
 # ===== 加速 LLM 配置（可选）=====
 # 注意如果不使用加速配置，env文件中就不要出现下面的配置项
 LLM_BOOST_API_KEY=your_api_key_here
 LLM_BOOST_BASE_URL=your_base_url_here
-LLM_BOOST_MODEL_NAME=your_model_name_here
+LLM_BOOST_MODEL_NAME=your_model_name_here

.gitignore

@@ -9,6 +9,7 @@ Thumbs.db
 .env.development
 .env.test
 .env.production
+start.sh
 
 # Python
 __pycache__/
@@ -18,6 +19,7 @@ __pycache__/
 .Python
 .venv/
 venv/
+venv11/
 ENV/
 .eggs/
 *.egg-info/
@@ -57,4 +59,4 @@ backend/logs/
 backend/uploads/
 
 # Docker 数据
-data/
+data/

README-ZH.md

@@ -100,8 +100,8 @@ MiroFish 致力于打造映射现实的群体智能镜像，通过捕捉个体
 | 工具 | 版本要求 | 说明 | 安装检查 |
 |------|---------|------|---------|
 | **Node.js** | 18+ | 前端运行环境，包含 npm | `node -v` |
-| **Python** | ≥3.11, ≤3.12 | 后端运行环境 | `python --version` |
-| **uv** | 最新版 | Python 包管理器 | `uv --version` |
+| **Python** | ≥3.11 | 后端运行环境。API 与本地图谱后端支持 Python 3.13。 | `python --version` |
+| **Python 3.11** | 3.11.x | 可选但推荐给 OASIS/CAMEL 使用，因为 `camel-oasis==0.2.5` 声明 Python `<3.12`。 | `python3.11 --version` |
 
 #### 1. 配置环境变量
 
@@ -121,10 +121,31 @@ cp .env.example .env
 LLM_API_KEY=your_api_key
 LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
 LLM_MODEL_NAME=qwen-plus
-
-# Zep Cloud 配置
-# 每月免费额度即可支撑简单使用：https://app.getzep.com/
-ZEP_API_KEY=your_zep_api_key
+LLM_CONTEXT_WINDOW=8192
+LLM_MAX_CONCURRENCY=1
+LLM_JSON_MAX_RETRIES=2
+ONTOLOGY_MAX_OUTPUT_TOKENS=2048
+ONTOLOGY_PROMPT_MARGIN_TOKENS=512
+LOCAL_ZEP_EXTRACT_MAX_OUTPUT_TOKENS=2048
+LOCAL_ZEP_EXTRACT_MAX_RETRIES=2
+
+# 本地图谱 / Embeddings 配置
+# 使用 OpenAI-compatible embeddings 接口，推荐优先接 vLLM
+EMBEDDING_API_KEY=local-embedding-key
+EMBEDDING_BASE_URL=http://localhost:8001/v1
+EMBEDDING_MODEL_NAME=your_embedding_model
+
+# 可选 cross-encoder reranker 接口；不配置时本地图谱搜索自动回退到 RRF
+RERANKER_API_KEY=local-reranker-key
+RERANKER_BASE_URL=http://localhost:8002/v1
+RERANKER_MODEL_NAME=your_reranker_model
+LOCAL_ZEP_RERANK_TOP_K=50
+
+# 可选：本地图谱 SQLite 存储路径
+LOCAL_ZEP_DB_PATH=backend/data/local_zep.sqlite3
+
+# 可选：为原版 OASIS/CAMEL 脚本指定独立 Python 3.11 venv
+OASIS_PYTHON=/absolute/path/to/venv11/bin/python
 ```
 
 #### 2. 安装依赖
@@ -144,6 +165,23 @@ npm run setup
 npm run setup:backend
 ```
 
+如果系统默认 `python3` 低于 3.11，可以手动用目标解释器创建后端 venv：
+
+```bash
+python3.13 -m venv venv
+./venv/bin/python -m pip install --upgrade pip
+./venv/bin/python -m pip install -r backend/requirements.txt
+```
+
+如果需要运行原版 OASIS/CAMEL 模拟引擎，建议单独创建 Python 3.11 venv，并在 `.env` 中设置 `OASIS_PYTHON`：
+
+```bash
+python3.11 -m venv venv11
+./venv11/bin/python -m pip install --upgrade pip
+./venv11/bin/python -m pip install -r backend/requirements.txt
+echo "OASIS_PYTHON=$(pwd)/venv11/bin/python" >> .env
+```
+
 #### 3. 启动服务
 
 ```bash
@@ -162,8 +200,130 @@ npm run backend   # 仅启动后端
 npm run frontend  # 仅启动前端
 ```
 
+### 本地模型运行与参数
+
+MiroFish 不再依赖 Zep Cloud。本地图谱模块会把图数据存入 SQLite，并使用你提供的 OpenAI-compatible embedding 接口。Reranker 是可选项，只在图谱搜索请求 `cross_encoder` 时用于重排候选结果；未配置时会自动回退到本地 hybrid ranking / RRF。
+
+本地端点示例：
+
+```bash
+# 主 LLM，llama.cpp 示例
+llama-server \
+  -m /path/to/model.gguf \
+  --alias Qwen3.5-9B-VL \
+  --host 127.0.0.1 \
+  --port 8000 \
+  -c 16384 \
+  --jinja
+
+# Embeddings，vLLM 示例
+vllm serve /path/to/Qwen3-Embedding-0.6B \
+  --host 127.0.0.1 \
+  --port 8001 \
+  --runner pooling \
+  --max-model-len 8192
+
+# 可选 reranker，vLLM 示例
+vllm serve /path/to/Qwen3-Reranker-0.6B \
+  --host 127.0.0.1 \
+  --port 8002 \
+  --runner pooling \
+  --max-model-len 8192
+```
+
+已验证可用于 24GB 显存 GPU（RTX 3090 / RTX 4090 级别）的配置。路径已做匿名化处理：
+
+```bash
+# 主 llama.cpp LLM 端点
+./llama-server \
+  --mmproj /path/to/models/Qwen3.5-9B-gguf/mmproj-Qwen3.5-9B-BF16.gguf \
+  --alias Qwen3.5-9B-VL \
+  --host 127.0.0.1 \
+  --port 8000 \
+  -c 280000 \
+  -ngl auto \
+  --temp 0.7 \
+  --top-p 0.8 \
+  --top-k 20 \
+  --min-p 0.0 \
+  --jinja \
+  -m /path/to/models/Qwen3.5-9B-gguf/Qwen3.5-9B-Q6_K.gguf
+
+# Embedding 端点，实测峰值约 2-3GB 显存
+vllm serve /path/to/models/embedding/Qwen3-Embedding-0.6B \
+  --host 127.0.0.1 \
+  --port 8001 \
+  --runner pooling \
+  --gpu-memory-utilization 0.08 \
+  --max-model-len 8192 \
+  --quantization fp8 \
+  --kv-cache-dtype fp8
+
+# Reranker 端点，实测峰值约 2-3GB 显存
+vllm serve /path/to/models/embedding/Qwen3-Reranker-0.6B \
+  --host 127.0.0.1 \
+  --port 8002 \
+  --runner pooling \
+  --gpu-memory-utilization 0.09 \
+  --max-model-len 8192 \
+  --quantization fp8 \
+  --kv-cache-dtype fp8
+```
+
+对应 `.env`：
+
+```env
+LLM_BASE_URL=http://127.0.0.1:8000/v1
+LLM_MODEL_NAME=Qwen3.5-9B-VL
+LLM_CONTEXT_WINDOW=280000
+LLM_MAX_CONCURRENCY=1
+ONTOLOGY_MAX_OUTPUT_TOKENS=8192
+LOCAL_ZEP_EXTRACT_MAX_OUTPUT_TOKENS=8192
+
+EMBEDDING_BASE_URL=http://127.0.0.1:8001/v1
+EMBEDDING_MODEL_NAME=/path/to/Qwen3-Embedding-0.6B
+
+RERANKER_BASE_URL=http://127.0.0.1:8002/v1
+RERANKER_MODEL_NAME=/path/to/Qwen3-Reranker-0.6B
+LOCAL_ZEP_RERANK_TOP_K=50
+```
+
+参数规则：
+- `LLM_CONTEXT_WINDOW` 必须和主 LLM 服务暴露的上下文长度一致，确保 `prompt tokens + max output tokens <= LLM_CONTEXT_WINDOW`。
+- 使用上面的 24GB 配置时，`LLM_CONTEXT_WINDOW=280000` 应与 `-c 280000` 保持一致。16k 上下文模型建议 `ONTOLOGY_MAX_OUTPUT_TOKENS=8192`，大约保留一半窗口给输出；8k 端点建议使用 `2048` 到 `4096`。
+- 单个 llama.cpp/vLLM 主端点建议 `LLM_MAX_CONCURRENCY=1`，除非确认服务端可以稳定并发处理 chat completions。
+- Embedding 维度不需要手动配置。本地图谱会记录模型返回的向量；同一个图谱数据库应保持使用同一个 embedding 模型。
+- Reranker 与 embedding 是不同模型。Embedding 负责图谱索引和语义检索；reranker 只负责对候选搜索结果重排。
+- `.env`、`start.sh`、`venv/`、`venv11/`、上传的模拟数据和本地图谱数据库都会被 git 忽略。
+
+### Tailscale 访问
+
+发布说明：Tailscale 支持主要面向源码/开发部署，即后端和 Vite 代理运行在同一台主机上。它不会自动公开本地 LLM、embedding 或 reranker 端点；除非你明确需要暴露，否则建议这些模型端点继续绑定在 `127.0.0.1`。
+
+前端现在默认走同源 `/api`，不再默认写死 `http://localhost:5001`。因此你从另一台 Tailscale 设备访问 Vite 开发服务器时，前端请求会继续命中宿主机后端，而不会错误地访问调用方自己的 localhost。
+
+建议在项目根目录 `.env` 中加入：
+
+```env
+VITE_DEV_HOST=0.0.0.0
+VITE_DEV_PORT=3000
+VITE_DEV_PROXY_TARGET=http://127.0.0.1:5001
+VITE_ALLOWED_HOSTS=localhost,127.0.0.1,.ts.net,.beta.tailscale.net
+FLASK_HOST=0.0.0.0
+FLASK_PORT=5001
+```
+
+然后从另一台 Tailscale 设备访问：
+
+- 前端：`http://<你的 tailnet 主机名>:3000`
+- 后端：`http://<你的 tailnet 主机名>:5001`
+
+如果你通过 `tailscale serve` 或 `tailscale funnel` 暴露后端，建议设置 `ENABLE_PROXY_FIX=true`。如果通过 MagicDNS 访问时 HMR 连接不稳定，再额外设置 `VITE_HMR_HOST` 为你的 Tailscale 主机名。
+
 ### 二、Docker 部署
 
+发布限制：Docker 部署属于旧路径，目前未针对本地 Zep 替代、外部 vLLM/llama.cpp 端点、以及拆分的 Python 3.11 OASIS 运行时做完整验证。需要本地优先工作流时，请使用源码部署。
+
 ```bash
 # 1. 配置环境变量（同源码部署）
 cp .env.example .env