diff --git a/.env.example b/.env.example index 3e75dde5..847bf6f1 100644 --- a/.env.example +++ b/.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= diff --git a/.env.lite.example b/.env.lite.example index 828c5613..1defd8c0 100644 --- a/.env.lite.example +++ b/.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 diff --git a/README.md b/README.md index 790a0b80..5a782298 100644 --- a/README.md +++ b/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: diff --git a/README_CN.md b/README_CN.md index 922d6083..861f253c 100644 --- a/README_CN.md +++ b/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: diff --git a/README_JA.md b/README_JA.md index ee879e45..c8a0abde 100644 --- a/README_JA.md +++ b/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 をダウンロードした場合: diff --git a/README_KO.md b/README_KO.md index 8018bdad..ebd823a1 100644 --- a/README_KO.md +++ b/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를 다운로드한 경우: diff --git a/config/builtin_models.yaml.example b/config/builtin_models.yaml.example index 2095d2d7..e6af14ce 100644 --- a/config/builtin_models.yaml.example +++ b/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: diff --git a/website-docs/01-getting-started/02-installation.md b/website-docs/01-getting-started/02-installation.md index 2a516aea..4e16cc83 100644 --- a/website-docs/01-getting-started/02-installation.md +++ b/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`)。 diff --git a/website-docs/01-getting-started/04-configuration.md b/website-docs/01-getting-started/04-configuration.md index 87cb84c5..48c0c9d4 100644 --- a/website-docs/01-getting-started/04-configuration.md +++ b/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 脚本。 diff --git a/website-docs/03-features/06-models.md b/website-docs/03-features/06-models.md index 53679812..8b0df7c8 100644 --- a/website-docs/03-features/06-models.md +++ b/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`: | 路径 | 说明 |