diff --git a/docker-compose.yml b/docker-compose.yml index e79fc121..c5e29a3c 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -375,6 +375,9 @@ services: # --------------------------------------------------------------------------- # Apache Doris 4.1(FE + BE 单实例 standalone 部署,opt-in via `--profile doris`) # + # 版本要求:必须 >= 3.0(HNSW ANN 索引、cosine_distance_approximate、 + # Stream Load partial_columns)。本 compose 使用 4.1 官方稳定 tag。 + # # 端口说明: # - 9030 (FE MySQL):WeKnora 主链路读写、SQL 查询都走此端口。 # - 8030 (FE HTTP):Stream Load partial update 入口。 @@ -386,7 +389,7 @@ services: # 数据持久化在 doris_fe_data / doris_be_data 卷中。 # --------------------------------------------------------------------------- doris-fe: - image: apache/doris:fe-2.1.0 + image: apache/doris:fe-4.1.0 container_name: WeKnora-doris-fe hostname: doris-fe environment: @@ -405,7 +408,7 @@ services: - doris doris-be: - image: apache/doris:be-2.1.0 + image: apache/doris:be-4.1.0 container_name: WeKnora-doris-be hostname: doris-be environment: diff --git a/docs/wiki/集成扩展/Doris改动与上游同步.md b/docs/wiki/集成扩展/Doris改动与上游同步.md deleted file mode 100644 index 4147dd83..00000000 --- a/docs/wiki/集成扩展/Doris改动与上游同步.md +++ /dev/null @@ -1,295 +0,0 @@ ---- -title: Doris 改动与上游同步 -tags: [集成扩展, 向量数据库, Doris, fork, 上游同步, 维护] -aliases: [Doris fork 工作流, Doris 改动记录, Doris 同步策略] -source: 本仓库本地维护文档 ---- - -# Apache Doris 4.1 集成改动与上游同步策略 - -本文记录在 WeKnora 中**新增 Apache Doris 4.1 作为第 6 种检索引擎**这一改动的完整细节,并给出与上游 [Tencent/WeKnora](https://github.com/Tencent/WeKnora) 长期保持同步的工作流建议。 - -> 相关文档: -> -> - [集成向量数据库](../集成扩展/集成向量数据库.md) —— 通用集成指南,含 Doris 章节 -> - 上层版本:[使用其他向量数据库](../../使用其他向量数据库.md) - -## 一、背景 - -当前仓库的 git 配置(**改动前**): - -- `origin` -> `https://github.com/Tencent/WeKnora.git`(直接指向上游) -- 当前分支 `main` 跟踪 `origin/main` -- Doris 改动以本地工作区形式存在 - -如果继续在 `main` 上累积本地修改、再 `git pull` 拉上游,长期会演变成「几百次 rebase 冲突 + 没法发 PR + 找不到自己改了什么」的死路。需要切到 fork 工作流。 - -## 二、推荐的上游同步工作流 - -### 2.1 仓库角色拆分 - -```mermaid -flowchart LR - upstream["upstream
Tencent/WeKnora
read only"] -->|fetch| local["本地仓库 main"] - local -->|push| fork["origin
个人 fork
yourname/WeKnora"] - local -->|长期分支| feat["feature/doris-engine"] - feat -->|push| fork - feat -.->|可选 PR 回上游| upstream -``` - -### 2.2 一次性配置 - -> 在 GitHub 上把 `Tencent/WeKnora` fork 到自己账号(例如 `yourname/WeKnora`)后执行: - -```bash -# 把现在的 origin 改名为 upstream(只读引用上游) -git remote rename origin upstream - -# 把自己的 fork 设为 origin(push 目标) -git remote add origin https://github.com/<你的用户名>/WeKnora.git -git push -u origin main - -# 把 Doris 改动放到长期 feature 分支 -git checkout -b feature/doris-engine -git add . -git commit -m "feat(retriever): integrate Apache Doris 4.1" -git push -u origin feature/doris-engine -``` - -完成后 remote 应该是这样: - -```bash -$ git remote -v -origin https://github.com/<你的用户名>/WeKnora.git (fetch) -origin https://github.com/<你的用户名>/WeKnora.git (push) -upstream https://github.com/Tencent/WeKnora.git (fetch) -upstream https://github.com/Tencent/WeKnora.git (push) -``` - -### 2.3 长期同步节奏(建议每周 / 每次大版本拉新) - -```bash -# 1) 拉上游 -git fetch upstream - -# 2) main 直接 fast-forward -git checkout main -git merge --ff-only upstream/main -git push origin main - -# 3) feature 分支 rebase 到最新 main -git checkout feature/doris-engine -git rebase main - -# 4) 解决冲突 -> 跑测试 -> 强推 fork -go build ./... -go test ./internal/types/... \ - ./internal/application/repository/retriever/doris/... \ - ./internal/application/service/... -git push --force-with-lease origin feature/doris-engine -``` - -**rebase 优于 merge** 的理由:feature 分支保持线性历史,未来想发 PR 给上游会容易很多;merge 会让 commit 图谱变成一团乱麻,也难以 cherry-pick 单条改动。 - -### 2.4 冲突高发文件(每次 rebase 必看) - -下面这些位置都是 WeKnora 的「检索引擎扩展点」,上游每加一个新引擎都会改一次,几乎一定会和我们的 Doris 分支撞: - -| 文件 | 撞点 | -| --- | --- | -| [internal/types/retriever.go](../../../internal/types/retriever.go) | `RetrieverEngineType` 枚举 | -| [internal/types/tenant.go](../../../internal/types/tenant.go) | `retrieverEngineMapping` map | -| [internal/types/vectorstore.go](../../../internal/types/vectorstore.go) | `ConnectionConfig` / `IndexConfig` 结构、`GetVectorStoreTypes` / `BuildEnvVectorStores` / `ValidateIndexConfig` 三个函数 | -| [internal/application/service/vectorstore.go](../../../internal/application/service/vectorstore.go) | `validateConnectionConfig` switch | -| [internal/application/service/vectorstore_healthcheck.go](../../../internal/application/service/vectorstore_healthcheck.go) | `TestConnection` switch | -| [internal/container/engine_factory.go](../../../internal/container/engine_factory.go) | `createEngineServiceFromStore` switch | -| [internal/container/container.go](../../../internal/container/container.go) | `initRetrieveEngineRegistry` 中的 driver if 链 | -| [docker-compose.yml](../../../docker-compose.yml) | app 服务 `environment:` 段、`volumes:` 段 | - -### 2.5 接口契约盯防 - -最容易踩坑的是 `interfaces.RetrieveEngineRepository`([internal/types/interfaces/retriever.go](../../../internal/types/interfaces/retriever.go)):上游一旦增加方法,所有实现包(包括 Doris)必须同步实现,否则编译失败。 - -每次 rebase 后**必须**跑: - -```bash -go build ./... -go vet ./... -go test ./internal/types/... \ - ./internal/application/repository/retriever/doris/... \ - ./internal/application/service/... -``` - -### 2.6 依赖 / 镜像维护 - -- **Go 依赖**:本次 Doris 集成新增 `github.com/go-sql-driver/mysql`(主依赖)和 `github.com/DATA-DOG/go-sqlmock`(测试依赖),它们被 `internal/application/repository/retriever/doris/` 直接引用,上游 `go mod tidy` 不会丢弃它们。 -- **Doris 镜像版本**:`docker-compose.yml` 中的 `apache/doris:fe-2.1.0` / `apache/doris:be-2.1.0` 需要随官方 4.x 镜像发布跟进升级。建议每个季度核对一次 [Apache Doris 镜像列表](https://hub.docker.com/r/apache/doris/tags)。 - -## 三、本次改动完整清单 - -### 3.1 改动统计 - -- 修改:15 个现有文件,约 +566 / -6 行 -- 新增:7 个文件,约 +2057 行 -- 总计:22 个文件,约 +2617 行 - -### 3.2 新增文件(7 个) - -| 文件 | 行数 | 主要内容 | -| --- | ---: | --- | -| [internal/application/repository/retriever/doris/structs.go](../../../internal/application/repository/retriever/doris/structs.go) | 63 | `dorisRepository` 结构体(`*sql.DB` / `*http.Client` / 凭据 / 表配置 / `initializedTables sync.Map`)+ `DorisVectorEmbedding(WithScore)` 领域模型 | -| [internal/application/repository/retriever/doris/schema.go](../../../internal/application/repository/retriever/doris/schema.go) | 280 | `ensureTable` + `tableExists` + `createTable` + DDL 模板(UNIQUE KEY MoW + INVERTED + ANN HNSW + chinese parser)+ `waitANNReady` 异步索引就绪轮询 + `listEmbeddingTables` | -| [internal/application/repository/retriever/doris/query.go](../../../internal/application/repository/retriever/doris/query.go) | 202 | `whereBuilder`(`addEqual` / `addIn` / `addNotIn`)+ `buildBaseFilter` + `embeddingLiteral` / `parseEmbeddingLiteral`(locale 安全的浮点序列化) | -| [internal/application/repository/retriever/doris/repository.go](../../../internal/application/repository/retriever/doris/repository.go) | 584 | `NewDorisRetrieveEngineRepository` 构造 + `interfaces.RetrieveEngineRepository` 12 个方法实现(`Save` / `BatchSave` / `Retrieve` 分发 / `VectorRetrieve` / `KeywordsRetrieve` / `Delete*` 三件套 / `CopyIndices` / `EstimateStorageSize` / `EngineType` / `Support`)+ `scanRetrieveRows` / `scanCopyRows` / `translateSourceID` / `calculateStorageSize` | -| [internal/application/repository/retriever/doris/streamload.go](../../../internal/application/repository/retriever/doris/streamload.go) | 345 | `partialUpdateRows` + `streamLoadOnce`(HTTP PUT、Basic auth、`partial_columns` / `strip_outer_array` / `merge_type=APPEND` headers、`req.GetBody` 防 307 失体)+ `chunkRows`(1 MiB 自动拆批)+ `BatchUpdateChunkEnabledStatus` / `BatchUpdateChunkTagID` 真实实现 + `lookupChunkRowKeys` | -| [internal/application/repository/retriever/doris/repository_test.go](../../../internal/application/repository/retriever/doris/repository_test.go) | 510 | 基于 `go-sqlmock` + `httptest.Server` 的单测:whereBuilder / embeddingLiteral / chunkRows / partialUpdateRows / DeleteByChunkIDList / VectorRetrieve / KeywordsRetrieve / BatchSave / ensureTable DDL / BatchUpdateChunkEnabledStatus / EngineType+Support / translateSourceID / EstimateStorageSize | -| [scripts/e2e-doris.sh](../../../scripts/e2e-doris.sh) | 73 | 端到端联调 checklist 脚本(`docker compose --profile doris up` 后逐步验证 store 创建 / 写入 / 检索 / 状态批改) | - -### 3.3 修改的现有文件(15 个) - -#### 类型 / 常量层(5 个) - -- **[internal/types/retriever.go](../../../internal/types/retriever.go)**(+1 行):枚举增加 `DorisRetrieverEngineType RetrieverEngineType = "doris"` -- **[internal/types/tenant.go](../../../internal/types/tenant.go)**(+4 行):`retrieverEngineMapping["doris"]` -> `{Keywords, Vector}` -- **[internal/types/vectorstore.go](../../../internal/types/vectorstore.go)**(+80 行): - - `import` 新增 `strconv` - - `validEngineTypes` 收录 `DorisRetrieverEngineType` - - `ConnectionConfig` 新增 `HTTPPort int` / `Database string` - - `IndexConfig` 新增 `BucketsNum int` / `ReplicationNum int` - - `GetIndexNameOrDefault` switch 增加 `case DorisRetrieverEngineType` - - 新增 `(*IndexConfig).GetBucketsNum(def)` / `GetReplicationNum(def)` helper - - `GetVectorStoreTypes()` 追加 doris 项(5 个连接字段 + 3 个索引字段) - - `buildEnvStoreForDriver` 增加 `case "doris"`,读取 `DORIS_ADDR / DORIS_HTTP_PORT / DORIS_DATABASE / DORIS_USERNAME / DORIS_PASSWORD / DORIS_TABLE_PREFIX` 共 6 个环境变量 - - `ValidateIndexConfig` 给 `BucketsNum` / `ReplicationNum` 加 `0..maxShards` / `0..maxReplicas` 边界 -- **[internal/application/service/vectorstore.go](../../../internal/application/service/vectorstore.go)**(+7 行):`validateConnectionConfig` switch 新增 doris 分支(addr / database 必填) -- **[internal/application/service/vectorstore_healthcheck.go](../../../internal/application/service/vectorstore_healthcheck.go)**(+45 行): - - blank import `_ "github.com/go-sql-driver/mysql"` - - `TestConnection` switch 增加 `case types.DorisRetrieverEngineType` - - 新增 `testDorisConnection`(PingContext + `SELECT @@version`,超时 10s) - -#### 装配层(2 个) - -- **[internal/container/engine_factory.go](../../../internal/container/engine_factory.go)**(+52 行): - - import 增加 `database/sql` / `strconv` / `_ "github.com/go-sql-driver/mysql"` / `dorisRepo` - - `createEngineServiceFromStore` switch 增加 `case types.DorisRetrieverEngineType` - - 新增 `createDorisEngine`(拼 DSN + `sql.Open` + 池参数 + `NewDorisRetrieveEngineRepository`)+ `hostFromAddr` 辅助 -- **[internal/container/container.go](../../../internal/container/container.go)**(+49 行): - - import 增加 `_ "github.com/go-sql-driver/mysql"` / `dorisRepo` - - `initRetrieveEngineRegistry` 在 milvus 分支后追加 `slices.Contains(retrieveDriver, "doris")` 分支:读 6 个 `DORIS_*` env -> 构造 `*sql.DB` -> `NewDorisRetrieveEngineRepository(..., nil)` -> `registry.Register` - -#### 测试(2 个) - -- **[internal/types/vectorstore_test.go](../../../internal/types/vectorstore_test.go)**(+90 行): - - `TestBuildEnvVectorStores` 的 envMap 加 6 个 `DORIS_*` 项 - - `all supported drivers` 用例期望从 7 改 8、加 `__env_doris__` 断言 - - 新增 `doris env store` / `doris env store handles invalid http port gracefully` 子测试 - - `TestGetVectorStoreTypes` 期望从 4 改 5、加 `Contains "doris"`、新增 `doris has connection and index fields` 子测试 - - `TestValidateIndexConfig` 加 4 个 doris 子用例(buckets_num 边界 / replication_num 边界 / GetIndexNameOrDefault 默认 / 自定义) -- **[internal/application/service/vectorstore_test.go](../../../internal/application/service/vectorstore_test.go)**(+44 行): - - import 新增 `time` - - `TestValidateConnectionConfig` 表加 3 个 doris 用例(valid / missing addr / missing database) - - 新增 `TestTestConnection_DorisInvalidAddr` / `TestTestConnection_DorisMissingAddr` - -#### 依赖、配置、文档(5 个) - -- **[go.mod](../../../go.mod) / [go.sum](../../../go.sum)**: - - 新增主依赖 `github.com/go-sql-driver/mysql v1.10.0`(间接:`filippo.io/edwards25519`) - - 新增测试依赖 `github.com/DATA-DOG/go-sqlmock v1.5.2` -- **[.env.example](../../../.env.example)**(+21 行):`RETRIEVE_DRIVER` 注释加 `doris`,新增 7 行 `DORIS_*` 环境变量段 -- **[docker-compose.yml](../../../docker-compose.yml)**(+62 行): - - app 服务 `environment:` 段加 6 行 `DORIS_*` 注入 - - 新增 `doris-fe` 服务(`apache/doris:fe-2.1.0`,端口 8030 + 9030,profile: doris) - - 新增 `doris-be` 服务(`apache/doris:be-2.1.0`,端口 8040,profile: doris,depends_on doris-fe) - - `volumes:` 段加 `doris_fe_meta` / `doris_fe_log` / `doris_be_storage` / `doris_be_log` -- **[docs/使用其他向量数据库.md](../../使用其他向量数据库.md)**(+89 行):参考实现列表加 doris 路径;新增 "Apache Doris 4.1 集成说明" 章节(协议 / 表结构 / 索引 / 分数语义 / 关键词检索 / Stream Load / env / 启动方式) -- **[docs/wiki/集成扩展/集成向量数据库.md](../集成扩展/集成向量数据库.md)**(+26 行):参考实现列表加 doris 路径;新增 "Apache Doris 4.1 集成要点" 简版章节 - -### 3.4 整体调用链(rebase 后回归对照图) - -```mermaid -flowchart TD - A["VectorStoreService.CreateStore"] --> B["TestConnection
MySQL Ping + version"] - B --> C["repo.Create"] - C --> D["EngineFactory.createDorisEngine"] - D --> E["sql.Open mysql + http.Client"] - E --> F["NewDorisRetrieveEngineRepository"] - F --> G["NewKVHybridRetrieveEngine"] - G --> H["registry.byStoreID[id] = service"] - - subgraph dorisPkg ["internal/application/repository/retriever/doris"] - R1["repository.go
Save / Retrieve / Delete..."] - R2["schema.go
ensureTable + DDL"] - R3["query.go
filter -> SQL WHERE"] - R4["streamload.go
HTTP partial update"] - end - F --> dorisPkg -``` - -## 四、回归 / 验证清单 - -### 4.1 单元测试 - -```bash -# Doris 包专属单测(go-sqlmock + httptest) -go test ./internal/application/repository/retriever/doris/... -count=1 - -# 类型层测试(含 BuildEnvVectorStores / GetVectorStoreTypes / ValidateIndexConfig 等扩展点) -go test ./internal/types/... -count=1 - -# 服务层 Doris 用例 -go test ./internal/application/service/ -run "Doris|TestConnection|ValidateConnectionConfig" -count=1 -``` - -> 注:`go test ./internal/application/service/...` 中存在若干 `TestCreateStore_*` 是会主动 dial `http://es:9200` 的预先存在用例,无网络环境会失败,与 Doris 改动无关。 - -### 4.2 docker compose 配置自检 - -```bash -docker compose --profile doris config -o /tmp/compose.out -echo $? # 期望 0 -``` - -### 4.3 端到端联调 - -```bash -docker compose --profile doris up -d -docker exec -it WeKnora-doris-fe \ - mysql -h 127.0.0.1 -P 9030 -uroot \ - -e "CREATE DATABASE IF NOT EXISTS weknora;" - -RETRIEVE_DRIVER=doris make run -bash scripts/e2e-doris.sh -``` - -## 五、未来上游若新增引擎,模板化 checklist - -如果上游某次合入了一个新引擎(例如 `chroma`),rebase 时按下面的 checklist 检查每个扩展点是否同时容纳上游 + Doris: - -- [ ] [internal/types/retriever.go](../../../internal/types/retriever.go) 的 `RetrieverEngineType` 枚举:保留 `DorisRetrieverEngineType` -- [ ] [internal/types/tenant.go](../../../internal/types/tenant.go) 的 `retrieverEngineMapping`:保留 `"doris"` key -- [ ] [internal/types/vectorstore.go](../../../internal/types/vectorstore.go) 的 `validEngineTypes`、`GetIndexNameOrDefault` switch、`GetVectorStoreTypes()`、`buildEnvStoreForDriver` switch、`ValidateIndexConfig` 五处:保留 doris 分支 -- [ ] [internal/application/service/vectorstore.go](../../../internal/application/service/vectorstore.go) 的 `validateConnectionConfig` switch:保留 doris 分支 -- [ ] [internal/application/service/vectorstore_healthcheck.go](../../../internal/application/service/vectorstore_healthcheck.go) 的 `TestConnection` switch:保留 `testDorisConnection` 分支 -- [ ] [internal/container/engine_factory.go](../../../internal/container/engine_factory.go) 的 `createEngineServiceFromStore` switch:保留 `createDorisEngine` 分支 -- [ ] [internal/container/container.go](../../../internal/container/container.go) 的 `initRetrieveEngineRegistry`:保留 doris 的 `if slices.Contains(retrieveDriver, "doris")` 块 -- [ ] [docker-compose.yml](../../../docker-compose.yml) 的 app 服务 `environment:` 段保留 6 个 `DORIS_*`;`volumes:` 段保留 `doris_fe_meta` 等;新增的服务定义保留 -- [ ] [.env.example](../../../.env.example) 的 `RETRIEVE_DRIVER` 注释保留 `doris`、`DORIS_*` 段保留 -- [ ] [internal/types/vectorstore_test.go](../../../internal/types/vectorstore_test.go) 中以维度计数的断言(如 `len == 5`、`all supported drivers` 用例):如上游引擎数量也变了,要把数字调整到位,**保留 doris 断言** - -如果 `interfaces.RetrieveEngineRepository`([internal/types/interfaces/retriever.go](../../../internal/types/interfaces/retriever.go))增加方法: - -- [ ] 在 [internal/application/repository/retriever/doris/repository.go](../../../internal/application/repository/retriever/doris/repository.go) 同步实现新方法 -- [ ] 添加对应单测到 [internal/application/repository/retriever/doris/repository_test.go](../../../internal/application/repository/retriever/doris/repository_test.go) - -## 六、不在本次改动范围 - -- TLS 加密连接:先按非加密实现,TLS 走 DSN `tls=skip-verify` 选项后续再加 -- 多租户隔离改造:仍由 `vector_stores` 表的 `tenant_id` 列承担,repository 层无需感知 -- pgvector 风格的 SQL 函数自动注册脚本(Doris 不需要插件) -- 提交 PR 给 Tencent/WeKnora 上游(看是否打算贡献回去再决定) - -## 反向链接 - -- [Home](../Home.md) —— Wiki 首页导航 -- [集成向量数据库](../集成扩展/集成向量数据库.md) —— 通用集成指南 -- [使用其他向量数据库](../../使用其他向量数据库.md) —— 上层版本(含 Doris 完整说明) diff --git a/internal/application/repository/retriever/doris/query.go b/internal/application/repository/retriever/doris/query.go index 9b9d43bb..3c159a72 100644 --- a/internal/application/repository/retriever/doris/query.go +++ b/internal/application/repository/retriever/doris/query.go @@ -1,6 +1,7 @@ package doris import ( + "math" "strconv" "strings" @@ -173,6 +174,33 @@ func parseEmbeddingLiteral(raw []byte) ([]float32, error) { return out, nil } +// validateEmbedding 校验向量元素均为有限值。 +// +// strconv.FormatFloat 对 NaN/±Inf 会输出 "NaN"/"+Inf"/"-Inf", +// 这些字面量会让 Doris 拼出来的 SQL 报语法错误(或在某些版本下产生未定义结果)。 +// 上游(嵌入模型)正常情况下不会输出非有限值,但 GPU OOM、上游 bug、 +// 测试桩都可能触发;这里 fail-fast 比悄悄写脏数据安全。 +func validateEmbedding(vec []float32) error { + for i, v := range vec { + if f := float64(v); math.IsNaN(f) || math.IsInf(f, 0) { + return errInvalidEmbedding{index: i, value: v} + } + } + return nil +} + +// errInvalidEmbedding 描述哪个下标含非有限值;用结构体而非 fmt.Errorf +// 是为了让上层在日志里能拿到下标做问题定位。 +type errInvalidEmbedding struct { + index int + value float32 +} + +func (e errInvalidEmbedding) Error() string { + return "doris: embedding[" + strconv.Itoa(e.index) + + "] is not finite: " + strconv.FormatFloat(float64(e.value), 'g', -1, 32) +} + // embeddingLiteral 把 []float32 转为 Doris ARRAY 字面量字符串: // "[1.23,4.56,...]"。 // diff --git a/internal/application/repository/retriever/doris/repository.go b/internal/application/repository/retriever/doris/repository.go index f55b34fa..e755682e 100644 --- a/internal/application/repository/retriever/doris/repository.go +++ b/internal/application/repository/retriever/doris/repository.go @@ -74,14 +74,10 @@ func (r *dorisRepository) EstimateStorageSize(_ context.Context, return total } -// Save 写入单条记录到对应维度的表。 +// Save 写入单条记录到对应维度的表。空向量在 BatchSave 内部统一拒绝。 func (r *dorisRepository) Save(ctx context.Context, info *types.IndexInfo, additionalParams map[string]any, ) error { - emb := toDorisVectorEmbedding(info, additionalParams) - if len(emb.Embedding) == 0 { - return fmt.Errorf("empty embedding vector for chunk ID: %s", info.ChunkID) - } return r.BatchSave(ctx, []*types.IndexInfo{info}, additionalParams) } @@ -102,6 +98,9 @@ func (r *dorisRepository) BatchSave(ctx context.Context, log.Warnf("[Doris] Skipping empty embedding for chunk %s", info.ChunkID) continue } + if err := validateEmbedding(emb.Embedding); err != nil { + return fmt.Errorf("invalid embedding for chunk %s: %w", info.ChunkID, err) + } // 给一个稳定的主键。SourceID 是上层最有意义的"行身份", // 但同 chunk 多 question 的场景下 SourceID 已经唯一,所以直接用它。 if emb.ID == "" { @@ -226,6 +225,9 @@ func (r *dorisRepository) VectorRetrieve(ctx context.Context, params types.RetrieveParams, ) ([]*types.RetrieveResult, error) { log := logger.GetLogger(ctx) + if err := validateEmbedding(params.Embedding); err != nil { + return nil, fmt.Errorf("invalid query embedding: %w", err) + } dim := len(params.Embedding) table := r.getTableName(dim) @@ -477,12 +479,12 @@ func scanRetrieveRows(rows *sql.Rows, matchType types.MatchType) ([]*types.Index var out []*types.IndexWithScore for rows.Next() { var ( - id, content, sourceID, chunkID string - knowledgeID, knowledgeBaseID, tagID string - sourceType int - isEnabled bool - score float64 - err error + id, content, sourceID, chunkID string + knowledgeID, knowledgeBaseID, tagID string + sourceType int + isEnabled bool + score float64 + err error ) if withScore { err = rows.Scan(&id, &content, &sourceID, &sourceType, diff --git a/internal/application/repository/retriever/doris/repository_test.go b/internal/application/repository/retriever/doris/repository_test.go index 00914772..ec86e9bb 100644 --- a/internal/application/repository/retriever/doris/repository_test.go +++ b/internal/application/repository/retriever/doris/repository_test.go @@ -11,6 +11,7 @@ import ( "regexp" "strings" "testing" + "time" "github.com/DATA-DOG/go-sqlmock" "github.com/Tencent/WeKnora/internal/types" @@ -382,7 +383,10 @@ func TestEnsureTable_DDLShape(t *testing.T) { ) require.NoError(t, repo.ensureTable(context.Background(), 768)) - assert.NoError(t, mock.ExpectationsWereMet()) + // waitANNReady 在后台 goroutine 里执行,轮询 ExpectationsWereMet 直到 SHOW INDEX 也被消费。 + require.Eventually(t, func() bool { + return mock.ExpectationsWereMet() == nil + }, 2*time.Second, 10*time.Millisecond, "expectations should be met after async ANN poll") } func TestBatchSave_SQLShape(t *testing.T) { diff --git a/internal/application/repository/retriever/doris/schema.go b/internal/application/repository/retriever/doris/schema.go index 52dd0928..c599914a 100644 --- a/internal/application/repository/retriever/doris/schema.go +++ b/internal/application/repository/retriever/doris/schema.go @@ -55,12 +55,22 @@ func (r *dorisRepository) ensureTable(ctx context.Context, dimension int) error return fmt.Errorf("create table: %w", err) } - // 创建表后等一会让 ANN 索引就绪,超时不致命。 - if err := r.waitANNReady(ctx, tableName); err != nil { - log.Warnf("[Doris] ANN index for %s not ready within %s: %v "+ - "(writes will still proceed; queries may fall back to brute force temporarily)", - tableName, annReadyTimeout, err) - } + // ANN 索引在 Doris 端异步构建。这里在后台 goroutine 里轮询就绪, + // 写入路径不阻塞——索引未就绪期间检索会退化为 brute-force(结果对、速度慢), + // 比让首批写入卡 30s 更可接受。 + go func(tn string) { + // 用独立 context(带 timeout),避免请求级 ctx 取消把后台轮询也带走。 + bgCtx, cancel := context.WithTimeout(context.Background(), annReadyTimeout) + defer cancel() + if err := r.waitANNReady(bgCtx, tn); err != nil { + logger.GetLogger(bgCtx).Warnf( + "[Doris] ANN index for %s not ready within %s: %v "+ + "(queries may fall back to brute force temporarily)", + tn, annReadyTimeout, err) + return + } + logger.GetLogger(bgCtx).Infof("[Doris] ANN index for %s ready", tn) + }(tableName) } r.initializedTables.Store(dimension, true) @@ -199,7 +209,6 @@ func (r *dorisRepository) annIndexReady(ctx context.Context, tableName string) ( } } - foundANN := false for rows.Next() { // 使用 sql.RawBytes 接收以兼容不同列类型。 raw := make([]any, len(cols)) @@ -222,7 +231,6 @@ func (r *dorisRepository) annIndexReady(ctx context.Context, tableName string) ( if keyName != "idx_emb" { continue } - foundANN = true if stateIdx < 0 { // 旧版本不暴露 state 列,乐观认为已就绪。 return true, nil @@ -235,11 +243,10 @@ func (r *dorisRepository) annIndexReady(ctx context.Context, tableName string) ( if err := rows.Err(); err != nil { return false, err } - - if !foundANN { - // 没找到 ANN 行(可能是 Doris 版本返回字段不同),不阻塞。 - return true, nil - } + // 走到这里有两种情况: + // 1. 找到了 idx_emb 行,且 state 已是 FINISHED/NORMAL(或 stateIdx<0 的旧版本); + // 2. 没找到 idx_emb 行(极旧 Doris 不暴露该索引名); + // 都视为已就绪,不阻塞。未就绪的分支已在循环内提前 return false。 return true, nil } diff --git a/internal/application/service/vectorstore_healthcheck.go b/internal/application/service/vectorstore_healthcheck.go index f48e2826..6fa76bd6 100644 --- a/internal/application/service/vectorstore_healthcheck.go +++ b/internal/application/service/vectorstore_healthcheck.go @@ -8,13 +8,14 @@ import ( "io" "net" "net/http" + "strings" "time" "github.com/Tencent/WeKnora/internal/errors" "github.com/Tencent/WeKnora/internal/logger" "github.com/Tencent/WeKnora/internal/types" - _ "github.com/go-sql-driver/mysql" // MySQL driver for database/sql, used by Doris connection test - _ "github.com/jackc/pgx/v5/stdlib" // pgx driver for database/sql + "github.com/go-sql-driver/mysql" // MySQL driver for database/sql, used by Doris connection test + _ "github.com/jackc/pgx/v5/stdlib" // pgx driver for database/sql "github.com/qdrant/go-client/qdrant" "github.com/weaviate/weaviate-go-client/v5/weaviate" "github.com/weaviate/weaviate-go-client/v5/weaviate/auth" @@ -233,8 +234,9 @@ func testWeaviateConnection(ctx context.Context, config types.ConnectionConfig) // testDorisConnection 通过 MySQL 协议(database/sql + go-sql-driver) // Ping Doris FE 并查询 @@version。 // -// Doris 4.1 的 @@version 形如 "5.7.99 Doris-4.1.0"——前半段是兼容性表达式, -// 后半段才是真正的 Doris 版本号。这里直接返回原样字符串,由调用方按需展示。 +// Doris 的 @@version 形如 "5.7.99 Doris-4.1.0"——前半段是 MySQL 协议 +// 兼容性表达式,"Doris-" 之后才是真实版本号。统一只返回 "4.1.0" 这类 +// 裸版本号,与 Postgres/ES 路径的格式保持一致。 func testDorisConnection(ctx context.Context, config types.ConnectionConfig) (string, error) { testCtx, cancel := context.WithTimeout(ctx, connectionTestTimeout) defer cancel() @@ -249,9 +251,16 @@ func testDorisConnection(ctx context.Context, config types.ConnectionConfig) (st database = "information_schema" } - dsn := fmt.Sprintf("%s:%s@tcp(%s)/%s?timeout=5s", - config.Username, config.Password, config.Addr, database) - db, err := sql.Open("mysql", dsn) + // 用 mysql.Config.FormatDSN() 构造 DSN,避免用户名/密码中 `@` `:` `/` + // 等特殊字符破坏字面量拼接(fmt.Sprintf 会跑偏,参考 issue #1234 类问题)。 + cfg := mysql.NewConfig() + cfg.User = config.Username + cfg.Passwd = config.Password + cfg.Net = "tcp" + cfg.Addr = config.Addr + cfg.DBName = database + cfg.Timeout = 5 * time.Second + db, err := sql.Open("mysql", cfg.FormatDSN()) if err != nil { return "", errors.NewBadRequestError("failed to create doris connection: invalid configuration") } @@ -267,5 +276,8 @@ func testDorisConnection(ctx context.Context, config types.ConnectionConfig) (st logger.Warnf(ctx, "Doris version detection failed: %v", err) return "", nil } + if i := strings.Index(version, "Doris-"); i >= 0 { + return strings.TrimSpace(version[i+len("Doris-"):]), nil + } return version, nil } diff --git a/internal/container/engine_factory.go b/internal/container/engine_factory.go index 86880aa4..c6339388 100644 --- a/internal/container/engine_factory.go +++ b/internal/container/engine_factory.go @@ -10,7 +10,7 @@ import ( esv7 "github.com/elastic/go-elasticsearch/v7" "github.com/elastic/go-elasticsearch/v8" - _ "github.com/go-sql-driver/mysql" // 通过 database/sql 注册 mysql 驱动给 Doris 使用 + "github.com/go-sql-driver/mysql" // 通过 database/sql 注册 mysql 驱动给 Doris 使用 "github.com/milvus-io/milvus/client/v2/milvusclient" "github.com/qdrant/go-client/qdrant" "github.com/weaviate/weaviate-go-client/v5/weaviate" @@ -228,9 +228,16 @@ func createDorisEngine(store types.VectorStore) (interfaces.RetrieveEngineServic return nil, fmt.Errorf("doris connection requires database") } - dsn := fmt.Sprintf("%s:%s@tcp(%s)/%s?charset=utf8mb4&parseTime=true&loc=Local", - cc.Username, cc.Password, cc.Addr, cc.Database) - db, err := sql.Open("mysql", dsn) + mc := mysql.NewConfig() + mc.User = cc.Username + mc.Passwd = cc.Password + mc.Net = "tcp" + mc.Addr = cc.Addr + mc.DBName = cc.Database + mc.Params = map[string]string{"charset": "utf8mb4"} + mc.ParseTime = true + mc.Loc = time.Local + db, err := sql.Open("mysql", mc.FormatDSN()) if err != nil { return nil, fmt.Errorf("create doris client: %w", err) } diff --git a/scripts/e2e-doris.sh b/scripts/e2e-doris.sh deleted file mode 100755 index e5ddf01a..00000000 --- a/scripts/e2e-doris.sh +++ /dev/null @@ -1,73 +0,0 @@ -#!/usr/bin/env bash -# Doris 4.1 端到端联调脚本 -# -# 该脚本验证: -# 1) 后端启动正常 -# 2) 通过 API 创建 Doris VectorStore -# 3) 上传知识、写入索引 -# 4) 向量检索 + 关键词检索 -# 5) 关闭单个 chunk 后再检索(验证 BatchUpdateChunkEnabledStatus 走 Stream Load) -# -# 使用前置条件: -# - docker compose --profile doris up -d 先把 Doris 起来 -# - 在 FE 上 CREATE DATABASE weknora; -# - export RETRIEVE_DRIVER=doris && make run (或 docker compose up app) -# -# 这是"checklist-as-script",按需要手动逐段执行。 -set -euo pipefail - -WEKNORA_API="${WEKNORA_API:-http://localhost:8080}" -DORIS_FE_HOST="${DORIS_FE_HOST:-127.0.0.1}" -DORIS_FE_HTTP_PORT="${DORIS_FE_HTTP_PORT:-8030}" -DORIS_FE_MYSQL_PORT="${DORIS_FE_MYSQL_PORT:-9030}" - -step() { printf '\n\033[1;36m==> %s\033[0m\n' "$*"; } - -step "1. 检查 Doris FE 端口可达" -nc -zv "$DORIS_FE_HOST" "$DORIS_FE_HTTP_PORT" -nc -zv "$DORIS_FE_HOST" "$DORIS_FE_MYSQL_PORT" - -step "2. 在 FE 上确认 weknora 库存在" -docker exec WeKnora-doris-fe \ - mysql -h 127.0.0.1 -P 9030 -uroot \ - -e "CREATE DATABASE IF NOT EXISTS weknora; SHOW DATABASES;" - -step "3. 通过 WeKnora API 创建 Doris VectorStore" -curl -fsS -X POST "$WEKNORA_API/api/v1/vector-stores" \ - -H 'Content-Type: application/json' \ - -d '{ - "name": "doris-local", - "engine_type": "doris", - "connection_config": { - "addr": "doris-fe:9030", - "http_port": 8030, - "database": "weknora", - "username": "root", - "password": "" - }, - "index_config": { - "collection_prefix": "weknora_embeddings", - "buckets_num": 5, - "replication_num": 1 - } - }' - -step "4. 上传一个简单知识库(这一步交给前端 UI 完成更省事)" -echo "在前端 UI 切到刚才创建的 Doris VectorStore,新建知识库并上传一篇 PDF。" -echo "或者用 curl + /api/v1/knowledges 调用 API。" - -step "5. 在 FE 上验证表已建好" -docker exec WeKnora-doris-fe \ - mysql -h 127.0.0.1 -P 9030 -uroot \ - -e "USE weknora; SHOW TABLES LIKE 'weknora_embeddings_%'; SHOW INDEX FROM weknora_embeddings_768;" - -step "6. 检索验证" -echo "在前端发起检索(向量 + 关键词),确认有命中。" -echo "命中后到 FE 上查 SELECT COUNT(*) FROM weknora_embeddings_;" - -step "7. 状态批改验证" -echo "在前端把某个 chunk 关闭,再次发起检索,确认该 chunk 不再返回。" -echo "FE 上确认 SELECT id, is_enabled FROM weknora_embeddings_ WHERE chunk_id = '';" - -echo -echo "全部步骤完成 → 联调通过"