indexer

package
v2.0.18 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 2, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package indexer 定义索引器的接口与实现。

本文件实现 GraphIndexer：图索引器，职责单一化为「图结构化」。

设计要点：

  • 不做分块（Chunker 由 HyperIndexer 调用；独立使用时 AddFile 内部调用 Chunker）
  • 不做向量化（SemanticIndexer 负责）
  • 只持有 GraphStore，从 doc.Nodes()/Edges() 读取实体/关系并写入
  • Chunk 不作为 Node 写入 GraphStore
  • 不实现 IndexerAdmin（Chunk 管理由 SemanticIndexer 通过 VectorStore 负责）

Package indexer 定义索引器的接口与实现。

本文件定义 indexer 包对外的 6 个核心接口（参考 io 包的小接口组合风格）：

  • Indexer 核心接口：Name / AddFile / Search / NewQuery（所有索引器必实现）
  • IndexerStore 存储接口：Save（各 Indexer 实现自动路由到各自存储）
  • IndexerAdmin 管理接口：List / GetChunks / Count / Remove / Clear
  • IndexerCloser 资源管理接口：Close
  • TreeViewBuilder 导航接口：Tree（仅 HyperIndexer 实现）
  • GraphSearcher 图查询接口：SearchGraph（仅 GraphIndexer 实现）

设计要点：

  • 接口分离原则（ISP）：调用方按需 type-assert，不依赖不需要的方法
  • 组合优于继承：HyperIndexer 通过组合 SemanticIndexer + GraphIndexer 实现双线协同
  • 只支持文件输入：Indexer 职责单一化为「索引文件」，所有内容必须通过 AddFile 索引
  • Hit 与 StructuredDoc 对称：StructuredDoc 是索引过程容器，Hit 是检索过程容器
  • StructuredDoc 类型定义在 core 包，indexer 包不依赖 structurizer 包

Index

Constants

View Source 
const (
	StrategyRecursive = "recursive"
	StrategyParagraph = "paragraph"
	StrategySentence  = "sentence"
	StrategyCode      = "code"
	StrategyParentDoc = "parent_doc"
)

分块策略常量。

Variables

This section is empty.

Functions

func GetChunks 

func GetChunks(content string, opts ...ChunkOption) ([]*core.Chunk, error)

GetChunks 根据文本内容进行结构化和分块。 如果没有指定策略，会根据内容自动选择最佳分块策略，返回完整的分块数组。

func GetFileChunks 

func GetFileChunks(file string, opts ...ChunkOption) ([]*core.Chunk, error)

GetFileChunks 根据文件路径进行结构化和分块。 如果没有指定策略，会根据内容自动选择最佳分块策略，返回完整的分块数组。

func RegionIDFromContext added in v2.0.3 

func RegionIDFromContext(ctx context.Context) string

RegionIDFromContext 从 context 中提取 region ID，未设置时返回空字符串。

func WithRegionID added in v2.0.3 

func WithRegionID(ctx context.Context, regionID string) context.Context

WithRegionID 将 region ID 附加到 context。 传递给 AddFile / Save 时，相关元数据会携带此 region_id。

Types

type ChunkOption 

type ChunkOption func(*chunkOption)

ChunkOption 分块选项

func WithChunkLogger 

func WithChunkLogger(logger logging.Logger) ChunkOption

WithChunkLogger attaches a logger to the chunking operation. The chunker emits a "chunker.parse" log when the source has been loaded and a "chunker.chunked" log when the chunk array is produced.

func WithChunkStrategy 

func WithChunkStrategy(strategy string) ChunkOption

WithChunkStrategy 设置分块策略

type FileExplorer added in v2.0.13 

type FileExplorer interface {
	// ExploreFile 以文件 Document 为中心探索实体和关系。
	// filePath 应为绝对路径；depth 默认 2 即可包含实体间关系。
	ExploreFile(ctx context.Context, filePath string, depth, limit int) (*RegionGraphView, error)
}

FileExplorer 文件级图探索扩展接口：以文件 Document 为中心查询实体和关系。

GraphIndexer 直接实现；HyperIndexer 委托给内部 graph。

type GraphExplorer added in v2.0.13 

type GraphExplorer interface {
	// ExploreRegion 从指定目录的 Region 节点出发，遍历 depth 跳邻居。
	// dir 应为绝对路径；limit 限制返回节点数量。
	ExploreRegion(ctx context.Context, dir string, depth, limit int) (*RegionGraphView, error)
}

GraphExplorer 图探索扩展接口：以目录为起点查询 Region 及其多跳邻居。

GraphIndexer 直接实现；HyperIndexer 委托给内部 graph。

type GraphIndexer 

type GraphIndexer struct {
	// contains filtered or unexported fields
}

GraphIndexer 图索引器：职责单一化为「图结构化」。

