docs(ollama): document embedding model config and RAM guidance (#3531)

* docs(ollama): document embedding model config and RAM guidance (#3480)

Local embedding and generation share the Ollama process at OLLAMA_BASE_URL.
The embedding model name is the local Embedding model's name; EMBEDDING_MODEL_NAME
is read only when builtin_models.yaml references it. The published 8 GB
starting point does not include Ollama weights or optional Neo4j.

Fixes #3480

* docs(ollama): shrink README/docs scope per maintainer review (#3480)

.env.example

@@ -345,7 +345,10 @@ RETRIEVE_DRIVER=postgres
 # ========== D1. LLM / VLM / Ollama ==========
 # Ollama 不可用时仅告警不阻断（true 时生效，默认不阻断，避免未配 Ollama 就启动失败）。
 OLLAMA_OPTIONAL=true
-# Ollama 服务基准 URL（连接本地/远程 Ollama）。
+# 本地 Ollama 的唯一地址。source=local 的向量模型与对话模型共用这一进程，
+# 不需要为 embedding 再起一个 Ollama。未设置时进程回退到 http://localhost:11434。
+# 向量模型名不是环境变量：在「设置 → 模型」、CLI 或初始化接口里把 Embedding
+# 模型的 name 设为 Ollama 模型名（如 nomic-embed-text）。见 README 的 Ollama 说明。
 OLLAMA_BASE_URL=http://host.docker.internal:11434
 # 批量 embedding 大小（留空走代码默认）。
 # BATCH_EMBED_SIZE=
@@ -366,7 +369,10 @@ OLLAMA_BASE_URL=http://host.docker.internal:11434
 # LLM_API_KEY=
 # LLM_PROVIDER=openai
 #
-# 内置向量模型
+# 内置向量模型。下面的名字只有写进 builtin_models.yaml 的 ${...} 才会被读取。
+# 本地 Ollama 向量模型用 source: local，name 用 ${EMBEDDING_MODEL_NAME}（Ollama 模型名）；
+# 地址仍是上面的 OLLAMA_BASE_URL。EMBEDDING_BASE_URL 只用于 source: remote 的 API。
+# 示例见 config/builtin_models.yaml.example 的 “one local Ollama” 段。
 # EMBEDDING_MODEL_NAME=
 # EMBEDDING_BASE_URL=
 # EMBEDDING_API_KEY=

.env.lite.example

@@ -28,7 +28,9 @@ LOCAL_STORAGE_BASE_DIR=./data/files
 STREAM_MANAGER_TYPE=memory
 
 # === LLM 服务 ===
-# Ollama 本地服务（默认地址，按需修改）
+# Ollama 本地服务（默认地址，按需修改）。
+# source=local 的向量模型与对话模型共用这一地址，不必为 embedding 再起一个 Ollama。
+# 向量模型名在模型配置里填写（如 nomic-embed-text），不是单独的环境变量。
 OLLAMA_BASE_URL=http://127.0.0.1:11434
 # 如使用其他 OpenAI 兼容服务，取消注释：
 # OPENAI_API_KEY=sk-xxx

README.md

@@ -249,6 +249,8 @@ Once started, visit **http://localhost** to get started.
 
 > To use a local Ollama model, run `ollama serve > /dev/null 2>&1 &` first.
 
+For Ollama embedding model name, `OLLAMA_BASE_URL`, and RAM notes, see [configuration](./website-docs/01-getting-started/04-configuration.md).
+
 ### 🔄 Upgrading
 
 If you already have WeKnora running and downloaded a newer release:

README_CN.md

@@ -226,6 +226,8 @@ docker compose up -d    # 启动核心服务
 
 > 如需使用本地 Ollama 模型，请先运行 `ollama serve > /dev/null 2>&1 &`
 
+Ollama 向量模型名、`OLLAMA_BASE_URL` 与内存说明见[配置文档](./website-docs/01-getting-started/04-configuration.md)。
+
 ### 🔄 版本升级
 
 若已有部署并下载了更新的 release：

README_JA.md

@@ -215,6 +215,8 @@ docker compose up -d    # コアサービスを起動
 
 > ローカル Ollama モデルを使用する場合は、先に `ollama serve > /dev/null 2>&1 &` を実行してください。
 
+Ollama の埋め込みモデル名、`OLLAMA_BASE_URL`、メモリの注意は[設定ドキュメント](./website-docs/01-getting-started/04-configuration.md)を参照してください。
+
 ### 🔄 アップグレード
 
 既存のデプロイがあり、新しい release をダウンロードした場合：

README_KO.md

@@ -225,6 +225,8 @@ docker compose up -d    # 코어 서비스 시작
 
 > 로컬 Ollama 모델을 사용하려면 먼저 `ollama serve > /dev/null 2>&1 &` 를 실행하세요.
 
+Ollama 임베딩 모델 이름, `OLLAMA_BASE_URL`, RAM 안내는 [설정 문서](./website-docs/01-getting-started/04-configuration.md)를 보세요.
+
 ### 🔄 업그레이드
 
 기존 배포가 있고 새 release를 다운로드한 경우:

config/builtin_models.yaml.example

@@ -62,6 +62,27 @@ builtin_models: []
 #       api_key: ${RERANK_API_KEY}
 #       provider: ${RERANK_PROVIDER}
 #
+# ----- Example: one local Ollama for embedding and generation ---------------
+# source: local uses OLLAMA_BASE_URL only. Embedding and chat share that
+# process; a second Ollama is not required. ${EMBEDDING_MODEL_NAME} is read
+# only because this file references it (see .env.example section D2).
+# dimension is a literal and must match the pulled model (the CLI example
+# nomic-embed-text uses 768). Uncomment this list on its own — do not also
+# uncomment the remote embedding entry above, or you will register two defaults.
+#
+# builtin_models:
+#   - id: builtin-ollama-chat
+#     type: KnowledgeQA
+#     source: local
+#     name: ${LLM_MODEL_NAME}            # Ollama chat model, e.g. qwen2.5:7b
+#   - id: builtin-ollama-embedding
+#     type: Embedding
+#     source: local
+#     name: ${EMBEDDING_MODEL_NAME}      # Ollama embedding model name
+#     parameters:
+#       embedding_parameters:
+#         dimension: 768
+#
 # ----- Example: literal values (no env indirection) -------------------------
 #
 # builtin_models:

website-docs/01-getting-started/02-installation.md

@@ -39,7 +39,7 @@ flowchart TB
 ## 硬件与依赖要求
 
 - **标准 Docker 部署**：Docker 20.10+ 与 Docker Compose v2（v1 `docker-compose` 也兼容，`scripts/start_all.sh` 会自动探测）；建议 4 核 CPU / 8GB 内存起步（docreader 含 LibreOffice、Playwright，较吃内存），磁盘按知识库规模预留（Postgres 卷 + `/data/files` 文件卷）。启用 Milvus / OpenSearch / Langfuse 等可选组件需相应增加内存。
-- **模型服务**：本地推理需 [Ollama](https://ollama.com)（默认地址 `http://host.docker.internal:11434`，`OLLAMA_OPTIONAL=true` 时不可用仅告警不阻断）；或任意 OpenAI 兼容 API（DeepSeek、通义、智谱、硅基流动等）。
+- **模型服务**：本地推理需 [Ollama](https://ollama.com)（默认地址 `http://host.docker.internal:11434`，`OLLAMA_OPTIONAL=true` 时不可用仅告警不阻断）；或任意 OpenAI 兼容 API（DeepSeek、通义、智谱、硅基流动等）。上述 8GB 起步不含 Ollama 模型权重；Neo4j 默认关闭（需启用 `neo4j` profile）。
 - **源码编译**：Go 1.26（见 `docker/Dockerfile.app` builder 阶段 `golang:1.26-bookworm`）、CGO（依赖 `libsqlite3-dev`）、Node.js + npm（前端）、Python 3.10 + uv（docreader）。
 - **Kubernetes**：>= 1.25.0（`helm/Chart.yaml`）。
 

website-docs/01-getting-started/04-configuration.md

@@ -207,13 +207,15 @@ AWS S3 的 `S3_ACCESS_KEY` / `S3_SECRET_KEY` 可以**同时留空**，此时走
 
 | 名称 | 默认值 | 说明 |
 | --- | --- | --- |
-| `OLLAMA_BASE_URL` | http://host.docker.internal:11434 | Ollama 地址 |
+| `OLLAMA_BASE_URL` | http://host.docker.internal:11434 | 唯一的本地 Ollama 地址。`source=local` 的向量与对话模型共用它；未设置时进程用 `http://localhost:11434` |
 | `OLLAMA_OPTIONAL` | true | Ollama 不可用时仅告警不阻断启动 |
 | `BATCH_EMBED_SIZE` | 空 | 批量 embedding 大小 |
 | `VLM_HTTP_TIMEOUT_SECONDS` | 180 | VLM 单次请求超时 |
 | `BUILTIN_MODELS_CONFIG` | config/builtin_models.yaml | 内置模型声明文件路径（见下文） |
 | `WEKNORA_LLM_STREAM_RAW_DUMP` / `_DIR` | 空 | LLM 流原始转储（排障用） |
 
+向量模型名不由环境变量决定。在模型记录里把 `type=Embedding`、`source=local` 的 `name` 设为 Ollama 模型名（CLI 示例 `nomic-embed-text`，维度 768；快速开始用 `bge-m3`，维度 1024）。名为空时本地 embedder 回退到 `nomic-embed-text`。`EMBEDDING_MODEL_NAME` 只在 `builtin_models.yaml` 引用 `${EMBEDDING_MODEL_NAME}` 时生效（见下文「config/builtin_models.yaml.example：声明式内置模型」与仓库 `config/builtin_models.yaml.example`）。安装文档的 8GB 起点不含 Ollama 权重；Neo4j 默认关闭（`neo4j` profile）。
+
 ### 认证、租户与安全
 
 | 名称 | 默认值 | 说明 |
@@ -393,6 +395,8 @@ builtin_models:
 
 注意：未设置的 `${ENV}` 会保留字面量以便暴露配置错误；非字符串字段（`type`、`source`、`is_default`、`dimension` 等）必须写字面值；从文件删除条目**不会**自动删库，需手动清理。
 
+本地 Ollama：把 `source` 写成 `local`，`name` 用 Ollama 模型名（向量侧可用 `${EMBEDDING_MODEL_NAME}`）。完整注释示例见 `config/builtin_models.yaml.example` 的 “one local Ollama” 段；`dimension` 须为字面量（CLI 示例 `nomic-embed-text` 为 768）。
+
 ## 配置优先级速记
 
 对同一语义的配置，生效优先级为：**数据库 `system_settings`（仅注册在表内的键）> 环境变量 > config.yaml > 代码内置默认值**；租户/知识库级配置（`RetrievalConfig`、`ChunkingConfig` 等，存于数据库）在运行时覆盖全局默认。修改 `.env` 后需重启容器（`docker compose up -d app`）；开发模式 air 热重载不会重读 `.env`，需重启 dev 脚本。

website-docs/03-features/06-models.md

@@ -141,6 +141,8 @@ builtin_models:
 
 #### 本地模型下载（Ollama）
 
+本地 embedding 与对话共用同一 `OLLAMA_BASE_URL`；向量模型名与环境变量说明见 [配置文档](../01-getting-started/04-configuration.md)。
+
 本地模型的生命周期由 `internal/models/utils/ollama/ollama.go` 的 `OllamaService` 管理（`IsModelAvailable` / `PullModel` / `EnsureModelAvailable` / `ListModelsDetailed` / `DeleteModel` 等），HTTP 入口在 `internal/handler/initialization.go`：
 
 | 路径 | 说明 |