Files

T

superidou b536672000 feat(m8): P2 pgvector + Ollama 向量化与语义检索

- PostgreSQL 切换 pgvector/pgvector:pg17 镜像;迁移 000024 建 vector 扩展、
  knowledge_chunks.embedding vector(1024) + HNSW 余弦索引,retrieval_mode 放宽三态
- OllamaEmbedder 本地 bge-m3 批量嵌入,404 惰性 pull 重试,维度/超时校验,可整体关闭
- SemanticRetriever/HybridRetriever + NewRetriever 按 retrieval_mode 分发,缺 embedder 回退 FTS
- 文档入库同步批量向量化;Ollama 故障降级入库 + embedding_failed 事件
- 修复 pgx CopyFrom 对 vector 列二进制编码误读:COPY 基础列后同事务 unnest 批量回填
- 修复降级路径 embeddings=nil 索引越界 panic(Add 与 Reprocess)
- 知识库列表 vectorized_chunk_count + 前端三态检索模式选择与向量化覆盖率
- 单测 embedder/retrievers + 集成 TestKnowledgeVectorLifecycle 全绿

Co-Authored-By: Claude <noreply@anthropic.com>

2026-08-12 15:16:32 +08:00

3.3 KiB

Raw Blame History

Production deployment

This bundle builds the Go services and both Art Design Pro applications from source. PostgreSQL (with pgvector), two Redis roles, MinIO (object storage, M8) and a local Ollama container (vectorization, M8) are included; ClickHouse is not required. Neither MinIO nor Ollama is a startup dependency: the gateway warns and refuses file uploads until the bucket is reachable, and knowledge-base documents are still stored (with embedding set to NULL) when Ollama is down, with retrieval falling back to full-text search.

Prerequisites

Docker Engine with Compose v2
At least 4 CPU cores, 8 GiB RAM and 30 GiB free disk for an initial build
An external TLS reverse proxy or load balancer
A backup destination for the PostgreSQL volume

First deployment

Run all commands from the repository root:

cp deploy/production.env.example deploy/production.env
chmod 600 deploy/production.env
# Edit deploy/production.env and replace every CHANGE_ME value.

docker compose \
  --env-file deploy/production.env \
  -f deploy/docker-compose.production.yml \
  config --quiet

docker compose \
  --env-file deploy/production.env \
  -f deploy/docker-compose.production.yml \
  up -d --build

Create the initial administrator once:

docker compose \
  --env-file deploy/production.env \
  -f deploy/docker-compose.production.yml \
  --profile tools run --rm bootstrap-admin

Then remove BOOTSTRAP_ADMIN_PASSWORD from deploy/production.env and use the admin UI to create database-backed gateway API keys.

Endpoints

API and OpenAI-compatible gateway: 127.0.0.1:8080
Admin UI: http://127.0.0.1:8081/admin/
Portal UI: http://127.0.0.1:8082/portal/
Liveness/readiness: /healthz and /readyz

Ports bind to loopback by default. Terminate TLS at a reverse proxy and forward to these endpoints. Change *_BIND_IP only when the host firewall and network policy are already in place.

Operations

Check status and logs:

docker compose --env-file deploy/production.env -f deploy/docker-compose.production.yml ps
docker compose --env-file deploy/production.env -f deploy/docker-compose.production.yml logs --tail=200 gateway-api
curl --fail http://127.0.0.1:8080/readyz

For upgrades, back up PostgreSQL first, change GATEWAY_VERSION, then run the same up -d --build command. The one-shot migrator applies forward migrations before the API starts. Do not use docker compose down -v in production because it removes persistent data.

The bundled database URLs use sslmode=disable only for the private Compose network. When using an external PostgreSQL or Redis service, require TLS and use sslmode=verify-full / rediss:// as supported by that service.

Vectorization and object storage

The PostgreSQL image is pgvector/pgvector:pg17 (data-volume compatible with postgres:17-alpine); migration 000024 creates the vector extension and adds the HNSW embedding column. EMBEDDING_DIM must stay at 1024 to match the vector(1024) column.
Ollama runs locally and lazily pulls bge-m3 (~1.2 GiB) on first embedding request. Set EMBEDDINGS_ENABLED=false to disable vectorization entirely.
Back up the minio-data and ollama-models volumes alongside PostgreSQL.
If you previously deployed with postgres:17-alpine, back up the PostgreSQL volume before switching images.

3.3 KiB Raw Blame History