设计要点：

  • 不做分块（Chunker 由 HyperIndexer 调用，独立使用时 AddFile 内部调用 Chunker）
  • 不做向量化（SemanticIndexer 负责）
  • 只持有 GraphStore，从 doc.Nodes()/Edges() 读取实体/关系并写入
  • Chunk 不作为 Node 写入 GraphStore
  • 不实现 IndexerAdmin（Chunk 管理由 SemanticIndexer 通过 VectorStore 负责）

独立使用模式（纯图谱模式）：

  • AddFile 内部调用 Chunker 分块，构造 StructuredDoc，调用 Save
  • Search 只走图遍历（不走向量检索）

HyperIndexer 编排模式：

  • HyperIndexer 完成分块后，通过 Save(ctx, doc) 注入已分块的 StructuredDoc
  • GraphIndexer 只负责写入实体/关系 + 维护 Region→文档根节点的 CONTAINS 边

func (*GraphIndexer) AddFile 

func (idx *GraphIndexer) AddFile(ctx context.Context, filePath string) ([]*core.Chunk, error)

AddFile 索引一个文件，返回产生的 Chunks。

独立使用模式：内部用 Chunker 分块，构造 StructuredDoc，调用 Save。 HyperIndexer 编排模式下不应直接调用 AddFile，应由 HyperIndexer 负责协调。

流程：

  1. document.Open(filePath) → rawDoc
  2. core.NewStructuredDoc(rawDoc) → doc
  3. chunker.New(rawDoc) → chunkerImpl
  4. chunkerImpl.Chunk(rawDoc) → result (含 Chunks/Nodes/Edges)
  5. doc.SetChunks/SetNodes/SetEdges
  6. idx.Save(ctx, doc)
  7. 返回 result.Chunks 转换为 []*core.Chunk

func (*GraphIndexer) CheckReady added in v2.0.8 

func (idx *GraphIndexer) CheckReady() error

CheckReady 检查 GraphIndexer 的核心存储组件是否已就绪。

func (*GraphIndexer) Close 

func (idx *GraphIndexer) Close(ctx context.Context) error

Close 关闭底层图存储。

func (*GraphIndexer) CountByRegion added in v2.0.5 

func (idx *GraphIndexer) CountByRegion(ctx context.Context, path string) (int, error)

CountByRegion 返回指定路径下（dir 前缀匹配）的文档根节点总数。 文档根节点的 dir 属性由 Save 方法在写入时填充。

func (*GraphIndexer) CypherQuery 

func (idx *GraphIndexer) CypherQuery(ctx context.Context, q string, params map[string]any) ([]map[string]any, error)

CypherQuery 执行原始的 Cypher 查询，供外部 Agent/LLM 生成高级图查询。 参数 params 为 Cypher 查询的命名参数映射。

func (*GraphIndexer) EntityStats 

func (idx *GraphIndexer) EntityStats() (entities, rels int)

EntityStats 返回自上次 ResetEntityStats 以来累计创建的实体和关系数量。

func (*GraphIndexer) ExploreFile added in v2.0.13 

func (idx *GraphIndexer) ExploreFile(ctx context.Context, filePath string, depth, limit int) (*RegionGraphView, error)

ExploreFile 以文件文档根节点为中心探索实体和关系。

流程：

  1. 通过 Cypher 查询 dir + file 精确匹配的文档根节点
  2. 从文档根节点出发遍历 depth 跳邻居实体
  3. 返回实体节点与关系边

filePath 应为绝对路径；depth 默认 2 即可包含实体间关系。

func (*GraphIndexer) ExploreRegion added in v2.0.13 

func (idx *GraphIndexer) ExploreRegion(ctx context.Context, dir string, depth, limit int) (*RegionGraphView, error)

ExploreRegion 实现 GraphExplorer 接口：探索指定目录的图结构。

流程：

  1. 通过目录路径生成 Region 节点 ID，获取 Region 节点
  2. 从 Region 节点出发，遍历 depth 跳邻居
  3. 通过 Cypher 查询所有 dir 以指定目录为前缀的文档根节点， 从这些文档根节点出发获取 entity 子节点（解决子目录 Region 独立导致的实体不可达问题）
  4. 合并全部节点与边并去重

func (*GraphIndexer) GetNode added in v2.0.13 

func (idx *GraphIndexer) GetNode(ctx context.Context, nodeID string) (*core.Node, error)

GetNode 实现 GraphNavigator 接口：按 ID 获取单个节点。

func (*GraphIndexer) GraphDB 

func (idx *GraphIndexer) GraphDB() core.GraphStore

GraphDB 返回 GraphIndexer 持有的图数据库实例。 外部可通过此方法直接操作图存储（如自定义 Cypher 查询、图分析等）。

func (*GraphIndexer) Name 

func (idx *GraphIndexer) Name() string

