Files
Enterprise-Knowledge-Base/internal/application/repository/retriever/doris/query.go
T
issunion 4cce6f2e99 feat(retriever): 接入 Apache Doris 4.1 作为向量数据库
为 RetrieveEngine 体系新增 Doris 后端,与现有 Qdrant/Milvus/Weaviate
等保持完整能力对齐:向量检索、关键词检索、健康检查、环境变量与多实例
DB 配置、前端类型注册、单元测试、Docker Compose 模板。

实现要点:
- 协议分工:主链路用 MySQL 协议(database/sql + go-sql-driver/mysql)
  做 DDL / 查询 / 删除;批量更新走 Stream Load HTTP API,并启用
  partial_update=true、merge_type=APPEND,自动按 1MiB 切分批次并处理
  307 重定向。
- 表结构:UNIQUE KEY(id) + enable_unique_key_merge_on_write=true 以
  支持 upsert/部分列更新;按维度分表(<base>_<dim>),每张表上建
  HNSW ANN 索引(metric_type=cosine_distance)和 INVERTED 索引
  (parser=chinese)。
- 分数语义:使用 cosine_distance_approximate,再以 1 - dist 转换为
  "越大越相似",与现有 KVHybridRetrieveEngine 约定一致。
- 异步索引:ANN 索引为后台构建,ensureTable 通过轮询 SHOW INDEX 等
  待索引就绪后再放行写入,避免首次检索召回为空。
- ARRAY<FLOAT> 序列化:go-sql-driver/mysql 不支持数组占位符,
  embeddingLiteral 将 []float32 转成 SQL 字面量字符串再拼接。

新增文件:
- internal/application/repository/retriever/doris/{structs,schema,
  query,repository,streamload,repository_test}.go
- scripts/e2e-doris.sh:E2E 验证清单
- docs/wiki/集成扩展/Doris改动与上游同步.md:fork-and-rebase 工作流
  与改动清单

修改文件(接线 + 文档):
- internal/types/{retriever,tenant,vectorstore}.go:新增
  DorisRetrieverEngineType、env 解析、表单 schema 与索引参数校验
- internal/container/{container,engine_factory}.go:环境变量驱动
  与 VectorStore 配置驱动两条路径都支持 Doris
- internal/application/service/vectorstore{,_healthcheck}.go:连接
  校验 + Ping/Version 健康检查
- docker-compose.yml:新增 doris-fe / doris-be 服务(profile=doris)
- .env.example:DORIS_* 环境变量与示例
- docs/{使用其他向量数据库,wiki/集成扩展/集成向量数据库}.md:
  使用说明与索引/分数行为说明

依赖:go.mod/go.sum 新增 github.com/go-sql-driver/mysql(运行时)和
github.com/DATA-DOG/go-sqlmock(测试)。

测试:repository 层 SQL 形状、Stream Load HTTP 行为、whereBuilder
逻辑、embeddingLiteral 往返、健康检查错误路径均有单测覆盖。
2026-05-08 21:59:35 +08:00

