SparkTide · 启澜

切换主题

向量与混合检索 ​

本页阅读位置

完成第一轮对话后，按当前业务需求深入。Spring 常规声明优先使用 RegistrationManifest 与注解；本页的底层 register / publish 或直连方法供协议细化与兼容集成参考。

选择检索方式 ​

方式配置行为与适用范围
词项不配置 retrieval，或 strategy=LEXICAL不调用 Embedding，适合明确词项；英文词项与中文双字匹配
向量strategy=VECTOR使用配置服务的真实嵌入与精确余弦排名，支持模型具备的语义能力
混合strategy=HYBRID词项、向量分别排名后按 RRF(k=60)融合，同一分块只保留一份
外部知识mode=REMOTE已有向量库、复杂 RAG 或大容量服务仍通过外部知识协议接入

默认数据库实现采用精确扫描，不要求 pgvector，也不声称无限规模或 ANN 性能。EmbeddingProvider 与 VectorStore 是独立替换端口；部署一个自定义实现时应只提供一个相应 Spring Bean，并保持相同权限、规范化和事务合同。更换存储实现还须同步迁移、容量和发布验证，不能仅替换查询而跳过发布完整性。

服务配置与数据边界 ​

选择一个实现 OpenAI Embeddings HTTP 合同的服务，确认其模型输出维度及正文可发送范围。运营者把精确 origin 放入 SPARKTIDE_ALLOWED_ORIGINS；密钥以服务端 Secret 引用绑定 origin 和应用，不能放在定义或 SDK 配置中。生产使用 HTTPS，本地明确允许 HTTP 的环境可联调。

输入使用 model、字符串数组 input 和 encoding_format=float；仅服务支持时启用 sendDimensions。返回按 data/index 对应输入，每个 embedding 必须是指定维度、有限数值与非零模长。平台规范化后存储；模型名称不同、缺行、重复编号、维度错误、畸形或过大响应都拒绝。合同依据：官方接口说明。

构建会向明确配置的服务发送当前调用者可读正文，检索会发送用户问题。不会发送平台 Bearer、业务用户身份、其他租户正文或当前不可读文档。Embedding 供应商独立计费；当前聊天额度和模型调用账本不代替其费用控制，请在供应商配置预算与访问限制。平台不自动重试这些请求，也不以向量查询成功声明模型效果或供应商 SLA。

管理页面操作 ​

  1. 新建一个托管知识草稿，选择分块策略，导入文本或等待文件摄入成功。
  2. 在能力配置中选择“向量余弦检索”或“词项与向量混合检索”，填写 Embedding 地址、模型、空间版本、维度与密钥引用。保存。
  3. 打开“管理托管文档”，在“向量索引”中点击“构建当前可读向量”；必要时填写本次文档标识以分批构建。
  4. 刷新任务与索引，确认任务 SUCCEEDED、当前可读向量就绪。FAILED 展示分类错误，可按当前身份、配置和正文创建新的重试任务；活动任务可取消。
  5. 用“检索调试”检查实际命中、得分及来源；使用自己的固定问题集比较旧/新版本。
  6. 完成所有租户/文档索引后发布知识版本，再将精确版本加入 Agent.allowedKnowledge。活动任务或缺失/过期向量会阻止单件发布与批次发布。

管理身份仍受正文 ACL 与租户约束。包含多个受限租户的知识版本，可由各租户有权管理且可读正文的身份分批构建；“当前可读就绪”不等于整个知识版本已就绪，最终发布会核定全部文档。业务身份可查看自己可读索引健康与检索；不能创建或管理任务。

SDK 示例 ​

java
var retrieval = KnowledgeRetrieval.hybrid(
    URI.create("https://embedding.example/v1/embeddings"),
    "your-embedding-model", "model-revision-1", 768,
    "EMBEDDING_KEY", false, 0.1
);
var definition = Map.<String,Object>of(
    "mode", "MANAGED",
    "chunking", Map.of("strategy", "PARAGRAPH", "maxChars", 2000),
    "retrieval", retrieval.definition()
);
client.register("knowledge", "project-documents", "2.0.0", definition)
      .toCompletableFuture().get();
client.ingest("project-documents", "2.0.0",
    Map.of("id", "operations", "text", "业务系统部署与运维正文"))
      .toCompletableFuture().get();
var job = client.buildVectors("project-documents", "2.0.0", List.of("operations"))
                .toCompletableFuture().get();
var latest = client.vectorJob("project-documents", "2.0.0", (String)job.get("id"))
                   .toCompletableFuture().get();
// 排队/构建中请以应用自己的轮询期限等待；只有 SUCCEEDED 才是本次成功。
var health = client.vectorHealth("project-documents", "2.0.0")
                   .toCompletableFuture().get();