Name 返回索引器名称。

func (*GraphIndexer) Neighbors added in v2.0.13 

func (idx *GraphIndexer) Neighbors(ctx context.Context, nodeID string, depth, limit int) ([]*core.Node, []*core.Edge, error)

Neighbors 实现 GraphNavigator 接口：从 nodeID 出发遍历 depth 跳邻居。 返回邻居节点与关联边；depth=1 表示直接邻居。

func (*GraphIndexer) NewQuery 

func (idx *GraphIndexer) NewQuery(terms string) core.Query

NewQuery 构造查询对象，默认查询类型为 semantic。 调用方可在查询前优化阶段通过 SetType 识别并修改为 graph / hybrid / keyword。

func (*GraphIndexer) ResetEntityStats 

func (idx *GraphIndexer) ResetEntityStats()

ResetEntityStats 将实体/关系计数器归零（通常在每次 Sync 开始前调用）。

func (*GraphIndexer) Save added in v2.0.13 

func (idx *GraphIndexer) Save(ctx context.Context, doc core.StructuredDoc) error

Save 实现 IndexerStore 接口：保存已结构化的文档到 GraphStore。

  • 从 doc.Nodes() 读取实体，写入 graphDB.UpsertNodes
  • 从 doc.Edges() 读取关系，写入 graphDB.UpsertEdges
  • 调用 writeContainsEdges 维护 Region→文档根节点的 CONTAINS 边
  • 不写 Chunk 节点到 GraphStore
  • 不写 文档根节点→Chunk 的 CONTAINS 边（由 TreeViewBuilder 在视图层组装）

与 SemanticIndexer.Save 的差异：

  • SemanticIndexer.Save 写 VectorStore（向量化）
  • GraphIndexer.Save 写 GraphStore（实体 + Region→文档根节点边，不向量化）

func (*GraphIndexer) Search 

func (idx *GraphIndexer) Search(ctx context.Context, qry core.Query) (*core.Hit, error)

Search 实现 Indexer 接口：执行图遍历检索，返回 *core.Hit 容器。

GraphIndexer 独立使用时不持有 VectorStore/Embedder，无法走向量检索。 Search 只走图遍历（searchGraphOnly），返回的 Hit 仅包含 Nodes/Edges。 生产场景应通过 HyperIndexer 使用，由 SemanticIndexer 提供向量检索能力。

func (*GraphIndexer) SearchGraph added in v2.0.13 

func (idx *GraphIndexer) SearchGraph(ctx context.Context, q core.Query) (*core.Hit, error)

SearchGraph 实现 GraphSearcher 接口：执行图查询，返回 *Hit（仅 Nodes/Edges，Chunks 为空）。

与 Search 的区别：

  • Search 在 HyperIndexer 编排下可能融合多源结果
  • SearchGraph 明确只走图遍历，返回的 Hit 仅包含 Nodes/Edges

客户端可对 Search 和 SearchGraph 的结果直接做 Fusion 融合。

type GraphNavigator added in v2.0.13 

type GraphNavigator interface {
	// Neighbors 从 nodeID 出发遍历 depth 跳邻居，返回邻居节点与关联边。
	// depth=1 表示直接邻居；limit 限制返回节点数量。
	Neighbors(ctx context.Context, nodeID string, depth, limit int) ([]*core.Node, []*core.Edge, error)

	// GetNode 按 ID 获取单个节点，用于补全路径起点（如 Region 节点本身）。
	GetNode(ctx context.Context, nodeID string) (*core.Node, error)
}

GraphNavigator 图导航扩展接口：从指定节点出发进行多跳邻居遍历。

仅 GraphIndexer / HyperIndexer 实现，用于 `grag nodes` 这类目录级图探索命令。

type GraphOption 

type GraphOption func(*GraphIndexer)

GraphOption 配置 GraphIndexer 的可选参数。

func WithLogger 

func WithLogger(logger logging.Logger) GraphOption

WithLogger 为 GraphIndexer 附加日志记录器。

type GraphSearcher added in v2.0.13 

type GraphSearcher interface {
	// SearchGraph 执行图查询，返回 Hit（Nodes / Edges 填充，Chunks 为空）。
	SearchGraph(ctx context.Context, query core.Query) (*core.Hit, error)
}

GraphSearcher 图查询扩展接口：执行图检索，返回 *Hit（Nodes / Edges 填充）。

仅 GraphIndexer 实现，SemanticIndexer 不维护 GraphStore。 调用方按需 type-assert： 

if g, ok := idx.(GraphSearcher); ok { hit, err := g.SearchGraph(ctx, q) }

与 Indexer.Search 统一返回 *Hit，便于 Fusion 融合：

  • SearchGraph 返回的 Hit 中 Chunks 为空，仅填充 Nodes / Edges
  • 客户端可对 Search 和 SearchGraph 的结果直接做 Fusion 融合
  • GraphResult 类型已删除，统一用 *core.Hit 表达检索结果

