Documentation
¶
Index ¶
- Constants
- func GetChunks(content string, opts ...ChunkOption) ([]*core.Chunk, error)
- func GetFileChunks(file string, opts ...ChunkOption) ([]*core.Chunk, error)
- func IsRegionDescriptor(path string) bool
- func NewFulltextIndexer(store core.FullTextStore) (core.Indexer, error)
- func NewFulltextIndexerWithFile(dbPath string) (core.Indexer, error)
- func NewSafeFulltextIndexer(dbPath string) (core.Indexer, error)
- func NewSemanticIndexer(db core.VectorStore, embedder core.Embedder, opts ...SemanticOption) core.Indexer
- func RegionIDFromContext(ctx context.Context) string
- func RegionIDFromDir(dir string) string
- func StripExt(filename string) string
- func WithRegionID(ctx context.Context, regionID string) context.Context
- type ChunkOption
- type EntityDef
- type GraphIndexer
- func (idx *GraphIndexer) Add(ctx context.Context, content string) ([]*core.Chunk, error)
- func (idx *GraphIndexer) AddFile(ctx context.Context, filePath string) ([]*core.Chunk, error)
- func (idx *GraphIndexer) CheckReady() error
- func (idx *GraphIndexer) Clear(ctx context.Context) error
- func (idx *GraphIndexer) Close(ctx context.Context) error
- func (idx *GraphIndexer) Count(ctx context.Context) (int, error)
- func (idx *GraphIndexer) CountByRegion(ctx context.Context, path string) (int, error)
- func (idx *GraphIndexer) CumulativeTokenUsage() *TokenUsage
- func (idx *GraphIndexer) CypherQuery(ctx context.Context, q string, params map[string]any) ([]map[string]any, error)
- func (idx *GraphIndexer) EntityStats() (entities, rels int)
- func (idx *GraphIndexer) GetChunks(ctx context.Context, docID string) ([]*core.Chunk, error)
- func (idx *GraphIndexer) GraphDB() core.GraphStore
- func (idx *GraphIndexer) LastTokenUsage() *TokenUsage
- func (idx *GraphIndexer) List(ctx context.Context, offset, limit int) ([]core.Hit, error)
- func (idx *GraphIndexer) ListFiltered(ctx context.Context, offset, limit int, filters []core.FilterCondition) ([]core.Hit, int, error)
- func (idx *GraphIndexer) Name() string
- func (idx *GraphIndexer) NewQuery(terms string) core.Query
- func (idx *GraphIndexer) Refill(ctx context.Context) error
- func (idx *GraphIndexer) Remove(ctx context.Context, chunkID string) error
- func (idx *GraphIndexer) ResetEntityStats()
- func (idx *GraphIndexer) Search(ctx context.Context, qry core.Query) ([]core.Hit, error)
- func (idx *GraphIndexer) SearchByChunkIDs(ctx context.Context, chunkIDs []string, depth, limit int, ...) ([]core.Hit, error)
- func (idx *GraphIndexer) SetEntityDefs(defs []EntityDef)
- func (idx *GraphIndexer) SetEntityDefsByRegion(regionID string, defs []EntityDef)
- func (idx *GraphIndexer) StoreChunk(ctx context.Context, chunk *core.Chunk) error
- func (idx *GraphIndexer) Tree(ctx context.Context, regionID string, depth int) (*core.ChunkNode, error)
- func (idx *GraphIndexer) Type() string
- func (idx *GraphIndexer) UseEnglish()
- func (idx *GraphIndexer) VectorDB() core.VectorStore
- type GraphOption
- type IndexData
- type IndexError
- type ModelConfig
- type RegionIndexer
- type RegionOption
- type RegionResult
- type SemanticOption
- type TokenUsage
Constants ¶
const ( LangEN = "en" LangZH = "zh" )
Prompt language constants.
const RegionFileName = "README.md"
RegionFileName 是 Region 描述文件的文件名。 每个目录下的该文件作为 Region 的实体化载体， 其内容会被索引为普通文档，提取的实体/关系成为 Region 的知识源。
若目录下已存在该文件（用户编写或上次生成），IndexRegion 会直接复用其内容， 跳过 LLM 聚合；仅在文件不存在时才走 LLM 聚合生成流程。
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 IsRegionDescriptor ¶ added in v2.0.4
IsRegionDescriptor 判断文件是否为 Region 描述文件。
func NewFulltextIndexer ¶
func NewFulltextIndexer(store core.FullTextStore) (core.Indexer, error)
func NewFulltextIndexerWithFile ¶
NewFulltextIndexer 创建全文索引器
func NewSafeFulltextIndexer ¶
NewSafeFulltextIndexer 创建线程安全的全文索引器
func NewSemanticIndexer ¶
func NewSemanticIndexer(db core.VectorStore, embedder core.Embedder, opts ...SemanticOption) core.Indexer
func RegionIDFromContext ¶ added in v2.0.3
RegionIDFromContext extracts a region ID from context, or returns "".
func RegionIDFromDir ¶ added in v2.0.3
RegionIDFromDir 计算一个目录路径对应的 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 core.ChunkStrategy) ChunkOption
WithChunkStrategy 设置分块策略
type EntityDef ¶
type EntityDef struct {
Prompt string // 实体类型描述文本（如 "**Person** — author, expert, contributor"）
Schema string // JSON Schema 文本（如 `{"type":"object","properties":{...}}`），可选
}
EntityDef 定义一个实体类型的 Prompt 与 Schema，供 WithSchemas 注入 LLM Prompt。 Prompt 写入 ### Entity Types 段，Schema 写入 ### Entity Schema 段。 LLM 在 output 中使用 Prompt 中的类型名作为 entity.type，该 type 最终成为 core.Node.Labels[0]（即 gograph 的 node Label），可用 MATCH (n:TypeName) 查询。
func ParseEntityDefsYAML ¶
ParseEntityDefsYAML 解析实体类型定义的 YAML 数据，返回 EntityDef 列表。 YAML 中每项支持两个输出字段：
- prompt：直接使用；为空时自动生成为 "**{Name}** — {Desc}"
- schema：可选字段，直接使用
type GraphIndexer ¶
type GraphIndexer struct {
// ── 钩子回调（只读观察者模式） ──
OnRequest func(docID string, messages []chat.Message, thinkingBudget int)
OnResponse func(docID string, resp *chat.Response)
OnFail func(docID string, err *IndexError)
// contains filtered or unexported fields
}
GraphIndexer 使用 LLM 进行文本分块、实体提取，并同时写入 VectorStore + GraphStore。 是 GoRAG 的全面索引器，同时写入 VectorStore + GraphStore。
数据流：
Add / AddFile → document (获取 docID) → Token 估算 → 未超限 → LLM (分块+实体提取) → 写入 vectorDB + graphDB → 超限 → 切片 → N 次 LLM 调用 → 合并结果 → 写入
func New ¶
func New( model ModelConfig, embedder core.Embedder, vectorDB core.VectorStore, graphDB core.GraphStore, opts ...GraphOption, ) *GraphIndexer
New 创建 GraphIndexer
- model: LLM 模型连接配置（APIKey, BaseURL, Model, MaxTokens）
- embedder: 文本向量化引擎
- vectorDB: 向量存储（写入 Chunk 向量，用于语义检索）
- graphDB: 图存储（写入实体/关系，用于知识图谱检索）
- opts: 可选配置（WithLogger、WithSchemas 等）
func (*GraphIndexer) Add ¶
Add 对一段文本执行 LLM 索引。
流程：document → Token 估算
- 未超限：单次 LLM 分块+实体提取 → 写入 vectorDB + graphDB
- 超限：按 80% maxTokens 切片 → 多次 LLM → 合并结果 → 写入
超短文本（< minContentLength 字符）会被静默丢弃。
func (*GraphIndexer) AddFile ¶
AddFile 从文件读取内容后执行 LLM 索引。
流程：document.Open（文档读取 + 清洗）→ Token 估算
- 未超限：单次 LLM → 写入
- 超限：返回错误，要求用户手动拆分文件
超短文件（< minContentLength 字符）会被静默丢弃。
func (*GraphIndexer) CheckReady ¶ added in v2.0.8
func (idx *GraphIndexer) CheckReady() error
CheckReady 检查 GraphIndexer 的核心存储组件是否都已就绪。 在调用 Add/AddFile 前调用此方法可以避免在组件未初始化时浪费 LLM 调用。 返回 error 时日志已在内部以 Error 级别输出。
func (*GraphIndexer) Clear ¶ added in v2.0.11
func (idx *GraphIndexer) Clear(ctx context.Context) error
Clear 清空索引中的所有数据（向量 + 图谱）。
func (*GraphIndexer) Close ¶
func (idx *GraphIndexer) Close(ctx context.Context) error
Close 关闭底层存储。
func (*GraphIndexer) Count ¶
func (idx *GraphIndexer) Count(ctx context.Context) (int, error)
Count 返回 vectorDB 中的索引总数。
func (*GraphIndexer) CountByRegion ¶ added in v2.0.5
CountByRegion 返回指定路径下（source_file 前缀匹配）的分片总数。
func (*GraphIndexer) CumulativeTokenUsage ¶
func (idx *GraphIndexer) CumulativeTokenUsage() *TokenUsage
CumulativeTokenUsage 返回从创建/重置起累积的 Token 用量（多切片场景使用）。
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) GraphDB ¶
func (idx *GraphIndexer) GraphDB() core.GraphStore
GraphDB 返回 GraphIndexer 持有的图数据库实例。 外部可通过此方法直接操作图存储（如自定义 Cypher 查询、图分析等）。
func (*GraphIndexer) LastTokenUsage ¶
func (idx *GraphIndexer) LastTokenUsage() *TokenUsage
LastTokenUsage 返回最近一次 LLM 调用的 Token 用量（单次值）。
func (*GraphIndexer) ListFiltered ¶ added in v2.0.3
func (idx *GraphIndexer) ListFiltered(ctx context.Context, offset, limit int, filters []core.FilterCondition) ([]core.Hit, int, error)
ListFiltered 从 vectorDB 中按 metadata 条件分页获取结果。 返回分页后的 hits、匹配条件的总条数（分页前）、以及错误。
func (*GraphIndexer) Name ¶
func (idx *GraphIndexer) Name() string
func (*GraphIndexer) Refill ¶ added in v2.0.10
func (idx *GraphIndexer) Refill(ctx context.Context) error
Refill 为已有分片补充从属维度的向量（title/summary）。 用于存量数据迁移到多维度索引。幂等：已存在的从属向量会跳过，支持中断重跑。
func (*GraphIndexer) Remove ¶
func (idx *GraphIndexer) Remove(ctx context.Context, chunkID string) error
Remove 从 vectorDB 和 graphDB 中移除与 chunkID 关联的所有数据。
func (*GraphIndexer) ResetEntityStats ¶
func (idx *GraphIndexer) ResetEntityStats()
ResetEntityStats 将实体/关系计数器归零（通常在每次 Sync 开始前调用）。
func (*GraphIndexer) Search ¶
Search 按查询类型路由搜索策略：
- *query.GraphQuery 含 RawCypher → graphDB 直接执行 Cypher → 转 Hits
- *query.GraphQuery 含 TextQuery（无 RawCypher）→ 内部 LLM 转 Cypher → graphDB 执行 → 转 Hits
- *query.GraphQuery 不含 Text/Raw → 向量检索 → Nodes/Edges 融合 → 多跳遍历 → Hits
- *query.SemanticQuery → 向量检索 → Nodes/Edges 融合 → 返回 Hits
无论哪种查询类型，返回的 Hits 均包含 Entities/Relations 字段。
func (*GraphIndexer) SearchByChunkIDs ¶
func (idx *GraphIndexer) SearchByChunkIDs(ctx context.Context, chunkIDs []string, depth, limit int, edgeTypes ...[]string) ([]core.Hit, error)
SearchByChunkIDs 通过 Chunk IDs 查询关联的图结构（外部调用入口，无需向量检索）。 流程：Chunk IDs → 查询关联 Nodes → 多跳遍历 → 路径评分 → Hit
支持选项：
- depth: 遍历深度（默认 1，即直接邻居）
- limit: 返回结果数量上限
- edgeTypes: 关系类型过滤，仅遍历指定类型的边
注意：此方法不执行向量检索，直接使用提供的 chunkIDs。前端分页列表等场景可用。
func (*GraphIndexer) SetEntityDefs ¶
func (idx *GraphIndexer) SetEntityDefs(defs []EntityDef)
SetEntityDefs 运行时更新全局实体类型定义列表。 用于用户在界面上保存知识标签选择后，同步到正在运行的 GraphIndexer。 下次索引调用会使用新的实体定义。
func (*GraphIndexer) SetEntityDefsByRegion ¶ added in v2.0.6
func (idx *GraphIndexer) SetEntityDefsByRegion(regionID string, defs []EntityDef)
SetEntityDefsByRegion 设置指定 region 的实体类型定义。 regionID 通常为项目目录的 SHA256 哈希。 AddFile 时会优先使用 region 级定义，没有时才回退到全局 entityDefs。
func (*GraphIndexer) StoreChunk ¶
StoreChunk stores a pre-built chunk directly in the index, skipping LLM processing and entity extraction. The chunk's Metadata is persisted as vector metadata for filter-based retrieval. This is used by the memory system to store raw memory data without running through the LLM chunking/entity pipeline.
func (*GraphIndexer) Tree ¶ added in v2.0.4
func (idx *GraphIndexer) Tree(ctx context.Context, regionID string, depth int) (*core.ChunkNode, error)
Tree 返回语义分片树（ChunkNode）。
用于 Sidebar 导航展示，与力导向实体图（Search）各自独立。 分片树和实体图通过 ChunkIDs 关联，而非直接嵌套。
regionID 为空时返回全局树（所有 Region 为第一级子节点）， 非空时返回该 Region 的子树。
不会修改 Search 方法。
func (*GraphIndexer) Type ¶
func (idx *GraphIndexer) Type() string
func (*GraphIndexer) UseEnglish ¶ added in v2.0.9
func (idx *GraphIndexer) UseEnglish()
UseEnglish switches prompt templates to English. Default is Chinese. Call this to use English prompts instead.
func (*GraphIndexer) VectorDB ¶
func (idx *GraphIndexer) VectorDB() core.VectorStore
VectorDB 返回 GraphIndexer 持有的向量数据库实例。 外部可通过此方法直接操作向量存储（如批量删除、统计等）。
type GraphOption ¶
type GraphOption func(*GraphIndexer)
GraphOption configures a GraphIndexer.
func WithLogger ¶
func WithLogger(logger logging.Logger) GraphOption
WithLogger attaches a logger to the GraphIndexer for observation logs.
func WithSchemas ¶
func WithSchemas(entityDefs ...EntityDef) GraphOption
WithSchemas 为 GraphIndexer 指定实体类型定义。 每项是一个 EntityDef（Prompt + Schema），会分别注入 Prompt 的 ### Entity Types 和 ### Entity Schema 段。多次调用会累积所有定义。 不调用该方法时，使用一组通用的默认实体类型。
func WithSchemasFromFS ¶
func WithSchemasFromFS(fsys fs.FS, glob string) GraphOption
WithSchemasFromFS 从文件系统（如 embed.FS）中读取匹配 glob 模式的实体类型配置文件， 解析后注入到 GraphIndexer。匹配多个文件时会合并所有实体类型定义。
用法：
//go:embed settings/entities-*.yml
var runtimeFS embed.FS
idx := New(cfg, embedder, vdb, gdb,
WithSchemasFromFS(runtimeFS, "settings/entities-*.yml"),
)
type IndexData ¶
type IndexData struct {
Chunks []struct {
Content string `json:"content"`
Metadata map[string]any `json:"metadata,omitempty"`
ChunkMeta struct {
Positions [][2]int `json:"positions"`
} `json:"chunk_meta,omitempty"`
} `json:"chunks"`
Entities []struct {
ID int `json:"id"`
Type string `json:"type"`
Name string `json:"name"`
Properties map[string]any `json:"properties,omitempty"`
} `json:"entities"`
Relations []struct {
Source int `json:"source"`
Target int `json:"target"`
Type string `json:"type"`
Predicate string `json:"predicate,omitempty"`
Properties map[string]any `json:"properties,omitempty"`
} `json:"relations"`
}
IndexData LLM 返回的顶层 JSON 结构。 字段设计对齐 core.Chunk / core.Node / core.Edge，减少后处理映射。 ID 字段使用序数（1, 2, 3...），由 writeToStores 解析为真实存储 ID。
type IndexError ¶
type IndexError struct {
DocID string // 文档 ID
Err error // 原始错误
ErrorType string // 错误分类: network | timeout | rate_limit | auth | api | unknown
Attempts int // 重试次数
Duration time.Duration // 总耗时
Messages []chat.Message // 请求消息快照（值传递，只读）
}
IndexError 包含 LLM 索引失败的详细信息，传递给 OnFail 钩子。
type ModelConfig ¶
type ModelConfig struct {
APIKey string
BaseURL string
Model string
Language string // 内容语言英文名（如 "Chinese", "English", "Japanese"），直接注入提示词
MaxTokens int // 模型的最大输出 token 数，也用于分页预算计算，0 表示使用默认值 128000
ContextLength int // 模型的总上下文长度（token 数），0 表示使用默认值 defaultMaxTokens
ThinkingBudget int // 思考模式的 token 预算（0 = 模型默认值），GraphIndexer 始终启用思考模式
}
ModelConfig LLM 模型连接配置
type RegionIndexer ¶ added in v2.0.3
type RegionIndexer struct {
// contains filtered or unexported fields
}
RegionIndexer 对一个已索引目录生成 Region 描述文件（README.md）。
Region 是"摘要的摘要"——它的聚合输入只包含该目录下两类摘要级向量：
- 本层文件的 Root Chunk（chunk_type = "root"）：文件级摘要
- 子目录的子 Region（README.md）：子目录级摘要
普通分段（chunk_type = "segment"）不参与 Region 聚合，确保 Region 只做层级抽象而不被细节污染。
生成流程：
- 若 README.md 已存在 → 直接复用，跳过 LLM 聚合
- 若 README.md 不存在 → 聚合摘要 → 写入 README.md 文件
- 在图数据库中创建 Region Node + CONTAINS 边
- 调用方负责将 README.md 通过 GraphIndexer 索引
时序要求：IndexRegion 必须在目标目录下所有文件的 Chunk 已写入 VectorStore 之后调用。调用方（通常是编排层）负责确保时序正确。
func NewRegionIndexer ¶ added in v2.0.3
func NewRegionIndexer( model ModelConfig, embedder core.Embedder, vectorDB core.VectorStore, opts ...RegionOption, ) *RegionIndexer
NewRegionIndexer 创建 RegionIndexer。
func (*RegionIndexer) IndexRegion ¶ added in v2.0.3
func (r *RegionIndexer) IndexRegion(ctx context.Context, dir string) (*RegionResult, error)
IndexRegion 对指定目录生成或复用 Region 描述文件（README.md）并创建图结构。
核心策略：优先复用目录下已存在的 README.md，避免覆盖用户编写的内容； 仅在 README.md 不存在时才走 LLM 聚合生成流程。
流程：
- 通过 region_id 过滤查询 VectorStore，获取该目录下全部向量
- 检查目录下 README.md 是否已存在： - 已存在 → 直接复用，跳过 LLM 聚合（仍会更新图结构） - 不存在 → 进入聚合流程
- 聚合时只取摘要级向量： - chunk_type = "root" → 文件级文档摘要 - region = true → 子目录级 Region 摘要（兼容旧版，新版来自 README.md 的向量） - chunk_type = "segment" → 忽略（不入聚合）
- 用 LLM 对摘要做二次抽象（摘要的摘要 + 实体关系补充）
- 将内容写入目录下的 README.md 文件
- 在图数据库中创建/更新 Region Node + CONTAINS 边
返回的 RegionResult 包含 RegionFilePath，调用方应将其通过 GraphIndexer.AddFile 索引。
特殊情况：
- 目录无内容（无任何向量）且 README.md 不存在：返回 nil
- 目录无内容但 README.md 已存在：复用 README.md，仍创建图结构
- 目录有文件但无摘要级向量：生成降级摘要，仍会写入 README.md
type RegionOption ¶ added in v2.0.3
type RegionOption func(*RegionIndexer)
RegionOption 配置 RegionIndexer 的可选参数。
func RegionWithGraphStore ¶ added in v2.0.3
func RegionWithGraphStore(gs core.GraphStore) RegionOption
RegionWithGraphStore 为 RegionIndexer 附加图数据库，用于创建 Region Node 和边。
func RegionWithLogger ¶ added in v2.0.3
func RegionWithLogger(logger logging.Logger) RegionOption
RegionWithLogger 为 RegionIndexer 附加日志记录器。
type RegionResult ¶ added in v2.0.4
type RegionResult struct {
*core.Region
RegionFilePath string // Region 描述文件路径（已存在或新生成的 README.md），为空表示无需索引
}
RegionResult 是 IndexRegion 的返回结果。
type SemanticOption ¶
type SemanticOption func(*semanticIndexer)
SemanticOption configures a semantic indexer.
func WithSemanticLogger ¶
func WithSemanticLogger(logger logging.Logger) SemanticOption
WithSemanticLogger attaches a logger to the semantic indexer for observation logs.
type TokenUsage ¶
type TokenUsage struct {
PromptTokens int `json:"prompt_tokens"`
CompletionTokens int `json:"completion_tokens"`
TotalTokens int `json:"total_tokens"`
// CacheTokens is the number of cached prompt tokens read from cache.
// Populated from resp.Usage.PromptTokensDetails.CachedTokens.
CacheTokens int `json:"cache_tokens,omitempty"`
}
TokenUsage 单次 LLM 调用的 Token 消耗
Source Files