203 lines
6.0 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
package doris
import (
"strconv"
"strings"
"github.com/Tencent/WeKnora/internal/types"
)
// 字段名常量。Doris 是 SQL 库,字段名要在 SELECT/WHERE/INSERT 多处复用,
// 用常量统一防止笔误。
const (
fieldID = "id"
fieldContent = "content"
fieldSourceID = "source_id"
fieldSourceType = "source_type"
fieldChunkID = "chunk_id"
fieldKnowledgeID = "knowledge_id"
fieldKnowledgeBaseID = "knowledge_base_id"
fieldTagID = "tag_id"
fieldIsEnabled = "is_enabled"
fieldEmbedding = "embedding"
)
// columns 是 INSERT / SELECT 时使用的标准列序。
var columns = []string{
fieldID, fieldContent, fieldSourceID, fieldSourceType,
fieldChunkID, fieldKnowledgeID, fieldKnowledgeBaseID, fieldTagID,
fieldIsEnabled, fieldEmbedding,
}
// columnsForRetrieve 是 Retrieve 时 SELECT 的列序,
// 不包含 embedding(向量本身查询结果中无需返回,省带宽)。
var columnsForRetrieve = []string{
fieldID, fieldContent, fieldSourceID, fieldSourceType,
fieldChunkID, fieldKnowledgeID, fieldKnowledgeBaseID, fieldTagID,
fieldIsEnabled,
}
// columnsForCopy 是 CopyIndices 中分页 SELECT 时使用的列序,
// 比 columnsForRetrieve 多 embedding,因为复制目的是搬运向量本身。
var columnsForCopy = []string{
fieldID, fieldContent, fieldSourceID, fieldSourceType,
fieldChunkID, fieldKnowledgeID, fieldKnowledgeBaseID, fieldTagID,
fieldIsEnabled, fieldEmbedding,
}
// whereCond 表示一个 WHERE 子条件:clause 是参数化 SQL 片段(带 ? 占位),
// args 是对应顺序的参数值。所有用户输入字段(IDs)必须通过 args 传入,
// 严禁拼到 clause 字符串里。
type whereCond struct {
clause string
args []any
}
// whereBuilder 用于把 RetrieveParams 中的过滤条件翻译成 SQL WHERE 子句。
//
// 每个 add* 方法对应一种 IN / NOT IN / = 算子;最终 build() 用 AND 拼接。
type whereBuilder struct {
conds []whereCond
}
// addEqual 追加一个 field = ? 条件。
func (w *whereBuilder) addEqual(field string, value any) {
w.conds = append(w.conds, whereCond{
clause: field + " = ?",
args: []any{value},
})
}
// addIn 追加一个 field IN (?, ?, ...) 条件。values 为空时不追加任何东西。
func (w *whereBuilder) addIn(field string, values []string) {
if len(values) == 0 {
return
}
placeholders := make([]string, len(values))
args := make([]any, len(values))
for i, v := range values {
placeholders[i] = "?"
args[i] = v
}
w.conds = append(w.conds, whereCond{
clause: field + " IN (" + strings.Join(placeholders, ", ") + ")",
args: args,
})
}
// addNotIn 追加一个 field NOT IN (?, ?, ...) 条件。
func (w *whereBuilder) addNotIn(field string, values []string) {
if len(values) == 0 {
return
}
placeholders := make([]string, len(values))
args := make([]any, len(values))
for i, v := range values {
placeholders[i] = "?"
args[i] = v
}
w.conds = append(w.conds, whereCond{
clause: field + " NOT IN (" + strings.Join(placeholders, ", ") + ")",
args: args,
})
}
// build 返回 WHERE 子句(不含 "WHERE " 前缀)和参数数组。
// 没有任何条件时返回 ("1 = 1", nil),方便调用方无脑拼接。
func (w *whereBuilder) build() (string, []any) {
if len(w.conds) == 0 {
return "1 = 1", nil
}
parts := make([]string, len(w.conds))
var args []any
for i, c := range w.conds {
parts[i] = c.clause
args = append(args, c.args...)
}
return strings.Join(parts, " AND "), args
}
// buildBaseFilter 将 RetrieveParams 中的过滤条件翻译为 whereBuilder。
// 默认追加 is_enabled = TRUE,与 Qdrant/Milvus/Weaviate 保持一致:
// 关闭的 chunk 不参与检索。
func buildBaseFilter(params types.RetrieveParams) *whereBuilder {
w := &whereBuilder{}
w.addEqual(fieldIsEnabled, true)
if len(params.KnowledgeBaseIDs) > 0 {
w.addIn(fieldKnowledgeBaseID, params.KnowledgeBaseIDs)
}
if len(params.KnowledgeIDs) > 0 {
w.addIn(fieldKnowledgeID, params.KnowledgeIDs)
}
if len(params.TagIDs) > 0 {
w.addIn(fieldTagID, params.TagIDs)
}
if len(params.ExcludeKnowledgeIDs) > 0 {
w.addNotIn(fieldKnowledgeID, params.ExcludeKnowledgeIDs)
}
if len(params.ExcludeChunkIDs) > 0 {
w.addNotIn(fieldChunkID, params.ExcludeChunkIDs)
}
return w
}
// parseEmbeddingLiteral 解析 Doris ARRAY<FLOAT> 通过 MySQL 协议返回的
// 字面量字符串(形如 "[1,2,3]")为 []float32。
//
// CopyIndices 路径需要从源行读出向量本身再写回目标行;此处的解析容错优先:
// 不带 [] 也接受、空数组返回 nil。
func parseEmbeddingLiteral(raw []byte) ([]float32, error) {
s := strings.TrimSpace(string(raw))
if s == "" {
return nil, nil
}
s = strings.TrimPrefix(s, "[")
s = strings.TrimSuffix(s, "]")
if s == "" {
return nil, nil
}
parts := strings.Split(s, ",")
out := make([]float32, 0, len(parts))
for _, p := range parts {
p = strings.TrimSpace(p)
if p == "" {
continue
}
f, err := strconv.ParseFloat(p, 32)
if err != nil {
return nil, err
}
out = append(out, float32(f))
}
return out, nil
}
// embeddingLiteral 把 []float32 转为 Doris ARRAY<FLOAT> 字面量字符串:
// "[1.23,4.56,...]"。
//
// 为何不用占位符:go-sql-driver/mysql 不支持 ARRAY 类型的参数绑定,
// Doris 端也只接受字面量形式。这里用 strconv.FormatFloat('g' + bitSize=32)
// 而不是 fmt.Sprintf("%f", v),原因有二:
// 1. fmt 在某些 locale 下会用千分位分隔符,破坏 SQL 语法;
// 2. 'g' 比 'f' 短且不会丢精度。
//
// 注入风险:[]float32 元素是嵌入模型输出的有限位数浮点数,序列化后只可能
// 包含 [0-9eE+-.\s] 字符,不会逃逸出字面量上下文。
func embeddingLiteral(vec []float32) string {
if len(vec) == 0 {
return "[]"
}
var sb strings.Builder
sb.Grow(len(vec) * 12)
sb.WriteByte('[')
for i, v := range vec {
if i > 0 {
sb.WriteByte(',')
}
sb.WriteString(strconv.FormatFloat(float64(v), 'g', -1, 32))
}
sb.WriteByte(']')
return sb.String()
}