type HyperIndexer added in v2.0.13 

type HyperIndexer struct {
	// contains filtered or unexported fields
}

===================================================================== HyperIndexer 复合索引器 =====================================================================

HyperIndexer 是双线结合的契机——协调 SemanticIndexer（语义线）和 GraphIndexer（关系线）。

核心设计：

  • GraphIndexer 职责独立，不做分块+向量化
  • SemanticIndexer 职责独立，不做实体提取+图结构化
  • HyperIndexer 编排双线：读文件→结构化→分块→分流到 SemanticIndexer + GraphIndexer

工作流（AddFile）：

  1. document.Open(path) → RawDoc（读文件 + 归一化）
  2. core.NewStructuredDoc(raw) → StructuredDoc（结构化容器）
  3. 路由 Chunker（注入的或 chunker.New(raw)）；chunkerImpl.Chunk(raw) → ChunkResult（含 Chunks/Nodes/Edges）
  4. doc.SetChunks/SetNodes/SetEdges（把三类产物分别存入 StructuredDoc）
  5. semantic.Save(doc)（语义线：向量化+写入 VectorStore）
  6. graph.Save(doc)（关系线：实体+CONTAINS 边+写入 GraphStore，若 graph 存在）

工作流（Search）：

  1. semantic.Search(q) → semHit（Chunks 填充）
  2. graph.SearchGraph(q) → graphHit（Nodes/Edges 填充，若 graph 存在）
  3. result.RRF(semHit, graphHit) → 融合 Hit（三类齐全）

扩展能力（通过 type-assert）：

  • hyper.(IndexerAdmin) → 委托 semantic（语义线持有 VectorStore）
  • hyper.(IndexerCloser) → 双线联动关闭
  • hyper.(TreeViewBuilder)→ HyperIndexer 自身实现（先取 Region→Document，再补齐 Chunk）
  • hyper.(GraphSearcher) → 委托 graph

func (*HyperIndexer) AddFile added in v2.0.13 

func (h *HyperIndexer) AddFile(ctx context.Context, filePath string) ([]*core.Chunk, error)

AddFile 实现 Indexer 接口：对外统一入口，编排双线索引。

工作流（完整）：

  1. document.Open(filePath) → RawDoc [1a] OnBeforeChunkHook：文件类型白名单、前置过滤
  2. core.NewStructuredDoc(raw) → StructuredDoc 容器
  3. 路由 Chunker → chunkerImpl.Chunk(raw) → ChunkResult
  4. doc.SetChunks/SetNodes/SetEdges [4a] OnChunkedHook：补充标签、审计分片结果 4.5 [语义线加工] 若注入了 Summarizer，对文档类分片逐 chunk 摘要 [4b] OnSummarizedHook：逐 chunk 摘要完成通知
  5. semantic.Save(doc)（向量化 + 写入 VectorStore） [5a] OnChunkedSavedHook：外部 API 增强、补充元数据 5.5 [关系线加工] 若注入了 Refiller + 已注册 Schema，调用 Refiller 提取实体和关系 [5b] OnExtractedHook：审计实体提取结果
  6. graph.Save(doc)（实体 + CONTAINS 边 + 写入 GraphStore，若 graph 存在） [6a] OnNodesSavedHook：图数据通知、审计日志

原子化管线：AddFile 内部依次完成「分块→逐 chunk 摘要→向量化存储→实体提取→图存储」， 每个文件独立完成全部处理。不再依赖外部分阶段编排（如 Update 中的 LLM 批量处理）。 关系线失败不阻塞语义线，仅记录警告。

func (*HyperIndexer) AddSchemas added in v2.0.13 

func (h *HyperIndexer) AddSchemas(path string, schemas []llm.EntitySchema)

AddSchemas 注册外部实体 Schema 到 HyperIndexer。

path 是文件系统路径，指向该组 Schema 的源目录（如 "schemas/general"）， 保留溯源语义——调用方可追踪这些 Schema 来自哪个配置文件目录。 schemas 使用 llm/schema.go 中已定义的 EntitySchema 类型， 可经由 llm.LoadEntitySchemasFromDir 或自定义加载函数解析后传入。

path 不用于文件读取（schemas 已经是解析好的），仅作为注册标识。 HyperIndexer 将 path 作为 key 存储在内部注册表中，供 Refiller 消费时合并。

func (*HyperIndexer) Clear added in v2.0.13 

func (h *HyperIndexer) Clear(ctx context.Context) error

Clear 实现 IndexerAdmin 接口：双线联动清空。

func (*HyperIndexer) Close added in v2.0.13 

func (h *HyperIndexer) Close(ctx context.Context) error