kotlin
val retrieval = hybridKnowledge(
    endpoint = URI("https://embedding.example/v1/embeddings"),
    model = "your-embedding-model", spaceVersion = "model-revision-1",
    dimensions = 768, secretRef = "EMBEDDING_KEY", minScore = 0.1
)
client.register("knowledge", "project-documents", "2.0.0", mapOf(
    "mode" to "MANAGED", "retrieval" to retrieval.definition()
)).awaitResult()
val job = client.buildVectorsAwait("project-documents", "2.0.0", listOf("operations"))
val latest = client.vectorJobAwait("project-documents", "2.0.0", job["id"] as String)
val health = client.vectorHealthAwait("project-documents", "2.0.0")

Java 示例说明：

示例地址、模型、768 维及密钥名称是需要替换的配置，占位地址不会自动可用。选择与实际服务匹配的维度。List.of() 表示本次全部可读文档，仍须满足任务分块上限；失败应先检查配置/访问，再显式重试。

Kotlin 示例说明：

Kotlin 示例先通过文本导入、批次导入或文件摄入准备 operations 文档。Java 与 Kotlin 使用同一不可变配置和公开接口；不会把 SDK 管理身份当成浏览器身份。

API、状态与限额 ​

路径前缀：/v1/apps/{app}/knowledge/{knowledgeId}/versions/{version}/vectors。

方法与后缀用途约束
GET 前缀当前可读索引健康租户/ACL/业务权限；不返回向量正文
POST /jobs排队构建管理角色、草稿；body={} 或 documentIds
GET /jobs分页任务管理角色；limit=1–20、offset≤1000000
GET /jobs/实际状态与错误管理角色；不包含私有身份或来源正文
POST /jobs/{jobId}/cancel取消排队/构建If-Match 当前修订
POST /jobs/{jobId}/retry失败后重新规划If-Match；返回新任务，保留旧错误证据
DELETE /jobs/清理终态记录If-Match；活动索引引用时拒绝，撤销版本才可同时清理关联向量

一次最多 512 分块、每批 8 输入、每片或问题≤8192 UTF-16 字符、维度 1–2048；单调用最长 15 秒、任务最长 600 秒、每实例一个构建线程。每知识版本仅一个活动构建，任务历史最多 10000 件。向量持久容量默认 64 MiB，配置 SPARKTIDE_VECTORS_CAPACITY_BYTES 可在 1 MiB–1 GiB 内调整。容量不足拒绝新提交，不删除或部分替换现有向量。运行/工作台保留各自已有并发与期限限制；对高容量知识选择外部服务并实测其性能。

模型空间、更改与失败处理 ​

spaceHash 绑定完整 Embedding 配置；模型、服务、spaceVersion、维度或请求维度配置变化后，原向量不再视为当前索引。同名模型被供应商升级时，必须主动更新 spaceVersion，不能靠相同维度复用。草稿正文和分块策略变化同样使向量过期。已发布版本冻结，切换应新建知识版本并重建，旧版本可用于恢复新请求。

只有全部选定分块成功，且最终定义、正文、当前 ACL/业务授权、任务所有权与期限均通过，才在短事务里替换所选文档向量；失败、超时、取消或丢失 worker 不替换部分索引。重试创建新的任务并重新捕获当前输入，不自动恢复或重复原调用。

VECTOR_INDEX_NOT_READY 请先构建当前配置；EMBEDDING_PROTOCOL_ERROR 检查维度与响应；EMBEDDING_AUTH_FAILED 检查服务端 Secret 授权；EMBEDDING_RATE_LIMITED/EMBEDDING_UNAVAILABLE 排查供应商限制并明确再试；VECTOR_WORKER_LOST 先确认旧 worker 已退出，再显式重试。当前身份不能读取正文时，调整真实授权或切换有权业务身份，不能用管理员绕过。

效果评测与恢复 ​

调试及评测中分别显示 LEXICAL_TERMS_V1、COSINE_V1、RRF_LEXICAL_COSINE_V1。余弦阈值允许 −1..1，混合得分不是余弦概率；实际语义效果取决于模型与业务问题集。评测将算法、空间、文档和向量摘要绑定知识版本，索引变化后标记历史过时。权限收回后历史详情拒绝显示来源相关结果。

参考知识检索调试与版本评测保存固定问题集。升级新增 V15，备份须包含 Registry、文档、ACL、向量和任务；回退时先将新请求指向旧发布知识/Agent 版本，停止向量任务，保留数据库迁移。旧平台不能执行含 retrieval 的新定义，不通过改写发布版本回退。

文档来源与验证记录
字段内容
状态已确认
日期2026-10-01
来源VectorRetrieval、EmbeddingProvider、VectorStore、VectorIngestion、V15 与 Java/Kotlin SDK
责任人SparkTide 维护者
关联任务完整产品落地 K02
结论托管知识可选词项、精确余弦或混合排名；先构建并确认完整索引，再发布给智能体
证据平台 clean build 189 项、后台 SDK 实际隔离联调 clean build 99 项全部通过；PostgreSQL V14→V15、重启保留、撤权、实际管理页面配置与重试、版本指标和聊天引用通过
适用版本：0.1 发布线 · 最近核对：2026-10-09 · SparkTide 产品文档

汇聚智能，驱动涌现。

SparkTide · 启澜产品文档 · 0.1 发布线