diff --git a/README.md b/README.md index 44f81a2..bf4b2cd 100644 --- a/README.md +++ b/README.md @@ -59,25 +59,112 @@ OpenViking 内部调用遵循： OpenViking session 由请求里的 `session_id` 创建和提交。`/memory-system/search` 的 OpenViking 分支固定调用 OpenViking `/api/v1/search/search`，`target_uri` 可选，默认是 `viking://user/memories`，并默认传 `level: 2`、`score_threshold: 0.8`。 -## 安装 +## 本地三服务安装 + +Memory Gateway 需要先连上两个后端服务。默认本地端口约定： + +| 服务 | 默认地址 | 作用 | +|---|---|---| +| OpenViking | `http://127.0.0.1:1933` | session、archive、long-term memory、resources、semantic search | +| EverOS EverCore | `http://127.0.0.1:1995` | profile、episodic memory、recall | +| Memory Gateway | `http://127.0.0.1:1934` | 对业务方暴露统一 `/memory-system` API | + +### 安装 OpenViking + +OpenViking 可以直接用 `pip install` 安装，不需要 clone 源码。Memory Gateway 只依赖它暴露 HTTP API 和一个服务端 root key： ```bash -cd /home/tom/memory-gateway +python -m venv /Users/tom/.venvs/openviking +source /Users/tom/.venvs/openviking/bin/activate +pip install -U pip +pip install openviking --upgrade --force-reinstall +``` + +如果本机已经有 OpenViking 源码或已安装的 `openviking-server`，可以跳过安装，直接确认 `openviking-server --help` 可用。 + +### 安装 EverOS / EverCore + +Memory Gateway 使用 EverOS 里的 EverCore HTTP 服务。按 [EverOS / EverCore Quick Start](https://github.com/EverMind-AI/EverOS#evercore)： + +```bash +git clone https://github.com/EverMind-AI/EverOS.git /Users/tom/projects/EverOS +cd /Users/tom/projects/EverOS/methods/EverCore + +# 需要 Docker 和 Python 3.12。 +cp /Users/tom/projects/memory-gateway/everos.env.example .env +# 编辑 .env，至少填入实际可用的 LLM_API_KEY 和 VECTORIZE_API_KEY。 + +docker compose up -d +uv sync +``` + +如果 EverOS 已经在本机存在，只需要进入 `methods/EverCore` 并补齐 `.env`。 + +### 安装 Memory Gateway + +```bash +cd /Users/tom/projects/memory-gateway python -m venv .venv source .venv/bin/activate pip install -U pip pip install -e ".[dev]" ``` -## 配置 - -复制配置模板： +也可以用 `uv`： ```bash +uv sync --extra dev +``` + +## 配置文件 + +### OpenViking 配置 + +Memory Gateway 仓库内提供 OpenViking 配置模板： + +```bash +mkdir -p ~/.openviking +cp /Users/tom/projects/memory-gateway/openviking.ov.conf.example ~/.openviking/ov.conf +``` + +然后编辑 `~/.openviking/ov.conf`，至少替换： + +| 占位符 | 含义 | +|---|---| +| `` | OpenViking root key；必须和 Memory Gateway `config.yaml` 里的 `openviking.api_key` 一致 | +| `` / `` / `` / `` | OpenViking embedding provider 配置 | +| `` / `` / `` / `` | OpenViking VLM provider 配置 | +| `` / `` / `` / `` | OpenViking rerank provider 配置 | + +配置好后先跑一次： + +```bash +openviking-server doctor +``` + +`root_api_key` 只放在 OpenViking 和 Memory Gateway 的服务端配置里。业务调用方不要传 root key。 + +### EverOS / EverCore 配置 + +Memory Gateway 仓库内也提供 EverOS / EverCore 的 `.env` 模板。复制到 EverCore 目录： + +```bash +cd /Users/tom/projects/EverOS/methods/EverCore +cp /Users/tom/projects/memory-gateway/everos.env.example .env +``` + +然后编辑 `.env`，至少填入 `LLM_API_KEY`、`LLM_MODEL`、`VECTORIZE_API_KEY`、`EMBEDDING_MODEL` 和 `RERANK_MODEL`。Docker 依赖地址默认使用模板里的本地 compose 端口；如果改过 EverCore 的 compose 配置，需要同步修改 `.env`。 + +### Memory Gateway 配置 + +复制 Gateway 配置模板： + +```bash +cd /Users/tom/projects/memory-gateway cp config.example.yaml config.yaml ``` -主要配置： +然后编辑 `config.yaml`： ```yaml server: @@ -87,7 +174,7 @@ server: openviking: url: "http://127.0.0.1:1933" - api_key: "your-secret-root-key" + api_key: "" timeout: 30 verify_ssl: true @@ -99,7 +186,7 @@ everos: health_path: "/health" storage: - sqlite_path: "/home/tom/memory-gateway/memory_system_api.sqlite3" + sqlite_path: "./memory_system_api.sqlite3" ``` 环境变量也可以覆盖部分配置： @@ -117,12 +204,41 @@ storage: ## 启动 -先启动 OpenViking 和 EverOS，再启动 Memory System API： +按依赖顺序启动三个服务。 + +终端 1：启动 OpenViking。 ```bash +source /Users/tom/.venvs/openviking/bin/activate +openviking-server --config ~/.openviking/ov.conf +``` + +如果使用 Docker 方式运行 OpenViking，确认对 Memory Gateway 暴露的是 `1933` 端口，避免和 Memory Gateway 的 `1934` 端口冲突。 + +终端 2：启动 EverOS / EverCore。 + +```bash +cd /Users/tom/projects/EverOS/methods/EverCore +docker compose up -d +uv run python src/run.py --port 1995 +``` + +终端 3：启动 Memory Gateway。 + +```bash +cd /Users/tom/projects/memory-gateway +source .venv/bin/activate python -m memory_system_api.server --config config.yaml --host 0.0.0.0 --port 1934 ``` +健康检查： + +```bash +curl -sS http://127.0.0.1:1933/health +curl -sS http://127.0.0.1:1995/health +curl -sS http://127.0.0.1:1934/memory-system/health +``` + 如果 `server.api_key` 非空，所有请求还要加： ```bash diff --git a/config.example.yaml b/config.example.yaml index e3646d9..8e3ad91 100644 --- a/config.example.yaml +++ b/config.example.yaml @@ -1,15 +1,21 @@ +# Copy this file to config.yaml and replace placeholders with local values. +# Do not commit config.yaml because it may contain backend root keys. + server: host: "127.0.0.1" port: 1934 + # Optional key that protects Memory Gateway itself. Leave empty for local dev. api_key: "" openviking: + # OpenViking HTTP server. The api_key must match server.root_api_key in ov.conf. url: "http://127.0.0.1:1933" - api_key: "your-secret-root-key" + api_key: "" timeout: 30 verify_ssl: true everos: + # EverOS EverCore HTTP server. url: "http://127.0.0.1:1995" api_key: "" timeout: 180 @@ -17,7 +23,7 @@ everos: health_path: "/health" storage: - sqlite_path: "/home/tom/memory-gateway/memory_system_api.sqlite3" + sqlite_path: "./memory_system_api.sqlite3" logging: level: "INFO" diff --git a/everos.env.example b/everos.env.example new file mode 100644 index 0000000..4feb7c5 --- /dev/null +++ b/everos.env.example @@ -0,0 +1,77 @@ +# Copy this file to ./EverOS/methods/EverCore/.env. +# Do not commit the copied .env file because it contains provider keys. + +# Required by EverCore for memory extraction. +LLM_PROVIDER=openai +LLM_MODEL= +LLM_BASE_URL= +LLM_API_KEY= +LLM_TEMPERATURE=0.3 +LLM_MAX_TOKENS=1000000 + +# Required by EverCore for embedding and rerank. + +VECTORIZE_PROVIDER=vllm +VECTORIZE_API_KEY= +VECTORIZE_BASE_URL= +VECTORIZE_MODEL=Qwen3-VL-Embedding-2B +VECTORIZE_FALLBACK_PROVIDER=none +VECTORIZE_TIMEOUT=30 +VECTORIZE_MAX_RETRIES=3 +VECTORIZE_BATCH_SIZE=10 +VECTORIZE_MAX_CONCURRENT=5 +VECTORIZE_ENCODING_FORMAT=float +VECTORIZE_DIMENSIONS=1024 + +RERANK_PROVIDER=vllm +RERANK_API_KEY= +RERANK_BASE_URL= +RERANK_MODEL=Qwen3-VL-Reranker-2B + +# EverCore API server. +API_BASE_URL=http://localhost:1995 +LOG_LEVEL=INFO +ENV=dev +PYTHONASYNCIODEBUG=1 +MEMORY_LANGUAGE=en + +# Docker compose default dependencies. + +# =================== +# Redis Configuration +# =================== + +TENANT_SINGLE_TENANT_ID=t_tom +REDIS_HOST=localhost +REDIS_PORT=6379 +REDIS_DB=8 +REDIS_SSL=false + +# =================== +# MongoDB Configuration +# =================== + +MONGODB_HOST=localhost +MONGODB_PORT=27017 +MONGODB_USERNAME=admin +MONGODB_PASSWORD=memsys123 +MONGODB_DATABASE=memsys +MONGODB_URI_PARAMS=socketTimeoutMS=15000&authSource=admin + +# =================== +# Elasticsearch Configuration +# =================== + +ES_HOSTS=http://localhost:19200 +ES_USERNAME= +ES_PASSWORD= +ES_VERIFY_CERTS=false +SELF_ES_INDEX_NS=memsys + +# =================== +# Milvus Vector Database Configuration +# =================== + +MILVUS_HOST=localhost +MILVUS_PORT=19530 +SELF_MILVUS_COLLECTION_NS=memsys diff --git a/openviking.ov.conf.example b/openviking.ov.conf.example new file mode 100644 index 0000000..3b45184 --- /dev/null +++ b/openviking.ov.conf.example @@ -0,0 +1,44 @@ +{ + "server": { + "host": "0.0.0.0", + "port": 1933, + "auth_mode": "api_key", + "root_api_key": "", + "cors_origins": ["*"] + }, + "storage": { + "workspace": "/Users/tom/projects/openviking_workspace", + "agfs": { + "backend": "local" + }, + "vectordb": { + "name": "context", + "backend": "local" + } + }, + "memory": { + "version": "v2", + "agent_scope_mode": "user+agent" + }, + "embedding": { + "dense": { + "provider": "", + "api_base": "", + "api_key": "", + "model": "", + "dimension": 1024 + } + }, + "vlm": { + "provider": "", + "api_base": "", + "api_key": "", + "model": "" + }, + "rerank": { + "provider": "", + "api_base": "", + "api_key": "", + "model": "" + } +}