Close 实现 IndexerCloser 接口：双线联动关闭。 任何一线关闭失败都返回 error，但会尝试关闭所有线后再返回。

func (*HyperIndexer) Count added in v2.0.13 

func (h *HyperIndexer) Count(ctx context.Context) (int, error)

Count 实现 IndexerAdmin 接口：委托语义线。

func (*HyperIndexer) CypherQuery added in v2.0.13 

func (h *HyperIndexer) CypherQuery(ctx context.Context, q string, params map[string]any) ([]map[string]any, error)

CypherQuery 执行原始 Cypher 查询，委托给关系线的 GraphIndexer。 仅当索引器支持图存储时可用。

func (*HyperIndexer) ExploreFile added in v2.0.13 

func (h *HyperIndexer) ExploreFile(ctx context.Context, filePath string, depth, limit int) (*RegionGraphView, error)

ExploreFile 实现 FileExplorer 接口：委托关系线执行文件级图探索。

func (*HyperIndexer) ExploreRegion added in v2.0.13 

func (h *HyperIndexer) ExploreRegion(ctx context.Context, dir string, depth, limit int) (*RegionGraphView, error)

ExploreRegion 实现 GraphExplorer 接口：委托关系线执行目录级图探索。

func (*HyperIndexer) GetChunks added in v2.0.13 

func (h *HyperIndexer) GetChunks(ctx context.Context, docID string) ([]*core.Chunk, error)

GetChunks 实现 IndexerAdmin 接口：委托语义线。

func (*HyperIndexer) GetNode added in v2.0.13 

func (h *HyperIndexer) GetNode(ctx context.Context, nodeID string) (*core.Node, error)

GetNode 实现 GraphNavigator 接口：委托关系线按 ID 获取单个节点。

func (*HyperIndexer) List added in v2.0.13 

func (h *HyperIndexer) List(ctx context.Context, offset, limit int, filters []core.FilterCondition) ([]core.Chunk, int, error)

List 实现 IndexerAdmin 接口：委托语义线（VectorStore 持有全部 Chunk 数据）。

func (*HyperIndexer) Name added in v2.0.13 

func (h *HyperIndexer) Name() string

Name 返回索引器名称

func (*HyperIndexer) Neighbors added in v2.0.13 

func (h *HyperIndexer) Neighbors(ctx context.Context, nodeID string, depth, limit int) ([]*core.Node, []*core.Edge, error)

Neighbors 实现 GraphNavigator 接口：委托关系线执行多跳邻居遍历。 若关系线未启用或未实现 GraphNavigator，返回错误。

func (*HyperIndexer) NewQuery added in v2.0.13 

func (h *HyperIndexer) NewQuery(terms string) core.Query

NewQuery 实现 Indexer 接口：委托语义线构造查询。

func (*HyperIndexer) Remove added in v2.0.13 

func (h *HyperIndexer) Remove(ctx context.Context, chunkID string) error

Remove 实现 IndexerAdmin 接口：双线联动删除。 语义线和关系线都需要按 chunkID 删除关联数据。 关系线删除失败不阻塞语义线，仅记录警告。

func (*HyperIndexer) Search added in v2.0.13 

func (h *HyperIndexer) Search(ctx context.Context, q core.Query) (*core.Hit, error)

Search 实现 Indexer 接口：双线融合检索。

工作流：

  1. semantic.Search(q) → semHit（Chunks 填充）
  2. graph.SearchGraph(q) → graphHit（Nodes/Edges 填充，若 graph 存在）
  3. result.RRF(semHit, graphHit) → 融合 Hit（三类齐全）

设计要点：

  • graph 为 nil 时跳过图检索，直接返回 semHit
  • graphHit 为 nil 时 RRF 内部自动跳过，不影响融合
  • 融合后 Hit.Score = topChunkScore + topNodeScore + topEdgeScore

func (*HyperIndexer) SearchGraph added in v2.0.13 

func (h *HyperIndexer) SearchGraph(ctx context.Context, q core.Query) (*core.Hit, error)

SearchGraph 实现 GraphSearcher 接口：委托关系线。 graph 为 nil 或未实现 GraphSearcher 时返回 error。

func (*HyperIndexer) SetLogger added in v2.0.13 

func (h *HyperIndexer) SetLogger(logger logging.Logger)

SetLogger 在运行时设置日志记录器。

func (*HyperIndexer) SetRefiller added in v2.0.13 

func (h *HyperIndexer) SetRefiller(r llm.Refiller)

SetRefiller 在运行时注入或替换 Refiller。 若传入 nil，则禁用 Refiller 功能。

func (*HyperIndexer) SetSummarizer added in v2.0.13 

func (h *HyperIndexer) SetSummarizer(s llm.Summarizer)

SetSummarizer 在运行时注入或替换 Summarizer。 若传入 nil，则禁用 Summarizer 功能。

func (*HyperIndexer) Tree added in v2.0.13 

func (h *HyperIndexer) Tree(ctx context.Context, regionID string) (*core.TreeNode, error)

Tree 实现 TreeViewBuilder 接口：构建 Region → Document → Chunk 三层知识树。

实现流程：

  1. 从 GraphIndexer 取 Region→Document 树（通过未导出方法 regionTree）
  2. 对每个 Document 节点，通过 semantic.(IndexerAdmin).GetChunks 从 VectorStore 读取 Chunk 列表
  3. 将 Chunk 挂载为对应 Document 的子节点
  4. 返回完整的 Region→Document→Chunk 树

设计要点：

  • 仅 HyperIndexer 实现此接口——它需要同时访问 GraphStore 和 VectorStore
  • GraphIndexer 不实现 TreeViewBuilder，仅暴露未导出的 regionTree 供 HyperIndexer 调用
  • Chunk 不写入 GraphStore，而是在视图层通过 VectorStore.Metadata[core.VecMetaDocID] 动态组装

graph 为 nil 或非 *GraphIndexer 时返回 error。

type HyperOption added in v2.0.13 

type HyperOption func(*HyperIndexer)

HyperOption HyperIndexer 配置选项

func WithHooks added in v2.0.13 

func WithHooks(hooksList ...any) HyperOption

WithHooks 注入事件扩展 Hook。

可传入任意数量的 Hook（OnBeforeChunkHook、OnChunkedHook、OnSummarizedHook、 OnChunkedSavedHook、OnExtractedHook、OnNodesSavedHook），WithHooks 按类型自动归入对应切片。 单一类型可注册多个 Hook，按注册顺序执行。

func WithHyperChunker added in v2.0.13 

func WithHyperChunker(c chunker.Chunker) HyperOption

WithHyperChunker 设置自定义分块器（默认按 RawDoc.Type 自动路由）

func WithHyperLogger added in v2.0.13 

func WithHyperLogger(logger logging.Logger) HyperOption

WithHyperLogger 设置日志记录器

func WithHyperRefiller added in v2.0.13 

func WithHyperRefiller(r llm.Refiller) HyperOption

WithHyperRefiller 注入实体提取兜底，在语义线保存后对分片执行 LLM 实体提取。 提取结果追加到 doc.Nodes/Edges，再写入 GraphStore。 不传则不执行实体提取，关系线只走 Chunker 代码解析器产出的 Nodes/Edges。

func WithHyperSummarizer added in v2.0.13 

func WithHyperSummarizer(s llm.Summarizer) HyperOption

WithHyperSummarizer 注入摘要器，在分块后为文档类分片逐 chunk 生成 title/summary。 不传则不调用 Summarizer，title/summary 由 Chunker 默认策略产出。

type IndexError 

type IndexError struct {
	DocID     string        // 文档 ID
	Err       error         // 原始错误
	ErrorType string        // 错误分类: network | timeout | rate_limit | auth | api | unknown
	Attempts  int           // 重试次数
	Duration  time.Duration // 总耗时
}

IndexError 包含索引失败的详细信息，供外部错误处理使用。

type Indexer added in v2.0.13 

type Indexer interface {
	// Name 返回索引器名称（如 "semantic" / "graph" / "hyper"）。
	Name() string

	// AddFile 从文件读取内容后执行索引全流程。
	// filePath 必须为绝对路径，内部通过 document.Open 归一化后分块、向量化、写入存储。
	// 返回本次索引生成的 Chunks（调用方可用于追踪或后续处理）。
	AddFile(ctx context.Context, filePath string) ([]*core.Chunk, error)

	// Search 执行检索，返回命中的 Hit 容器（持有 Chunks/Nodes/Edges）。
	// Hit 与 StructuredDoc 对称——StructuredDoc 是存，Hit 是取。
	Search(ctx context.Context, query core.Query) (*core.Hit, error)

	// NewQuery 构造查询对象，承载查询前优化与查询类型识别。
	NewQuery(terms string) core.Query
}

Indexer 索引器核心接口：负责文件索引和检索。 所有索引器必须实现此接口。

设计要点：

  • 只支持文件输入（AddFile），不支持字符串输入
  • 所有内容必须先落盘为文件，通过 document.Open 归一化
  • dir / file / region_id 等元数据依赖文件路径
  • Search 返回 *core.Hit 容器（持有 Chunks/Nodes/Edges），与 StructuredDoc 对称

实现类型：

  • SemanticIndexer：分块 + 向量化 + 语义检索
  • GraphIndexer：分块 + 图结构化（独立使用为纯图谱模式）
  • HyperIndexer：双线协同（语义线 + 关系线）

func New 

func New(
	graphDB core.GraphStore,
	opts ...GraphOption,
) (Indexer, error)

New 创建 GraphIndexer，返回 Indexer 接口。

参数：

  • graphDB: 图存储（写入实体/关系，用于知识图谱检索）
  • opts: 可选配置（WithLogger、WithSchemas、WithSchemasFromFS 等）

func NewHyperIndexer added in v2.0.13 

func NewHyperIndexer(semantic Indexer, graph Indexer, opts ...HyperOption) (Indexer, error)

NewHyperIndexer 创建复合索引器，返回 Indexer 接口。

参数：

  • semantic: 语义线索引器（必传，通常由 NewSemanticIndexer 创建）
  • graph: 关系线索引器（可选，传 nil 则不启用图功能；通常由 New（GraphIndexer）创建）
  • opts: 可选配置（WithHyperLogger、WithHyperChunker、WithHyperSummarizer、WithHyperRefiller）

设计要点：

  • semantic 为 nil 时返回 error（语义线是必传的核心能力）
  • graph 为 nil 时降级为纯语义模式（Search 只返回 Chunks）
  • 默认分块器按需懒创建（每次 AddFile 时根据 RawDoc.Type 路由）

func NewSemanticIndexer 

func NewSemanticIndexer(db core.VectorStore, embedder core.Embedder, opts ...SemanticOption) (Indexer, error)

NewSemanticIndexer 创建语义索引器，返回 Indexer 接口。

必传参数：

  • db：向量存储，nil 返回 error
  • embedder：向量计算器，nil 返回 error

可选参数通过 WithSemanticLogger / WithSemanticChunker 注入。

type IndexerAdmin added in v2.0.13 

type IndexerAdmin interface {
	// List 分页浏览已索引的 Chunk。
	// filters 为 nil 时返回全部，非 nil 时按条件过滤（多个条件之间为 AND 语义）。
	// 返回当前页的 Chunk 切片与过滤前总数。
	List(ctx context.Context, offset, limit int, filters []core.FilterCondition) ([]core.Chunk, int, error)

	// GetChunks 按 docID 获取该文档的所有 Chunk。
	GetChunks(ctx context.Context, docID string) ([]*core.Chunk, error)

	// Count 返回已索引的 Chunk 总数。
	Count(ctx context.Context) (int, error)

	// Remove 按 chunkID 移除索引项（连带删除关联的 Nodes / Edges）。
	Remove(ctx context.Context, chunkID string) error

	// Clear 清空索引。
	Clear(ctx context.Context) error
}

IndexerAdmin 索引器管理接口：浏览、统计、维护。

调用方按需 type-assert： 

if a, ok := idx.(IndexerAdmin); ok { ... }

type IndexerCloser added in v2.0.13 

type IndexerCloser interface {
	// Close 释放底层资源（数据库连接、文件句柄等）。
	Close(ctx context.Context) error
}

IndexerCloser 资源管理接口：释放底层存储资源。

调用方按需 type-assert： 

if c, ok := idx.(IndexerCloser); ok { defer c.Close(ctx) }

type IndexerFlusher added in v2.0.14 

type IndexerFlusher interface {
	// Flush 强制将写入缓冲刷入持久化存储。
	Flush(ctx context.Context) error
}

IndexerFlusher 落盘接口：强制将写入缓冲刷入持久化存储。

底层存储（如 govector）为性能采用攒批缓冲写入：数据先进内存索引（查询 即时可见），只有攒够阈值或显式 Flush/Close 才真正写入磁盘。对关键数据 （如记忆），调用方应在写入后立即调用 Flush，避免进程异常退出 （如 os.Exit 重启）导致缓冲中的数据丢失。

调用方按需 type-assert： 

if f, ok := idx.(IndexerFlusher); ok { f.Flush(ctx) }

type IndexerMetadataUpdater added in v2.0.14 

type IndexerMetadataUpdater interface {
	// UpdateVectorMetadata 更新主向量的 metadata（patch 逐键覆盖）。
	UpdateVectorMetadata(ctx context.Context, chunkID string, patch map[string]any) error
}

IndexerMetadataUpdater 向量元数据更新接口：按 chunkID 就地更新主向量 metadata。

与 Remove + Save 的区别：以原向量 ID 写回（Upsert 对已存在 ID 为 replace 语义）， 不触发向量删除，避免 HNSW 图在 Remove 后结构不一致的问题。 仅 SemanticIndexer 实现。

调用方按需 type-assert： 

if u, ok := idx.(IndexerMetadataUpdater); ok { u.UpdateVectorMetadata(ctx, id, patch) }

type IndexerStore added in v2.0.13 

type IndexerStore interface {
	// Save 保存已结构化的文档到各自存储。
	// 不返回 Chunks——Chunks 已在 doc 中，各 Indexer 只负责保存。
	Save(ctx context.Context, doc core.StructuredDoc) error
}

IndexerStore 存储接口：保存 StructuredDoc 到各自存储。

各 Indexer 的 Save 实现自动路由到各自存储：

  • SemanticIndexer.Save → 从 doc.Chunks() 读取，按 Title/Summary/Content 生成多维度向量，写入 VectorStore
  • GraphIndexer.Save → 从 doc.Nodes()/Edges() 读取实体/关系，维护 Region→Document 的 CONTAINS 边，写入 GraphStore

语义：

  • Save 接收的 StructuredDoc 已完成「读文件 + 归一化 + 分块 + 结构化」
  • Chunks/Nodes/Edges 已由 HyperIndexer 调用 Chunker 填充到 doc 中
  • 各 Indexer 从 doc 读取各自需要的数据（向量化 / 图结构化）
  • Save 只负责「保存各自需要的数据」，不返回 Chunks

HyperIndexer 不实现此接口——它是组合器，通过调用 semantic.Save + graph.Save 实现存储路由。

type OnBeforeChunkHook added in v2.0.14 

type OnBeforeChunkHook interface {
	OnBeforeChunk(ctx context.Context, raw document.RawDoc) (document.RawDoc, error)
}

OnBeforeChunkHook 修改型 Hook。 在 document.Open 之后、Chunker.Chunk 之前触发，可修改 RawDoc。 应用场景：文件类型白名单、前置过滤。

type OnChunkedHook added in v2.0.14 

type OnChunkedHook interface {
	OnChunked(ctx context.Context, doc core.StructuredDoc) (core.StructuredDoc, error)
}

OnChunkedHook 修改型 Hook。 在 Chunker 完成分片后、Summarizer 之前触发，可修改 StructuredDoc。 应用场景：补充标签、审计分片结果。

type OnChunkedSavedHook added in v2.0.14 

type OnChunkedSavedHook interface {
	OnChunkedSaved(ctx context.Context, chunks []core.Chunk) error
}

OnChunkedSavedHook 修改型 Hook。 在 semantic.Save（向量化+存储）完成后、Refiller 之前触发。 应用场景：外部 API 增强、补充元数据。

type OnExtractedHook added in v2.0.14 

type OnExtractedHook interface {
	OnExtracted(ctx context.Context, chunks []core.Chunk, nodes []core.Node, edges []core.Edge) error
}

OnExtractedHook 通知型 Hook。 在 Refiller 完成实体提取后、graph.Save 之前触发，不阻塞管线。 应用场景：审计实体提取结果。

type OnNodesSavedHook added in v2.0.14 

type OnNodesSavedHook interface {
	OnNodesSaved(ctx context.Context, nodes []core.Node) error
}

OnNodesSavedHook 通知型 Hook。 在 graph.Save（图存储）完成后触发，不阻塞管线。 应用场景：图数据通知、审计日志。

type OnSummarizedHook added in v2.0.14 

type OnSummarizedHook interface {
	OnSummarized(ctx context.Context, chunk *core.Chunk) error
}

OnSummarizedHook 通知型 Hook。 在每个 chunk 完成 LLM 摘要后触发，不阻塞管线。 应用场景：逐 chunk 进度通知。

type RegionGraphView added in v2.0.13 

type RegionGraphView struct {
	RegionID   string
	RegionName string
	Region     *core.Node
	Nodes      []*core.Node
	Edges      []*core.Edge
}

RegionGraphView 是 GraphIndexer 返回的目录级图视图。

type SemanticOption 

type SemanticOption func(*semanticIndexer)

SemanticOption 配置 semanticIndexer 的可选参数。

func WithSemanticChunker added in v2.0.13 

func WithSemanticChunker(c chunker.Chunker) SemanticOption

WithSemanticChunker 注入自定义 Chunker，覆盖默认的 chunker.New 路由。 不传则 AddFile 内部按 RawDoc.Type 调用 chunker.New 选择实现。

func WithSemanticLogger 

func WithSemanticLogger(logger logging.Logger) SemanticOption

WithSemanticLogger 为语义索引器附加日志记录器。

type TreeViewBuilder added in v2.0.13 

type TreeViewBuilder interface {
	// Tree 输出基于 Region 层级的知识树。
	// regionID 为空时返回整棵树；非空时返回该 Region 子树。
	// 实现流程：先从 GraphIndexer 取 Region→Document 树，
	// 再通过 SemanticIndexer 为每个 Document 补齐 Chunk 子节点。
	Tree(ctx context.Context, regionID string) (*core.TreeNode, error)
}

TreeViewBuilder 知识库导航接口：构建 Region → Document → Chunk 层级树。

仅 HyperIndexer 实现，因为它需要同时访问 GraphStore 的 Region→Document 层级 和 VectorStore 的 Document→Chunk 数据。 调用方按需 type-assert： 

if t, ok := idx.(TreeViewBuilder); ok { tree, err := t.Tree(ctx, "") }

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.