From 164dafca85a477ced3c5f7f7be65433fa4435276 Mon Sep 17 00:00:00 2001 From: Xinliang Zheng Date: Sat, 17 Oct 2026 23:00:55 +0800 Subject: [PATCH] feat(graph): add standalone JSON graph search API (#4395) --- docs/docs.go | 282 +++++++++++++++++ docs/swagger.json | 282 +++++++++++++++++ docs/swagger.yaml | 184 +++++++++++ docs/swagger_contract_test.go | 40 +++ .../application/repository/graph_search.go | 63 ++++ .../repository/graph_search_test.go | 88 ++++++ .../retriever/neo4j/graph_search.go | 192 +++++++++++ .../retriever/neo4j/graph_search_test.go | 169 ++++++++++ internal/application/service/graph_search.go | 242 ++++++++++++++ .../application/service/graph_search_test.go | 298 ++++++++++++++++++ internal/container/container.go | 4 + internal/handler/graph_search.go | 75 +++++ internal/handler/graph_search_test.go | 198 ++++++++++++ internal/router/router.go | 2 + internal/router/routes_graph.go | 18 ++ internal/router/routes_graph_test.go | 27 ++ internal/types/graph_search.go | 114 +++++++ internal/types/graph_search_test.go | 36 +++ internal/types/interfaces/graph_search.go | 25 ++ .../03-features/09-knowledge-graph.md | 10 +- website-docs/04-api/02-api-knowledge.md | 39 +++ 21 files changed, 2386 insertions(+), 2 deletions(-) create mode 100644 internal/application/repository/graph_search.go create mode 100644 internal/application/repository/graph_search_test.go create mode 100644 internal/application/repository/retriever/neo4j/graph_search.go create mode 100644 internal/application/repository/retriever/neo4j/graph_search_test.go create mode 100644 internal/application/service/graph_search.go create mode 100644 internal/application/service/graph_search_test.go create mode 100644 internal/handler/graph_search.go create mode 100644 internal/handler/graph_search_test.go create mode 100644 internal/router/routes_graph.go create mode 100644 internal/router/routes_graph_test.go create mode 100644 internal/types/graph_search.go create mode 100644 internal/types/graph_search_test.go create mode 100644 internal/types/interfaces/graph_search.go diff --git a/docs/docs.go b/docs/docs.go index 4464d9d2..826588e6 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -6272,6 +6272,121 @@ const docTemplate = `{ } } }, + "/knowledge-bases/{id}/graph-search": { + "post": { + "security": [ + { + "Bearer": [] + }, + { + "ApiKeyAuth": [] + } + ], + "description": "对单个授权知识库按实体名进行区分大小写的子串查询,返回实体、定向关系及仍然有效的来源分块。不调用模型,不影响默认检索。0 表示使用默认上限。", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "知识库" + ], + "summary": "查询知识图谱", + "parameters": [ + { + "type": "string", + "description": "知识库ID", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "共享智能体 ID", + "name": "agent_id", + "in": "query" + }, + { + "type": "integer", + "description": "共享智能体来源空间", + "name": "agent_source_tenant_id", + "in": "query" + }, + { + "description": "查询及结果上限", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/internal_handler.DataResponse" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchResult" + } + } + } + ] + } + }, + "400": { + "description": "参数错误", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + }, + "401": { + "description": "未登录", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + }, + "403": { + "description": "无权访问知识库", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + }, + "404": { + "description": "知识库不存在", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + }, + "409": { + "description": "知识图谱未启用", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + }, + "500": { + "description": "来源校验失败", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + }, + "503": { + "description": "图谱服务不可用", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + } + } + } + }, "/knowledge-bases/{id}/hybrid-search": { "get": { "security": [ @@ -27334,6 +27449,173 @@ const docTemplate = `{ } } }, + "github_com_Tencent_WeKnora_internal_types.GraphSearchEntity": { + "type": "object", + "properties": { + "attributes": { + "type": "array", + "items": { + "type": "string" + } + }, + "id": { + "type": "string" + }, + "knowledge_id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "source_chunk_ids": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "github_com_Tencent_WeKnora_internal_types.GraphSearchMeta": { + "type": "object", + "properties": { + "max_nodes": { + "type": "integer" + }, + "max_relations": { + "type": "integer" + }, + "max_source_chunks": { + "type": "integer" + }, + "truncated": { + "type": "boolean" + }, + "truncation_reasons": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "github_com_Tencent_WeKnora_internal_types.GraphSearchRelation": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "source_chunk_ids": { + "type": "array", + "items": { + "type": "string" + } + }, + "source_id": { + "type": "string" + }, + "target_id": { + "type": "string" + }, + "type": { + "type": "string" + } + } + }, + "github_com_Tencent_WeKnora_internal_types.GraphSearchRequest": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "max_nodes": { + "type": "integer", + "default": 50, + "maximum": 100, + "minimum": 0 + }, + "max_relations": { + "type": "integer", + "default": 100, + "maximum": 200, + "minimum": 0 + }, + "max_source_chunks": { + "type": "integer", + "default": 20, + "maximum": 50, + "minimum": 0 + }, + "query": { + "type": "string", + "maxLength": 512, + "minLength": 1 + } + } + }, + "github_com_Tencent_WeKnora_internal_types.GraphSearchResult": { + "type": "object", + "properties": { + "entities": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchEntity" + } + }, + "knowledge_base_id": { + "type": "string" + }, + "meta": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchMeta" + }, + "query": { + "type": "string" + }, + "relationships": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchRelation" + } + }, + "source_chunks": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchSourceChunk" + } + } + } + }, + "github_com_Tencent_WeKnora_internal_types.GraphSearchSourceChunk": { + "type": "object", + "properties": { + "chunk_index": { + "type": "integer" + }, + "content": { + "type": "string" + }, + "content_truncated": { + "type": "boolean" + }, + "end_at": { + "type": "integer" + }, + "id": { + "type": "string" + }, + "knowledge_id": { + "type": "string" + }, + "start_at": { + "type": "integer" + }, + "title": { + "type": "string" + }, + "title_truncated": { + "type": "boolean" + } + } + }, "github_com_Tencent_WeKnora_internal_types.History": { "type": "object", "properties": { diff --git a/docs/swagger.json b/docs/swagger.json index 2b7d1306..5ae09e89 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -6265,6 +6265,121 @@ } } }, + "/knowledge-bases/{id}/graph-search": { + "post": { + "security": [ + { + "Bearer": [] + }, + { + "ApiKeyAuth": [] + } + ], + "description": "对单个授权知识库按实体名进行区分大小写的子串查询,返回实体、定向关系及仍然有效的来源分块。不调用模型,不影响默认检索。0 表示使用默认上限。", + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "tags": [ + "知识库" + ], + "summary": "查询知识图谱", + "parameters": [ + { + "type": "string", + "description": "知识库ID", + "name": "id", + "in": "path", + "required": true + }, + { + "type": "string", + "description": "共享智能体 ID", + "name": "agent_id", + "in": "query" + }, + { + "type": "integer", + "description": "共享智能体来源空间", + "name": "agent_source_tenant_id", + "in": "query" + }, + { + "description": "查询及结果上限", + "name": "request", + "in": "body", + "required": true, + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchRequest" + } + } + ], + "responses": { + "200": { + "description": "OK", + "schema": { + "allOf": [ + { + "$ref": "#/definitions/internal_handler.DataResponse" + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchResult" + } + } + } + ] + } + }, + "400": { + "description": "参数错误", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + }, + "401": { + "description": "未登录", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + }, + "403": { + "description": "无权访问知识库", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + }, + "404": { + "description": "知识库不存在", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + }, + "409": { + "description": "知识图谱未启用", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + }, + "500": { + "description": "来源校验失败", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + }, + "503": { + "description": "图谱服务不可用", + "schema": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError" + } + } + } + } + }, "/knowledge-bases/{id}/hybrid-search": { "get": { "security": [ @@ -27327,6 +27442,173 @@ } } }, + "github_com_Tencent_WeKnora_internal_types.GraphSearchEntity": { + "type": "object", + "properties": { + "attributes": { + "type": "array", + "items": { + "type": "string" + } + }, + "id": { + "type": "string" + }, + "knowledge_id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "source_chunk_ids": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "github_com_Tencent_WeKnora_internal_types.GraphSearchMeta": { + "type": "object", + "properties": { + "max_nodes": { + "type": "integer" + }, + "max_relations": { + "type": "integer" + }, + "max_source_chunks": { + "type": "integer" + }, + "truncated": { + "type": "boolean" + }, + "truncation_reasons": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "github_com_Tencent_WeKnora_internal_types.GraphSearchRelation": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "source_chunk_ids": { + "type": "array", + "items": { + "type": "string" + } + }, + "source_id": { + "type": "string" + }, + "target_id": { + "type": "string" + }, + "type": { + "type": "string" + } + } + }, + "github_com_Tencent_WeKnora_internal_types.GraphSearchRequest": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "max_nodes": { + "type": "integer", + "default": 50, + "maximum": 100, + "minimum": 0 + }, + "max_relations": { + "type": "integer", + "default": 100, + "maximum": 200, + "minimum": 0 + }, + "max_source_chunks": { + "type": "integer", + "default": 20, + "maximum": 50, + "minimum": 0 + }, + "query": { + "type": "string", + "maxLength": 512, + "minLength": 1 + } + } + }, + "github_com_Tencent_WeKnora_internal_types.GraphSearchResult": { + "type": "object", + "properties": { + "entities": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchEntity" + } + }, + "knowledge_base_id": { + "type": "string" + }, + "meta": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchMeta" + }, + "query": { + "type": "string" + }, + "relationships": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchRelation" + } + }, + "source_chunks": { + "type": "array", + "items": { + "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchSourceChunk" + } + } + } + }, + "github_com_Tencent_WeKnora_internal_types.GraphSearchSourceChunk": { + "type": "object", + "properties": { + "chunk_index": { + "type": "integer" + }, + "content": { + "type": "string" + }, + "content_truncated": { + "type": "boolean" + }, + "end_at": { + "type": "integer" + }, + "id": { + "type": "string" + }, + "knowledge_id": { + "type": "string" + }, + "start_at": { + "type": "integer" + }, + "title": { + "type": "string" + }, + "title_truncated": { + "type": "boolean" + } + } + }, "github_com_Tencent_WeKnora_internal_types.History": { "type": "object", "properties": { diff --git a/docs/swagger.yaml b/docs/swagger.yaml index ee9b480a..ffa67070 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -3546,6 +3546,119 @@ definitions: type: type: string type: object + github_com_Tencent_WeKnora_internal_types.GraphSearchEntity: + properties: + attributes: + items: + type: string + type: array + id: + type: string + knowledge_id: + type: string + name: + type: string + source_chunk_ids: + items: + type: string + type: array + type: object + github_com_Tencent_WeKnora_internal_types.GraphSearchMeta: + properties: + max_nodes: + type: integer + max_relations: + type: integer + max_source_chunks: + type: integer + truncated: + type: boolean + truncation_reasons: + items: + type: string + type: array + type: object + github_com_Tencent_WeKnora_internal_types.GraphSearchRelation: + properties: + id: + type: string + source_chunk_ids: + items: + type: string + type: array + source_id: + type: string + target_id: + type: string + type: + type: string + type: object + github_com_Tencent_WeKnora_internal_types.GraphSearchRequest: + properties: + max_nodes: + default: 50 + maximum: 100 + minimum: 0 + type: integer + max_relations: + default: 100 + maximum: 200 + minimum: 0 + type: integer + max_source_chunks: + default: 20 + maximum: 50 + minimum: 0 + type: integer + query: + maxLength: 512 + minLength: 1 + type: string + required: + - query + type: object + github_com_Tencent_WeKnora_internal_types.GraphSearchResult: + properties: + entities: + items: + $ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchEntity' + type: array + knowledge_base_id: + type: string + meta: + $ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchMeta' + query: + type: string + relationships: + items: + $ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchRelation' + type: array + source_chunks: + items: + $ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchSourceChunk' + type: array + type: object + github_com_Tencent_WeKnora_internal_types.GraphSearchSourceChunk: + properties: + chunk_index: + type: integer + content: + type: string + content_truncated: + type: boolean + end_at: + type: integer + id: + type: string + knowledge_id: + type: string + start_at: + type: integer + title: + type: string + title_truncated: + type: boolean + type: object github_com_Tencent_WeKnora_internal_types.History: properties: answer: @@ -17748,6 +17861,77 @@ paths: summary: 搜索FAQ tags: - FAQ管理 + /knowledge-bases/{id}/graph-search: + post: + consumes: + - application/json + description: 对单个授权知识库按实体名进行区分大小写的子串查询,返回实体、定向关系及仍然有效的来源分块。不调用模型,不影响默认检索。0 表示使用默认上限。 + parameters: + - description: 知识库ID + in: path + name: id + required: true + type: string + - description: 共享智能体 ID + in: query + name: agent_id + type: string + - description: 共享智能体来源空间 + in: query + name: agent_source_tenant_id + type: integer + - description: 查询及结果上限 + in: body + name: request + required: true + schema: + $ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchRequest' + produces: + - application/json + responses: + "200": + description: OK + schema: + allOf: + - $ref: '#/definitions/internal_handler.DataResponse' + - properties: + data: + $ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.GraphSearchResult' + type: object + "400": + description: 参数错误 + schema: + $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError' + "401": + description: 未登录 + schema: + $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError' + "403": + description: 无权访问知识库 + schema: + $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError' + "404": + description: 知识库不存在 + schema: + $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError' + "409": + description: 知识图谱未启用 + schema: + $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError' + "500": + description: 来源校验失败 + schema: + $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError' + "503": + description: 图谱服务不可用 + schema: + $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError' + security: + - Bearer: [] + - ApiKeyAuth: [] + summary: 查询知识图谱 + tags: + - 知识库 /knowledge-bases/{id}/hybrid-search: get: consumes: diff --git a/docs/swagger_contract_test.go b/docs/swagger_contract_test.go index 1be752cf..fcf5816a 100644 --- a/docs/swagger_contract_test.go +++ b/docs/swagger_contract_test.go @@ -113,6 +113,46 @@ func TestReleaseAPIContracts(t *testing.T) { } } +func TestGraphSearchContract(t *testing.T) { + for _, tt := range swaggerDocuments() { + t.Run(tt.name, func(t *testing.T) { + var spec struct { + Paths map[string]map[string]any `json:"paths" yaml:"paths"` + Definitions map[string]struct { + Properties map[string]any `json:"properties" yaml:"properties"` + } `json:"definitions" yaml:"definitions"` + } + if err := tt.parse(tt.loadSpec(t), &spec); err != nil { + t.Fatal(err) + } + methods := spec.Paths["/knowledge-bases/{id}/graph-search"] + if methods["post"] == nil || len(methods) != 1 { + t.Fatal("graph-search must be documented as a POST-only endpoint") + } + const prefix = "github_com_Tencent_WeKnora_internal_types." + for definition, fields := range map[string][]string{ + "GraphSearchResult": {"entities", "relationships", "source_chunks", "meta"}, + "GraphSearchEntity": {"id", "knowledge_id", "source_chunk_ids"}, + "GraphSearchRelation": {"source_id", "target_id", "source_chunk_ids"}, + "GraphSearchSourceChunk": {"content_truncated", "title_truncated"}, + "GraphSearchMeta": {"truncated", "truncation_reasons"}, + } { + properties := spec.Definitions[prefix+definition].Properties + for _, field := range fields { + if properties[field] == nil { + t.Errorf("%s.%s must be documented", definition, field) + } + } + for _, hidden := range []string{"tenant_id", "knowledge_base_id", "element_id"} { + if definition != "GraphSearchResult" && properties[hidden] != nil { + t.Errorf("%s leaks internal field %s", definition, hidden) + } + } + } + }) + } +} + func TestModelDeleteUsageContract(t *testing.T) { for _, tt := range swaggerDocuments() { t.Run(tt.name, func(t *testing.T) { diff --git a/internal/application/repository/graph_search.go b/internal/application/repository/graph_search.go new file mode 100644 index 00000000..5b951c9f --- /dev/null +++ b/internal/application/repository/graph_search.go @@ -0,0 +1,63 @@ +package repository + +import ( + "context" + "fmt" + + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" + "gorm.io/gorm" +) + +type graphSearchEvidenceRepository struct { + db *gorm.DB +} + +// NewGraphSearchEvidenceRepository constructs the scoped live-source projection. +func NewGraphSearchEvidenceRepository(db *gorm.DB) interfaces.GraphSearchEvidenceRepository { + return &graphSearchEvidenceRepository{db: db} +} + +func (r *graphSearchEvidenceRepository) GetGraphSourceChunks( + ctx context.Context, tenantID uint64, kbID string, ids []string, +) ([]types.GraphSearchSourceChunk, error) { + if tenantID == 0 || kbID == "" || len(ids) > types.GraphSearchMaxEvidence { + return nil, fmt.Errorf("invalid graph evidence scope or budget") + } + rows := []types.GraphSearchSourceChunk{} + if len(ids) == 0 { + return rows, nil + } + // Explicit soft-delete predicates are necessary: Table/Joins do not apply + // the two models' GORM default scopes. SUBSTR is supported by every SQL + // backend; fetching one extra character detects clipping without loading + // unbounded content or doing a second, racy metadata-to-content lookup. + err := r.db.WithContext(ctx).Table("chunks AS c"). + Select(`c.id, c.tenant_id, c.knowledge_base_id, c.knowledge_id, + c.chunk_index, c.start_at, c.end_at, + SUBSTR(c.content, 1, ?) AS content, SUBSTR(k.title, 1, 513) AS title`, + types.GraphSearchMaxContentRunes+1). + Joins(`JOIN knowledges AS k ON k.id = c.knowledge_id + AND k.tenant_id = c.tenant_id AND k.knowledge_base_id = c.knowledge_base_id`). + Where("c.tenant_id = ? AND c.knowledge_base_id = ? AND c.id IN ?", tenantID, kbID, ids). + Where("c.deleted_at IS NULL AND k.deleted_at IS NULL AND c.is_enabled = ?", true). + Where("k.enable_status = ? AND k.parse_status <> ?", "enabled", types.ParseStatusDeleting). + Where("(c.index_status = ? OR c.index_status = ?)", "ready", ""). + Order("c.id").Scan(&rows).Error + if err != nil { + return nil, err + } + for i := range rows { + rows[i].Content, rows[i].ContentTruncated = graphSearchClip(rows[i].Content, types.GraphSearchMaxContentRunes) + rows[i].Title, rows[i].TitleTruncated = graphSearchClip(rows[i].Title, 512) + } + return rows, nil +} + +func graphSearchClip(text string, limit int) (string, bool) { + runes := []rune(text) // SQL has already bounded this allocation. + if len(runes) > limit { + return string(runes[:limit]), true + } + return text, false +} diff --git a/internal/application/repository/graph_search_test.go b/internal/application/repository/graph_search_test.go new file mode 100644 index 00000000..02dbfddb --- /dev/null +++ b/internal/application/repository/graph_search_test.go @@ -0,0 +1,88 @@ +package repository + +import ( + "context" + "strings" + "testing" + "time" + "unicode/utf8" + + "github.com/Tencent/WeKnora/internal/types" + "github.com/stretchr/testify/require" + "gorm.io/driver/sqlite" + "gorm.io/gorm" +) + +func TestGraphSearchLiveEvidenceSQL(t *testing.T) { + db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{}) + require.NoError(t, err) + sqlDB, err := db.DB() + require.NoError(t, err) + t.Cleanup(func() { require.NoError(t, sqlDB.Close()) }) + require.NoError(t, db.AutoMigrate(&types.Knowledge{}, &types.Chunk{})) + for _, name := range []string{ + "live", "chunk-deleted", "doc-deleted", "chunk-disabled", "doc-disabled", + "deleting", "wrong-tenant", "wrong-kb", "wrong-parent", "indexing", "long", + } { + doc := &types.Knowledge{ + ID: name, TenantID: 7, KnowledgeBaseID: "kb", + EnableStatus: "enabled", ParseStatus: types.ParseStatusCompleted, Title: "标题", + } + chunk := &types.Chunk{ + ID: name, TenantID: 7, KnowledgeBaseID: "kb", KnowledgeID: name, + Content: "内容", IsEnabled: true, IndexStatus: "ready", + } + switch name { + case "chunk-deleted": + chunk.DeletedAt = gorm.DeletedAt{Time: time.Now(), Valid: true} + case "doc-deleted": + doc.DeletedAt = gorm.DeletedAt{Time: time.Now(), Valid: true} + case "chunk-disabled": + // GORM's default:true would rewrite false at insert; disable below. + case "doc-disabled": + doc.EnableStatus = "disabled" + case "deleting": + doc.ParseStatus = types.ParseStatusDeleting + case "wrong-tenant": + chunk.TenantID, doc.TenantID = 8, 8 + case "wrong-kb": + chunk.KnowledgeBaseID, doc.KnowledgeBaseID = "other", "other" + case "wrong-parent": + doc.KnowledgeBaseID = "other" + case "indexing": + chunk.IndexStatus = "processing" + case "long": + chunk.Content = strings.Repeat("中", 2100) + doc.Title = strings.Repeat("题", 600) + } + require.NoError(t, db.Create(doc).Error) + require.NoError(t, db.Create(chunk).Error) + } + require.NoError(t, db.Model(&types.Chunk{}).Where("id = ?", "chunk-disabled"). + UpdateColumn("is_enabled", false).Error) + repo := NewGraphSearchEvidenceRepository(db) + ids := []string{ + "live", "chunk-deleted", "doc-deleted", "chunk-disabled", "doc-disabled", + "deleting", "wrong-tenant", "wrong-kb", "wrong-parent", "indexing", "missing", "long", + } + rows, err := repo.GetGraphSourceChunks(context.Background(), 7, "kb", ids) + require.NoError(t, err) + require.Len(t, rows, 2) + require.Equal(t, "live", rows[0].ID) + require.Equal(t, "内容", rows[0].Content) + require.False(t, rows[0].ContentTruncated) + require.Equal(t, "long", rows[1].ID) + require.Equal(t, 2000, utf8.RuneCountInString(rows[1].Content)) + require.True(t, utf8.ValidString(rows[1].Content)) + require.True(t, rows[1].ContentTruncated) + require.Equal(t, 512, utf8.RuneCountInString(rows[1].Title)) + require.True(t, rows[1].TitleTruncated) + _, err = repo.GetGraphSourceChunks(context.Background(), 7, "kb", make([]string, 513)) + require.Error(t, err) + _, err = repo.GetGraphSourceChunks(context.Background(), 0, "kb", []string{"live"}) + require.Error(t, err) + require.NoError(t, db.Migrator().DropTable(&types.Chunk{})) + rows, err = repo.GetGraphSourceChunks(context.Background(), 7, "kb", []string{"live"}) + require.Error(t, err) + require.Nil(t, rows, "database failure is not an empty successful search") +} diff --git a/internal/application/repository/retriever/neo4j/graph_search.go b/internal/application/repository/retriever/neo4j/graph_search.go new file mode 100644 index 00000000..9d47d530 --- /dev/null +++ b/internal/application/repository/retriever/neo4j/graph_search.go @@ -0,0 +1,192 @@ +// Package neo4j implements the knowledge graph storage and query adapters. +package neo4j + +import ( + "context" + "fmt" + "strings" + + "github.com/Tencent/WeKnora/internal/logger" + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" + "github.com/neo4j/neo4j-go-driver/v6/neo4j" +) + +// NewGraphSearchRepository constructs the bounded public-query adapter. +func NewGraphSearchRepository(driver neo4j.Driver) interfaces.GraphSearchRepository { + return &Neo4jRepository{driver: driver, nodePrefix: "ENTITY"} +} + +// graphSearchProjection bounds fields before they cross Bolt. One extra item +// (or character) lets the service report clipping instead of a false total. +func graphSearchProjection(alias string) string { + return alias + ` { + id: elementId(` + alias + `), + name: substring(` + alias + `.name, 0, 513), + knowledge_id: substring(` + alias + `.kg, 0, 129), + chunks: [c IN ` + alias + `.chunks[..513] | substring(c, 0, 129)], + attributes: [a IN ` + alias + `.attributes[..21] | substring(a, 0, 1001)] + }` +} + +// graphSearchLabel quotes every identifier. KB IDs are data, never Cypher, +// including imported/legacy IDs containing punctuation or backticks. +func (n *Neo4jRepository) graphSearchLabel(namespace types.NameSpace) (string, error) { + if namespace.KnowledgeBase == "" || namespace.Knowledge != "" { + return "", fmt.Errorf("graph search requires exactly one knowledge base") + } + labels := n.Labels(namespace) + for i, label := range labels { + labels[i] = "`" + strings.ReplaceAll(label, "`", "``") + "`" + } + return strings.Join(labels, ":"), nil +} + +// SearchGraph returns ranked seed entities and a bounded one-hop neighbourhood. +func (n *Neo4jRepository) SearchGraph( + ctx context.Context, namespace types.NameSpace, query string, +) (*types.GraphSearchCandidates, error) { + if n.driver == nil { + return nil, nil // Distinguished from an available backend with no matches. + } + label, err := n.graphSearchLabel(namespace) + if err != nil { + return nil, err + } + session := n.driver.NewSession(ctx, neo4j.SessionConfig{AccessMode: neo4j.AccessModeRead}) + defer func() { + if err := session.Close(ctx); err != nil { + logger.Warnf(ctx, "Failed to close graph query session: %v", err) + } + }() + value, err := session.ExecuteRead(ctx, func(tx neo4j.ManagedTransaction) (any, error) { + out := &types.GraphSearchCandidates{Graph: &types.GraphData{}} + seedResult, err := tx.Run(ctx, ` + MATCH (n:`+label+`) + WHERE n.name CONTAINS $query + WITH n ORDER BY CASE WHEN n.name = $query THEN 0 ELSE 1 END, + size(n.name), n.name, n.kg, elementId(n) + LIMIT $probeLimit + RETURN `+graphSearchProjection("n")+` AS n`, + map[string]any{"query": query, "probeLimit": types.GraphSearchMaxSeeds + 1}) + if err != nil { + return nil, err + } + seedIDs := []string{} + seen := map[string]bool{} + for seedResult.Next(ctx) { + if len(seedIDs) == types.GraphSearchMaxSeeds { + out.TruncationReasons = append(out.TruncationReasons, "candidate_seeds") + continue + } + node, err := decodeGraphSearchProjection(seedResult.Record(), "n") + if err != nil { + return nil, err + } + seedIDs = append(seedIDs, node.ID) + seen[node.ID] = true + out.Graph.Node = append(out.Graph.Node, node) + } + if err := seedResult.Err(); err != nil { + return nil, err + } + if len(seedIDs) == 0 { + return out, nil + } + // Keep relation-less seeds, and expand each stored edge only from its + // earliest seed. Target matches cannot reverse the stored direction or + // fill the budget twice. Both endpoints must carry the KB label. + rows, err := tx.Run(ctx, ` + UNWIND range(0, size($seeds) - 1) AS seed_index + MATCH (n:`+label+`) WHERE elementId(n) = $seeds[seed_index] + MATCH (n)-[r]-(m:`+label+`) + WHERE NOT elementId(m) IN $seeds[0..seed_index] + WITH n, r, m, seed_index ORDER BY seed_index, elementId(r) + LIMIT $probeLimit + RETURN `+graphSearchProjection("n")+` AS n, `+graphSearchProjection("m")+` AS m, + elementId(r) AS id, elementId(startNode(r)) AS source_id, + elementId(endNode(r)) AS target_id, substring(type(r), 0, 129) AS type`, + map[string]any{"seeds": seedIDs, "probeLimit": types.GraphSearchMaxRows + 1}) + if err != nil { + return nil, err + } + count := 0 + for rows.Next(ctx) { + if count == types.GraphSearchMaxRows { + out.TruncationReasons = append(out.TruncationReasons, "candidate_relations") + continue + } + count++ + for _, alias := range []string{"n", "m"} { + node, err := decodeGraphSearchProjection(rows.Record(), alias) + if err != nil { + return nil, err + } + if !seen[node.ID] { + out.Graph.Node = append(out.Graph.Node, node) + seen[node.ID] = true + } + } + relation := &types.GraphRelation{} + for field, dest := range map[string]*string{ + "id": &relation.ID, "source_id": &relation.SourceID, + "target_id": &relation.TargetID, "type": &relation.Type, + } { + v, _, err := neo4j.GetRecordValue[string](rows.Record(), field) + if err != nil || v == "" { + return nil, fmt.Errorf("invalid graph relationship field %s", field) + } + *dest = v + } + if !seen[relation.SourceID] || !seen[relation.TargetID] { + return nil, fmt.Errorf("graph relationship has an unreturned endpoint") + } + out.Graph.Relation = append(out.Graph.Relation, relation) + } + if err := rows.Err(); err != nil { + return nil, err + } + return out, nil + }, neo4j.WithTxTimeout(types.GraphSearchTimeout)) + if err != nil { + return nil, err + } + return value.(*types.GraphSearchCandidates), nil +} + +func decodeGraphSearchProjection(record *neo4j.Record, alias string) (*types.GraphNode, error) { + if record == nil { + return nil, fmt.Errorf("nil graph search record") + } + value, ok := record.Get(alias) + props, isMap := value.(map[string]any) + if !ok || !isMap { + return nil, fmt.Errorf("invalid graph node projection") + } + node := &types.GraphNode{} + for key, dest := range map[string]*string{"id": &node.ID, "name": &node.Name, "knowledge_id": &node.KnowledgeID} { + value, ok := props[key].(string) + if !ok || value == "" { + return nil, fmt.Errorf("graph node has no %s", key) + } + *dest = value + } + for key, dest := range map[string]*[]string{"chunks": &node.Chunks, "attributes": &node.Attributes} { + *dest = []string{} + if props[key] == nil { + continue + } + values, ok := props[key].([]any) + if !ok { + return nil, fmt.Errorf("invalid graph node %s", key) + } + for _, value := range values { + text, ok := value.(string) + if !ok { + return nil, fmt.Errorf("invalid graph node %s item", key) + } + *dest = append(*dest, text) + } + } + return node, nil +} diff --git a/internal/application/repository/retriever/neo4j/graph_search_test.go b/internal/application/repository/retriever/neo4j/graph_search_test.go new file mode 100644 index 00000000..2b6d4e1b --- /dev/null +++ b/internal/application/repository/retriever/neo4j/graph_search_test.go @@ -0,0 +1,169 @@ +package neo4j + +import ( + "context" + "fmt" + "os" + "strings" + "testing" + "time" + + "github.com/Tencent/WeKnora/internal/types" + "github.com/neo4j/neo4j-go-driver/v6/neo4j" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestGraphSearchLabelAndDisabledBackend(t *testing.T) { + repo := &Neo4jRepository{nodePrefix: "ENTITY"} + label, err := repo.graphSearchLabel(types.NameSpace{KnowledgeBase: "kb-`):MATCH (x)"}) + require.NoError(t, err) + require.Equal(t, "`ENTITYkb_``):MATCH (x)`", label) + _, err = repo.graphSearchLabel(types.NameSpace{}) + require.Error(t, err) + _, err = repo.graphSearchLabel(types.NameSpace{KnowledgeBase: "kb", Knowledge: "doc"}) + require.Error(t, err) + result, err := repo.SearchGraph(context.Background(), types.NameSpace{KnowledgeBase: "kb"}, "Acme") + require.NoError(t, err) + require.Nil(t, result) +} + +func TestGraphSearchProjectionValidation(t *testing.T) { + valid := map[string]any{ + "id": "n", "name": "Acme", "knowledge_id": "doc", + "chunks": []any{"c1"}, "attributes": []any{"attr"}, + } + record := &neo4j.Record{Keys: []string{"n"}, Values: []any{valid}} + node, err := decodeGraphSearchProjection(record, "n") + require.NoError(t, err) + require.Equal(t, []string{"c1"}, node.Chunks) + _, err = decodeGraphSearchProjection(nil, "n") + require.Error(t, err) + for _, key := range []string{"id", "name", "knowledge_id", "chunks", "attributes"} { + props := map[string]any{} + for k, v := range valid { + props[k] = v + } + props[key] = 17 + _, err = decodeGraphSearchProjection(&neo4j.Record{Keys: []string{"n"}, Values: []any{props}}, "n") + require.Error(t, err, key) + } +} + +func TestGraphSearchIntegration(t *testing.T) { + uri := os.Getenv("WEKNORA_NEO4J_TEST_URI") + if uri == "" { + t.Skip("set WEKNORA_NEO4J_TEST_URI to run the live public graph-query regression") + } + ctx, cancel := context.WithTimeout(context.Background(), time.Minute) + defer cancel() + driver, err := neo4j.NewDriver(uri, neo4j.NoAuth()) + require.NoError(t, err) + t.Cleanup(func() { assert.NoError(t, driver.Close(context.Background())) }) + require.NoError(t, driver.VerifyConnectivity(ctx)) + repo := NewGraphSearchRepository(driver).(*Neo4jRepository) + // Exercise escaping against a real engine, not only a string assertion. + ns := types.NameSpace{KnowledgeBase: fmt.Sprintf("public_graph_%d_`", time.Now().UnixNano())} + label, err := repo.graphSearchLabel(ns) + require.NoError(t, err) + outsideLabel, err := repo.graphSearchLabel(types.NameSpace{KnowledgeBase: ns.KnowledgeBase + "_outside"}) + require.NoError(t, err) + t.Cleanup(func() { + cleanupCtx, stop := context.WithTimeout(context.Background(), 10*time.Second) + defer stop() + _, err := neo4j.ExecuteQuery(cleanupCtx, driver, "MATCH (n:"+label+") DETACH DELETE n", + nil, neo4j.EagerResultTransformer) + assert.NoError(t, err) + }) + _, err = neo4j.ExecuteQuery(ctx, driver, ` + CREATE (a:`+label+` {name:'Acme', kg:'doc1', chunks:['c1'], attributes:['attr1']}), + (b:`+label+` {name:'Acme Shanghai', kg:'doc1', chunks:['c1'], attributes:[]}), + (a2:`+label+` {name:'Acme', kg:'doc2', chunks:['c2'], attributes:['attr2']}), + (b2:`+label+` {name:'Acme Shanghai', kg:'doc2', chunks:['c2'], attributes:[]}), + (isolated:`+label+` {name:'Isolated', kg:'doc1', chunks:['c1'], attributes:[]}), + (outside:`+outsideLabel+` {name:'Outside', kg:'secret', chunks:['secret']}), + (a)-[:HEADQUARTERED_IN]->(b), (b)-[:RELATED_TO]->(a), (a)-[:SELF]->(a), + (a2)-[:HAS_BRANCH_IN]->(b2), (a)-[:MUST_NOT_LEAK]->(outside) + `, nil, neo4j.EagerResultTransformer) + require.NoError(t, err) + t.Cleanup(func() { + _, err := neo4j.ExecuteQuery(context.Background(), driver, + "MATCH (n:"+outsideLabel+") DETACH DELETE n", nil, neo4j.EagerResultTransformer) + assert.NoError(t, err) + }) + for _, query := range []string{"Acme", "Shanghai"} { + result, err := repo.SearchGraph(ctx, ns, query) + require.NoError(t, err) + require.Len(t, result.Graph.Node, 4) + expectedRelations := 4 + if query == "Shanghai" { + expectedRelations = 3 // Self-loop is outside this one-hop neighbourhood. + } + require.Len(t, result.Graph.Relation, expectedRelations) + names := map[string]string{} + for _, node := range result.Graph.Node { + names[node.ID] = node.Name + } + for _, relation := range result.Graph.Relation { + require.NotEqual(t, "MUST_NOT_LEAK", relation.Type) + if relation.Type == "HEADQUARTERED_IN" { + require.Equal(t, "Acme", names[relation.SourceID]) + require.Equal(t, "Acme Shanghai", names[relation.TargetID]) + } + } + require.Empty(t, result.TruncationReasons) + } + isolated, err := repo.SearchGraph(ctx, ns, "Isolated") + require.NoError(t, err) + require.Len(t, isolated.Graph.Node, 1) + require.Empty(t, isolated.Graph.Relation) + empty, err := repo.SearchGraph(ctx, ns, "no match") + require.NoError(t, err) + require.Empty(t, empty.Graph.Node) + // Full query text remains a parameter, including a Cypher-looking payload. + empty, err = repo.SearchGraph(ctx, ns, "' RETURN 1 //") + require.NoError(t, err) + require.Empty(t, empty.Graph.Node) + + t.Run("seed cap and exact-name priority", func(t *testing.T) { + _, err := neo4j.ExecuteQuery(ctx, driver, ` + UNWIND range(0, 104) AS i CREATE (n:`+label+` + {name:'Cap '+toString(i), kg:'doc', chunks:['c1'], attributes:[]}) + WITH count(*) AS created + CREATE (exact:`+label+` {name:'Cap', kg:'doc', chunks:['c1'], attributes:[]})`, + nil, neo4j.EagerResultTransformer) + require.NoError(t, err) + result, err := repo.SearchGraph(ctx, ns, "Cap") + require.NoError(t, err) + require.Len(t, result.Graph.Node, types.GraphSearchMaxSeeds) + require.Equal(t, "Cap", result.Graph.Node[0].Name) + require.Contains(t, result.TruncationReasons, "candidate_seeds") + }) + t.Run("row cap without duplicate edge expansion", func(t *testing.T) { + _, err := neo4j.ExecuteQuery(ctx, driver, ` + CREATE (hub:`+label+` {name:'Hub', kg:'doc', chunks:['c1'], attributes:[]}) + WITH hub UNWIND range(0, 512) AS i + CREATE (leaf:`+label+` {name:'Leaf '+toString(i), kg:'doc', chunks:['c1'], attributes:[]}), + (hub)-[:CONNECTS]->(leaf)`, + nil, neo4j.EagerResultTransformer) + require.NoError(t, err) + result, err := repo.SearchGraph(ctx, ns, "Hub") + require.NoError(t, err) + require.Len(t, result.Graph.Relation, types.GraphSearchMaxRows) + require.Contains(t, result.TruncationReasons, "candidate_relations") + }) + t.Run("field projections are bounded before Bolt", func(t *testing.T) { + _, err := neo4j.ExecuteQuery(ctx, driver, ` + CREATE (n:`+label+` {name:'Large', kg:'doc', chunks:$chunks, attributes:$attributes})`, + map[string]any{ + "chunks": strings.Split(strings.Repeat("c,", 600), ","), + "attributes": []string{strings.Repeat("中", 3000)}, + }, neo4j.EagerResultTransformer) + require.NoError(t, err) + result, err := repo.SearchGraph(ctx, ns, "Large") + require.NoError(t, err) + require.Len(t, result.Graph.Node, 1) + require.Len(t, result.Graph.Node[0].Chunks, 513) + require.Len(t, []rune(result.Graph.Node[0].Attributes[0]), 1001) + }) +} diff --git a/internal/application/service/graph_search.go b/internal/application/service/graph_search.go new file mode 100644 index 00000000..fbcec51b --- /dev/null +++ b/internal/application/service/graph_search.go @@ -0,0 +1,242 @@ +package service + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "slices" + "unicode/utf8" + + "github.com/Tencent/WeKnora/internal/application/access" + apperrors "github.com/Tencent/WeKnora/internal/errors" + "github.com/Tencent/WeKnora/internal/logger" + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" +) + +type graphSearchService struct { + graph interfaces.GraphSearchRepository + evidence interfaces.GraphSearchEvidenceRepository +} + +// NewGraphSearchService constructs the public-query provenance boundary. +func NewGraphSearchService(graph interfaces.GraphSearchRepository, + evidence interfaces.GraphSearchEvidenceRepository, +) interfaces.GraphSearchService { + return &graphSearchService{graph: graph, evidence: evidence} +} + +func (s *graphSearchService) Search( + ctx context.Context, kb *types.KnowledgeBase, req types.GraphSearchRequest, +) (*types.GraphSearchResult, error) { + if kb == nil || !access.HasKBGrant(ctx, kb.ID, kb.TenantID, types.OrgRoleViewer) { + return nil, apperrors.NewForbiddenError("An explicit read grant for this knowledge base is required") + } + if scope, ok := types.TenantAPIKeyScopeFromContext(ctx); ok && !scope.FullAccess && + !scope.HasCapability(types.APIKeyCapabilityRetrieve) { + return nil, apperrors.NewForbiddenError("The API key requires retrieve capability") + } + if err := req.Normalize(); err != nil { + return nil, apperrors.NewBadRequestError(err.Error()) + } + if !kb.IsGraphEnabled() { + return nil, apperrors.NewConflictError("Knowledge graph is not enabled for this knowledge base") + } + ctx, cancel := context.WithTimeout(ctx, types.GraphSearchTimeout) + defer cancel() + candidates, err := s.graph.SearchGraph(ctx, types.NameSpace{KnowledgeBase: kb.ID}, req.Query) + if err != nil { + logger.ErrorWithFields(ctx, err, nil) + return nil, apperrors.NewServiceUnavailableError("Knowledge graph query is temporarily unavailable") + } + if candidates == nil || candidates.Graph == nil { + return nil, apperrors.NewServiceUnavailableError("Knowledge graph backend is not configured") + } + result := &types.GraphSearchResult{ + KnowledgeBaseID: kb.ID, Query: req.Query, + Entities: []types.GraphSearchEntity{}, Relationships: []types.GraphSearchRelation{}, + SourceChunks: []types.GraphSearchSourceChunk{}, + Meta: types.GraphSearchMeta{ + TruncationReasons: []string{}, MaxNodes: req.MaxNodes, + MaxRelations: req.MaxRelations, MaxSourceChunks: req.MaxSourceChunks, + }, + } + mark := func(reason string) { + result.Meta.Truncated = true + if !slices.Contains(result.Meta.TruncationReasons, reason) { + result.Meta.TruncationReasons = append(result.Meta.TruncationReasons, reason) + } + } + for _, reason := range candidates.TruncationReasons { + mark(reason) + } + ids := []string{} + wanted := map[string]bool{} + eligible := map[string][]string{} + for _, node := range candidates.Graph.Node { + if node == nil || node.ID == "" || node.Name == "" || node.KnowledgeID == "" || len(node.Chunks) == 0 { + continue + } + if utf8.RuneCountInString(node.Name) > types.GraphSearchMaxNameRunes || + len(node.KnowledgeID) > 128 || len(node.Chunks) > types.GraphSearchMaxEvidence { + mark("entity_fields") + continue + } + chunkIDs := []string{} + additional := []string{} + valid := true + for _, id := range node.Chunks { + if id == "" || len(id) > 128 { + valid = false + mark("entity_fields") + break + } + if !slices.Contains(chunkIDs, id) { + chunkIDs = append(chunkIDs, id) + if !wanted[id] { + additional = append(additional, id) + } + } + } + if !valid { + continue + } + if len(ids)+len(additional) > types.GraphSearchMaxEvidence { + mark("candidate_source_chunks") + continue + } + for _, id := range additional { + wanted[id] = true + ids = append(ids, id) + } + slices.Sort(chunkIDs) + eligible[node.ID] = chunkIDs + } + sources := map[string]types.GraphSearchSourceChunk{} + if len(ids) != 0 { + rows, err := s.evidence.GetGraphSourceChunks(ctx, kb.TenantID, kb.ID, ids) + if err != nil { + logger.ErrorWithFields(ctx, err, nil) + return nil, apperrors.NewInternalServerError("Failed to validate graph source chunks") + } + for _, row := range rows { + if wanted[row.ID] && row.TenantID == kb.TenantID && row.KnowledgeBaseID == kb.ID { + sources[row.ID] = row + } + } + } + // Conservative provenance: every cited chunk must still be enabled, live + // and in this exact document/KB. Attributes are document-level aggregates; + // validating just one surviving chunk could expose disabled-source facts. + nodes := map[string]types.GraphSearchEntity{} + publicIDs := map[string]bool{} + returnedSources := map[string]bool{} + for _, node := range candidates.Graph.Node { + if node == nil { + continue + } + chunkIDs, ok := eligible[node.ID] + if !ok { + continue + } + valid, extra := true, 0 + for _, id := range chunkIDs { + if row, ok := sources[id]; !ok || row.KnowledgeID != node.KnowledgeID { + valid = false + break + } + if !returnedSources[id] { + extra++ + } + } + if !valid { + continue + } + id := graphSearchPublicID("entity", kb.ID, node.KnowledgeID, node.Name) + if publicIDs[id] { + continue + } + if len(result.Entities) >= req.MaxNodes { + mark("max_nodes") + continue + } + if len(result.SourceChunks)+extra > req.MaxSourceChunks { + mark("max_source_chunks") + continue + } + attributes := []string{} + for i, attribute := range node.Attributes { + if i == types.GraphSearchMaxAttributes { + mark("entity_fields") + break + } + text := []rune(attribute) + if len(text) > types.GraphSearchMaxAttributeRunes { + attribute = string(text[:types.GraphSearchMaxAttributeRunes]) + mark("entity_fields") + } + attributes = append(attributes, attribute) + } + entity := types.GraphSearchEntity{ + ID: id, Name: node.Name, KnowledgeID: node.KnowledgeID, + Attributes: attributes, SourceChunkIDs: chunkIDs, + } + nodes[node.ID] = entity + publicIDs[id] = true + result.Entities = append(result.Entities, entity) + for _, id := range chunkIDs { + if !returnedSources[id] { + row := sources[id] + result.SourceChunks = append(result.SourceChunks, row) + returnedSources[id] = true + if row.ContentTruncated || row.TitleTruncated { + mark("source_fields") + } + } + } + } + seenRelations := map[string]bool{} + for _, relation := range candidates.Graph.Relation { + if relation == nil { + continue + } + source, sourceOK := nodes[relation.SourceID] + target, targetOK := nodes[relation.TargetID] + if !sourceOK || !targetOK || source.KnowledgeID != target.KnowledgeID || relation.Type == "" { + continue + } + if utf8.RuneCountInString(relation.Type) > 128 { + mark("relation_fields") + continue + } + id := graphSearchPublicID("relation", source.ID, target.ID, relation.Type) + if seenRelations[id] { + continue + } + seenRelations[id] = true + if len(result.Relationships) >= req.MaxRelations { + mark("max_relations") + continue + } + chunkIDs := append([]string{}, source.SourceChunkIDs...) + for _, id := range target.SourceChunkIDs { + if !slices.Contains(chunkIDs, id) { + chunkIDs = append(chunkIDs, id) + } + } + slices.Sort(chunkIDs) + result.Relationships = append(result.Relationships, types.GraphSearchRelation{ + ID: id, SourceID: source.ID, TargetID: target.ID, Type: relation.Type, SourceChunkIDs: chunkIDs, + }) + } + return result, nil +} + +// JSON tuple encoding avoids delimiter collisions; IDs survive graph reindexing +// and never expose Neo4j element IDs or conflate same-named document instances. +func graphSearchPublicID(parts ...string) string { + data, _ := json.Marshal(parts) + sum := sha256.Sum256(data) + return hex.EncodeToString(sum[:]) +} diff --git a/internal/application/service/graph_search_test.go b/internal/application/service/graph_search_test.go new file mode 100644 index 00000000..d4e5c85a --- /dev/null +++ b/internal/application/service/graph_search_test.go @@ -0,0 +1,298 @@ +package service + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "strings" + "testing" + "unicode/utf8" + + "github.com/Tencent/WeKnora/internal/application/access" + apperrors "github.com/Tencent/WeKnora/internal/errors" + "github.com/Tencent/WeKnora/internal/types" + "github.com/stretchr/testify/require" +) + +type graphSearchStoreStub struct { + candidates *types.GraphSearchCandidates + err error + calls int + namespace types.NameSpace + query string +} + +func (s *graphSearchStoreStub) SearchGraph( + _ context.Context, ns types.NameSpace, query string, +) (*types.GraphSearchCandidates, error) { + s.calls++ + s.namespace, s.query = ns, query + return s.candidates, s.err +} + +type graphSearchEvidenceStub struct { + rows []types.GraphSearchSourceChunk + err error + calls int + tenantID uint64 + kbID string + ids []string +} + +func (s *graphSearchEvidenceStub) GetGraphSourceChunks( + _ context.Context, tenantID uint64, kbID string, ids []string, +) ([]types.GraphSearchSourceChunk, error) { + s.calls++ + s.tenantID, s.kbID, s.ids = tenantID, kbID, append([]string{}, ids...) + return s.rows, s.err +} + +func graphSearchTestKB() *types.KnowledgeBase { + return &types.KnowledgeBase{ + ID: "kb", TenantID: 7, + IndexingStrategy: types.IndexingStrategy{GraphEnabled: true}, + ExtractConfig: &types.ExtractConfig{Enabled: true}, + } +} + +func graphSearchTestContext(kb *types.KnowledgeBase) context.Context { + grant := &access.KBAccess{ + KnowledgeBase: kb, EffectiveTenantID: kb.TenantID, + Caller: types.Caller{TenantID: 1, UserID: "reader", Role: types.TenantRoleViewer}, + Permission: types.OrgRoleViewer, + } + return grant.WithGrant(context.Background()) +} + +func graphSearchTestSource(id, doc string) types.GraphSearchSourceChunk { + return types.GraphSearchSourceChunk{ + ID: id, KnowledgeID: doc, + TenantID: 7, KnowledgeBaseID: "kb", Title: doc, Content: "source " + id, + } +} + +func TestGraphSearchPublicIdentitiesDirectionAndProvenance(t *testing.T) { + kb := graphSearchTestKB() + graph := &types.GraphData{ + Node: []*types.GraphNode{ + { + ID: "physical-a1", Name: "Acme", KnowledgeID: "doc1", + Chunks: []string{"c1"}, Attributes: []string{"attr1"}, + }, + {ID: "physical-b1", Name: "Shanghai", KnowledgeID: "doc1", Chunks: []string{"c1"}}, + { + ID: "physical-a2", Name: "Acme", KnowledgeID: "doc2", + Chunks: []string{"c2"}, Attributes: []string{"attr2"}, + }, + {ID: "physical-b2", Name: "Shanghai", KnowledgeID: "doc2", Chunks: []string{"c2"}}, + {ID: "physical-dead", Name: "Acme", KnowledgeID: "deleted", Chunks: []string{"missing"}}, + }, + Relation: []*types.GraphRelation{ + {ID: "r1", SourceID: "physical-a1", TargetID: "physical-b1", Type: "HEADQUARTERED_IN"}, + {ID: "r1-duplicate", SourceID: "physical-a1", TargetID: "physical-b1", Type: "HEADQUARTERED_IN"}, + {ID: "r2", SourceID: "physical-b1", TargetID: "physical-a1", Type: "RELATED_TO"}, + {ID: "r3", SourceID: "physical-a2", TargetID: "physical-b2", Type: "HAS_BRANCH_IN"}, + {ID: "self", SourceID: "physical-a1", TargetID: "physical-a1", Type: "SELF"}, + {ID: "dead", SourceID: "physical-dead", TargetID: "physical-b1", Type: "SECRET"}, + {ID: "cross-document", SourceID: "physical-a1", TargetID: "physical-b2", Type: "INVALID"}, + {Node1: "Acme", Node2: "Shanghai", Type: "NAMES_ARE_NOT_IDENTITIES"}, + }, + } + store := &graphSearchStoreStub{candidates: &types.GraphSearchCandidates{Graph: graph}} + evidence := &graphSearchEvidenceStub{rows: []types.GraphSearchSourceChunk{ + graphSearchTestSource("c1", "doc1"), graphSearchTestSource("c2", "doc2"), + }} + svc := NewGraphSearchService(store, evidence) + result, err := svc.Search(graphSearchTestContext(kb), kb, types.GraphSearchRequest{Query: " Acme "}) + require.NoError(t, err) + require.Len(t, result.Entities, 4) + require.Len(t, result.Relationships, 4) + require.Len(t, result.SourceChunks, 2) + require.False(t, result.Meta.Truncated) + require.NotEqual(t, result.Entities[0].ID, result.Entities[2].ID, "same names in different documents stay distinct") + require.Equal(t, "Acme", store.query) + require.Equal(t, types.NameSpace{KnowledgeBase: "kb"}, store.namespace) + require.Equal(t, uint64(7), evidence.tenantID, "use shared KB owner, never caller/execution tenant") + require.Equal(t, "kb", evidence.kbID) + require.Equal(t, result.Entities[0].ID, result.Relationships[0].SourceID) + require.Equal(t, result.Entities[1].ID, result.Relationships[0].TargetID) + require.Equal(t, result.Entities[1].ID, result.Relationships[1].SourceID) + data, err := json.Marshal(result) + require.NoError(t, err) + for _, secret := range []string{"physical-", "SECRET", "INVALID", "NAMES_ARE_NOT_IDENTITIES", "tenant_id"} { + require.NotContains(t, string(data), secret) + } + // Reindexing changes backend IDs but not the public document-instance ID. + graph.Node[0].ID = "new-backend-id" + result2, err := svc.Search(graphSearchTestContext(kb), kb, types.GraphSearchRequest{Query: "Acme"}) + require.NoError(t, err) + require.Equal(t, result.Entities[0].ID, result2.Entities[0].ID) + require.NotEqual(t, graphSearchPublicID("a:b", "c"), graphSearchPublicID("a", "b:c")) +} + +func TestGraphSearchRequiresEverySourceInExactDocument(t *testing.T) { + kb := graphSearchTestKB() + for name, rows := range map[string][]types.GraphSearchSourceChunk{ + "missing or disabled second source": {graphSearchTestSource("c1", "doc")}, + "wrong document": { + graphSearchTestSource("c1", "doc"), graphSearchTestSource("c2", "another"), + }, + "wrong tenant": { + graphSearchTestSource("c1", "doc"), + {ID: "c2", KnowledgeID: "doc", TenantID: 8, KnowledgeBaseID: "kb"}, + }, + "wrong KB": { + graphSearchTestSource("c1", "doc"), + {ID: "c2", KnowledgeID: "doc", TenantID: 7, KnowledgeBaseID: "other"}, + }, + } { + t.Run(name, func(t *testing.T) { + store := &graphSearchStoreStub{candidates: &types.GraphSearchCandidates{Graph: &types.GraphData{ + Node: []*types.GraphNode{ + { + ID: "n", Name: "Secret", KnowledgeID: "doc", Chunks: []string{"c1", "c2"}, + Attributes: []string{"do not expose"}, + }, + }, + Relation: []*types.GraphRelation{{SourceID: "n", TargetID: "n", Type: "SECRET"}}, + }}} + result, err := NewGraphSearchService(store, &graphSearchEvidenceStub{rows: rows}). + Search(graphSearchTestContext(kb), kb, types.GraphSearchRequest{Query: "Secret"}) + require.NoError(t, err) + require.Empty(t, result.Entities) + require.Empty(t, result.Relationships) + require.Empty(t, result.SourceChunks) + }) + } +} + +func TestGraphSearchAdmissionAndFailures(t *testing.T) { + kb := graphSearchTestKB() + for name, ctx := range map[string]context.Context{ + "no grant": context.Background(), + "wrong resource": graphSearchTestContext(&types.KnowledgeBase{ID: "other", TenantID: 7}), + "wrong owner": graphSearchTestContext(&types.KnowledgeBase{ID: "kb", TenantID: 8}), + "narrowed key": types.WithTenantAPIKeyScope(graphSearchTestContext(kb), + types.TenantAPIKeyScope{KnowledgeBaseIDs: types.StringArray{"other"}}), + "chat-only direct caller": types.WithTenantAPIKeyScope(graphSearchTestContext(kb), + types.TenantAPIKeyScope{Capabilities: types.StringArray{"chat"}}), + "ingest-only direct caller": types.WithTenantAPIKeyScope(graphSearchTestContext(kb), + types.TenantAPIKeyScope{Capabilities: types.StringArray{"ingest"}}), + } { + t.Run(name, func(t *testing.T) { + store, evidence := &graphSearchStoreStub{}, &graphSearchEvidenceStub{} + result, err := NewGraphSearchService(store, evidence).Search(ctx, kb, + types.GraphSearchRequest{Query: "Acme"}) + require.Nil(t, result) + var appErr *apperrors.AppError + require.ErrorAs(t, err, &appErr) + require.Equal(t, apperrors.ErrForbidden, appErr.Code) + require.Zero(t, store.calls+evidence.calls) + }) + } + for _, legacyConfigOnly := range []bool{false, true} { + disabled := *kb + disabled.IndexingStrategy.GraphEnabled = legacyConfigOnly + if legacyConfigOnly { + disabled.ExtractConfig = &types.ExtractConfig{Enabled: false} + } + store := &graphSearchStoreStub{} + _, err := NewGraphSearchService(store, &graphSearchEvidenceStub{}). + Search(graphSearchTestContext(&disabled), &disabled, types.GraphSearchRequest{Query: "Acme"}) + var appErr *apperrors.AppError + require.ErrorAs(t, err, &appErr) + require.Equal(t, apperrors.ErrConflict, appErr.Code) + require.Zero(t, store.calls) + } + for _, storeErr := range []error{nil, errors.New("backend password must not be returned")} { + store := &graphSearchStoreStub{err: storeErr} + _, err := NewGraphSearchService(store, &graphSearchEvidenceStub{}). + Search(graphSearchTestContext(kb), kb, types.GraphSearchRequest{Query: "Acme"}) + var appErr *apperrors.AppError + require.ErrorAs(t, err, &appErr) + require.Equal(t, apperrors.ErrServiceUnavailable, appErr.Code) + require.NotContains(t, err.Error(), "password") + } + store := &graphSearchStoreStub{candidates: &types.GraphSearchCandidates{Graph: &types.GraphData{ + Node: []*types.GraphNode{{ID: "n", Name: "Acme", KnowledgeID: "doc", Chunks: []string{"c1"}}}, + }}} + result, err := NewGraphSearchService(store, &graphSearchEvidenceStub{err: errors.New("SQL error")}). + Search(graphSearchTestContext(kb), kb, types.GraphSearchRequest{Query: "Acme"}) + require.Nil(t, result, "validation failure must not return partial graph data") + var appErr *apperrors.AppError + require.ErrorAs(t, err, &appErr) + require.Equal(t, apperrors.ErrInternalServer, appErr.Code) +} + +func TestGraphSearchBudgetsAndClipping(t *testing.T) { + kb := graphSearchTestKB() + graph := &types.GraphData{} + evidence := &graphSearchEvidenceStub{} + for i := range 513 { + chunkID, nodeID := fmt.Sprintf("c%d", i), fmt.Sprintf("n%d", i) + graph.Node = append(graph.Node, &types.GraphNode{ + ID: nodeID, Name: nodeID, + KnowledgeID: "doc", Chunks: []string{chunkID, chunkID}, + Attributes: []string{strings.Repeat("中", 1001)}, + }) + evidence.rows = append(evidence.rows, graphSearchTestSource(chunkID, "doc")) + } + for i := range 3 { + graph.Relation = append(graph.Relation, &types.GraphRelation{ + SourceID: "n0", TargetID: "n1", Type: fmt.Sprintf("REL%d", i), + }) + } + store := &graphSearchStoreStub{candidates: &types.GraphSearchCandidates{ + Graph: graph, TruncationReasons: []string{"candidate_seeds", "candidate_relations"}, + }} + result, err := NewGraphSearchService(store, evidence).Search(graphSearchTestContext(kb), kb, + types.GraphSearchRequest{Query: "n", MaxNodes: 2, MaxSourceChunks: 2, MaxRelations: 1}) + require.NoError(t, err) + require.Len(t, evidence.ids, types.GraphSearchMaxEvidence) + require.Len(t, result.Entities, 2) + require.Len(t, result.SourceChunks, 2) + require.Len(t, result.Relationships, 1) + require.True(t, result.Meta.Truncated) + for _, reason := range []string{ + "candidate_seeds", "candidate_relations", "candidate_source_chunks", + "max_nodes", "max_relations", "entity_fields", + } { + require.Contains(t, result.Meta.TruncationReasons, reason) + } + require.Equal(t, 1000, utf8.RuneCountInString(result.Entities[0].Attributes[0])) + // The chunk limit must never create dangling node/relationship references. + result, err = NewGraphSearchService(store, evidence).Search(graphSearchTestContext(kb), kb, + types.GraphSearchRequest{Query: "n", MaxSourceChunks: 1}) + require.NoError(t, err) + require.Len(t, result.Entities, 1) + require.Len(t, result.SourceChunks, 1) + require.Empty(t, result.Relationships) + require.Contains(t, result.Meta.TruncationReasons, "max_source_chunks") +} + +func TestGraphSearchEmptyAndIsolatedEntity(t *testing.T) { + kb := graphSearchTestKB() + store := &graphSearchStoreStub{candidates: &types.GraphSearchCandidates{Graph: &types.GraphData{}}} + evidence := &graphSearchEvidenceStub{} + svc := NewGraphSearchService(store, evidence) + result, err := svc.Search(graphSearchTestContext(kb), kb, types.GraphSearchRequest{Query: "none"}) + require.NoError(t, err) + require.Zero(t, evidence.calls) + data, err := json.Marshal(result) + require.NoError(t, err) + for _, field := range []string{`"entities":[]`, `"relationships":[]`, `"source_chunks":[]`} { + require.Contains(t, string(data), field) + } + store.candidates.Graph.Node = []*types.GraphNode{ + {ID: "isolated", Name: "Isolated", KnowledgeID: "doc", Chunks: []string{"c1"}}, + } + source := graphSearchTestSource("c1", "doc") + source.ContentTruncated = true + evidence.rows = []types.GraphSearchSourceChunk{source} + result, err = svc.Search(graphSearchTestContext(kb), kb, types.GraphSearchRequest{Query: "Isolated"}) + require.NoError(t, err) + require.Len(t, result.Entities, 1) + require.Empty(t, result.Relationships) + require.Contains(t, result.Meta.TruncationReasons, "source_fields") +} diff --git a/internal/container/container.go b/internal/container/container.go index edb2a304..99b49b7b 100644 --- a/internal/container/container.go +++ b/internal/container/container.go @@ -178,6 +178,8 @@ func BuildContainer(container *dig.Container) *dig.Container { must(container.Provide(repository.NewSystemSettingRepository)) must(container.Provide(repository.NewModelCatalogRepository)) must(container.Provide(neo4jRepo.NewNeo4jRepository)) + must(container.Provide(neo4jRepo.NewGraphSearchRepository)) + must(container.Provide(repository.NewGraphSearchEvidenceRepository)) must(container.Provide(repository.NewMCPServiceRepository)) must(container.Provide(repository.NewMCPToolApprovalRepository)) must(container.Provide(repository.NewAgentPromptRepository)) @@ -240,6 +242,7 @@ func BuildContainer(container *dig.Container) *dig.Container { must(container.Provide(service.NewAuditLogService)) must(container.Provide(service.NewAuditLogRetentionRunner)) must(container.Provide(service.NewKnowledgeBaseService)) + must(container.Provide(service.NewGraphSearchService)) must(container.Provide(service.NewOrganizationService)) must(container.Provide(service.NewKBShareService)) // KBShareService must be registered before KnowledgeService and KnowledgeTagService must(container.Provide(service.NewAgentShareService)) @@ -561,6 +564,7 @@ func BuildContainer(container *dig.Container) *dig.Container { must(container.Provide(handler.NewTenantInvitationHandler)) must(container.Provide(handler.NewAuditLogHandler)) must(container.Provide(handler.NewKnowledgeBaseHandler)) + must(container.Provide(handler.NewGraphSearchHandler)) must(container.Provide(handler.NewKnowledgeHandler)) must(container.Provide(handler.NewChunkHandler)) must(container.Provide(handler.NewFAQHandler)) diff --git a/internal/handler/graph_search.go b/internal/handler/graph_search.go new file mode 100644 index 00000000..7aee3726 --- /dev/null +++ b/internal/handler/graph_search.go @@ -0,0 +1,75 @@ +package handler + +import ( + "encoding/json" + "io" + "net/http" + + apperrors "github.com/Tencent/WeKnora/internal/errors" + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" + "github.com/gin-gonic/gin" +) + +// GraphSearchHandler exposes a read-only JSON view of one authorized KB graph. +type GraphSearchHandler struct { + kbHandler *KnowledgeBaseHandler + service interfaces.GraphSearchService +} + +// NewGraphSearchHandler reuses the standard KB access resolver. +func NewGraphSearchHandler(kbHandler *KnowledgeBaseHandler, service interfaces.GraphSearchService) *GraphSearchHandler { + return &GraphSearchHandler{kbHandler: kbHandler, service: service} +} + +// Search godoc +// @Summary 查询知识图谱 +// @Description 对单个授权知识库按实体名进行区分大小写的子串查询,返回实体、定向关系及仍然有效的来源分块。不调用模型,不影响默认检索。0 表示使用默认上限。 +// @Tags 知识库 +// @Accept json +// @Produce json +// @Param id path string true "知识库ID" +// @Param agent_id query string false "共享智能体 ID" +// @Param agent_source_tenant_id query integer false "共享智能体来源空间" +// @Param request body types.GraphSearchRequest true "查询及结果上限" +// @Success 200 {object} handler.DataResponse{data=types.GraphSearchResult} +// @Failure 400 {object} apperrors.AppError "参数错误" +// @Failure 401 {object} apperrors.AppError "未登录" +// @Failure 403 {object} apperrors.AppError "无权访问知识库" +// @Failure 404 {object} apperrors.AppError "知识库不存在" +// @Failure 409 {object} apperrors.AppError "知识图谱未启用" +// @Failure 500 {object} apperrors.AppError "来源校验失败" +// @Failure 503 {object} apperrors.AppError "图谱服务不可用" +// @Security Bearer +// @Security ApiKeyAuth +// @Router /knowledge-bases/{id}/graph-search [post] +func (h *GraphSearchHandler) Search(c *gin.Context) { + kb, _, _, _, err := h.kbHandler.validateAndGetKnowledgeBase(c) + if err != nil { + _ = c.Error(err) + return + } + c.Request.Body = http.MaxBytesReader(c.Writer, c.Request.Body, 8<<10) + decoder := json.NewDecoder(c.Request.Body) + decoder.DisallowUnknownFields() + var req types.GraphSearchRequest + if err := decoder.Decode(&req); err != nil { + _ = c.Error(apperrors.NewBadRequestError("Invalid graph query request")) + return + } + // Reject trailing JSON rather than silently executing only the first query. + if err := decoder.Decode(new(any)); err != io.EOF { + _ = c.Error(apperrors.NewBadRequestError("Expected one graph query object")) + return + } + if err := req.Normalize(); err != nil { + _ = c.Error(apperrors.NewBadRequestError(err.Error())) + return + } + result, err := h.service.Search(c.Request.Context(), kb, req) + if err != nil { + _ = c.Error(err) + return + } + c.JSON(http.StatusOK, gin.H{"success": true, "data": result}) +} diff --git a/internal/handler/graph_search_test.go b/internal/handler/graph_search_test.go new file mode 100644 index 00000000..e6c38d2d --- /dev/null +++ b/internal/handler/graph_search_test.go @@ -0,0 +1,198 @@ +package handler + +import ( + "context" + "net/http" + "net/http/httptest" + "strings" + "testing" + + "github.com/Tencent/WeKnora/internal/application/access" + "github.com/Tencent/WeKnora/internal/application/repository" + apperrors "github.com/Tencent/WeKnora/internal/errors" + "github.com/Tencent/WeKnora/internal/middleware" + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" + "github.com/gin-gonic/gin" + "github.com/stretchr/testify/require" +) + +type graphSearchHandlerServiceStub struct { + calls int + req types.GraphSearchRequest + kb *types.KnowledgeBase + grant bool + err error +} + +func (s *graphSearchHandlerServiceStub) Search( + ctx context.Context, kb *types.KnowledgeBase, req types.GraphSearchRequest, +) (*types.GraphSearchResult, error) { + s.calls++ + s.req, s.kb = req, kb + s.grant = access.HasKBGrant(ctx, kb.ID, kb.TenantID, types.OrgRoleViewer) + return &types.GraphSearchResult{ + KnowledgeBaseID: kb.ID, Query: req.Query, + Entities: []types.GraphSearchEntity{}, Relationships: []types.GraphSearchRelation{}, + SourceChunks: []types.GraphSearchSourceChunk{}, + }, s.err +} + +func graphSearchHandlerRouter( + kbService interfaces.KnowledgeBaseService, shares interfaces.KBShareService, + svc interfaces.GraphSearchService, caller uint64, scope *types.TenantAPIKeyScope, + agents ...interfaces.AgentShareService, +) *gin.Engine { + gin.SetMode(gin.TestMode) + r := gin.New() + r.Use(middleware.ErrorHandler(), func(c *gin.Context) { + c.Set(types.TenantIDContextKey.String(), caller) + c.Set(types.UserIDContextKey.String(), "reader") + if scope != nil { + c.Request = c.Request.WithContext(types.WithTenantAPIKeyScope(c.Request.Context(), *scope)) + } + c.Next() + }) + kbHandler := &KnowledgeBaseHandler{service: kbService, kbShareService: shares} + if len(agents) > 0 { + kbHandler.agentShareService = agents[0] + } + h := NewGraphSearchHandler(kbHandler, svc) + r.POST("/knowledge-bases/:id/graph-search", h.Search) + return r +} + +func graphSearchHandlerKB(owner uint64) *stubKBOnlyService { + return &stubKBOnlyService{getByID: func(_ context.Context, id string) (*types.KnowledgeBase, error) { + return &types.KnowledgeBase{ID: id, TenantID: owner}, nil + }} +} + +func TestGraphSearchHandlerValidation(t *testing.T) { + for name, body := range map[string]string{ + "empty": "", + "missing query": `{}`, + "null root": `null`, + "query whitespace": `{"query":" "}`, + "wrong query type": `{"query":1}`, + "unknown field": `{"query":"Acme","tenant_id":7}`, + "trailing object": `{"query":"Acme"} {}`, + "fractional limit": `{"query":"Acme","max_nodes":1.5}`, + "negative limit": `{"query":"Acme","max_source_chunks":-1}`, + "excessive limit": `{"query":"Acme","max_relations":201}`, + "long query": `{"query":"` + strings.Repeat("中", 513) + `"}`, + "large body": `{"query":"Acme"}` + strings.Repeat(" ", 8192), + } { + t.Run(name, func(t *testing.T) { + svc := &graphSearchHandlerServiceStub{} + w := httptest.NewRecorder() + graphSearchHandlerRouter(graphSearchHandlerKB(1), nil, svc, 1, nil). + ServeHTTP(w, httptest.NewRequest(http.MethodPost, + "/knowledge-bases/kb/graph-search", strings.NewReader(body))) + require.Equal(t, http.StatusBadRequest, w.Code, w.Body.String()) + require.Zero(t, svc.calls) + require.Contains(t, w.Body.String(), `"code":1000`) + }) + } +} + +func TestGraphSearchHandlerSharedAccessAndErrors(t *testing.T) { + shares := &handlerKBShareStub{} + svc := &graphSearchHandlerServiceStub{} + r := graphSearchHandlerRouter(graphSearchHandlerKB(7), shares, svc, 1, nil) + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/knowledge-bases/kb/graph-search", + strings.NewReader(`{"query":" Acme "}`))) + require.Equal(t, http.StatusOK, w.Code, w.Body.String()) + require.True(t, svc.grant, "the service receives the exact KB read grant") + require.Equal(t, uint64(7), svc.kb.TenantID) + require.Equal(t, uint64(1), shares.caller) + require.Equal(t, "Acme", svc.req.Query) + require.Equal(t, 50, svc.req.MaxNodes) + + svc.err = apperrors.NewServiceUnavailableError("graph unavailable") + w = httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/knowledge-bases/kb/graph-search", + strings.NewReader(`{"query":"Acme"}`))) + require.Equal(t, http.StatusServiceUnavailable, w.Code) + require.NotContains(t, w.Body.String(), `"entities"`, "errors never expose partial results") +} + +func TestGraphSearchHandlerDeniesBeforeQuery(t *testing.T) { + for _, tt := range []struct { + name string + caller uint64 + scope *types.TenantAPIKeyScope + kbService interfaces.KnowledgeBaseService + status int + }{ + {name: "unauthenticated", caller: 0, kbService: graphSearchHandlerKB(1), status: 401}, + {name: "unshared KB", caller: 1, kbService: graphSearchHandlerKB(7), status: 403}, + { + name: "key outside allow list", caller: 1, kbService: graphSearchHandlerKB(1), status: 403, + scope: &types.TenantAPIKeyScope{KnowledgeBaseIDs: types.StringArray{"other"}}, + }, + { + name: "missing KB", caller: 1, status: 404, + kbService: &stubKBOnlyService{getByID: func(context.Context, string) (*types.KnowledgeBase, error) { + return nil, repository.ErrKnowledgeBaseNotFound + }}, + }, + } { + t.Run(tt.name, func(t *testing.T) { + svc := &graphSearchHandlerServiceStub{} + r := graphSearchHandlerRouter(tt.kbService, nil, svc, tt.caller, tt.scope) + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest(http.MethodPost, "/knowledge-bases/kb/graph-search", + strings.NewReader(`{"query":"Acme"}`))) + require.Equal(t, tt.status, w.Code, w.Body.String()) + require.Zero(t, svc.calls) + }) + } +} + +type graphSearchAgentStub struct { + interfaces.AgentShareService + config types.CustomAgentConfig + owner uint64 +} + +func (s *graphSearchAgentStub) GetSharedAgentForTenant( + context.Context, uint64, types.TenantRole, string, ...uint64, +) (*types.CustomAgent, error) { + return &types.CustomAgent{ID: "shared", TenantID: s.owner, Config: s.config}, nil +} + +func TestGraphSearchHandlerSharedAgentScope(t *testing.T) { + for _, tt := range []struct { + name, mode string + kbs []string + owner uint64 + status int + }{ + {"selected KB", "selected", []string{"kb"}, 7, 200}, + {"none is not all", "none", nil, 7, 403}, + {"empty selected is not all", "selected", nil, 7, 403}, + {"another selection", "selected", []string{"other"}, 7, 403}, + {"all in another owner", "all", nil, 8, 403}, + } { + t.Run(tt.name, func(t *testing.T) { + svc := &graphSearchHandlerServiceStub{} + agent := &graphSearchAgentStub{ + owner: tt.owner, + config: types.CustomAgentConfig{KBSelectionMode: tt.mode, KnowledgeBases: tt.kbs}, + } + r := graphSearchHandlerRouter(graphSearchHandlerKB(7), nil, svc, 1, nil, agent) + w := httptest.NewRecorder() + r.ServeHTTP(w, httptest.NewRequest(http.MethodPost, + "/knowledge-bases/kb/graph-search?agent_id=shared", strings.NewReader(`{"query":"Acme"}`))) + require.Equal(t, tt.status, w.Code, w.Body.String()) + if tt.status == http.StatusOK { + require.Equal(t, 1, svc.calls) + require.True(t, svc.grant) + } else { + require.Zero(t, svc.calls) + } + }) + } +} diff --git a/internal/router/router.go b/internal/router/router.go index d2545215..29f37d3b 100644 --- a/internal/router/router.go +++ b/internal/router/router.go @@ -44,6 +44,7 @@ type RouterParams struct { KBShareService interfaces.KBShareService AgentShareService interfaces.AgentShareService KBHandler *handler.KnowledgeBaseHandler + GraphSearchHandler *handler.GraphSearchHandler KnowledgeHandler *handler.KnowledgeHandler TenantHandler *handler.TenantHandler TenantService interfaces.TenantService @@ -296,6 +297,7 @@ func NewRouter(params RouterParams) *gin.Engine { ) RegisterKnowledgeTagRoutes(v1, params.TagHandler, rbacGuards) RegisterKnowledgeRoutes(v1, params.KnowledgeHandler, rbacGuards) + RegisterGraphSearchRoutes(v1, params.GraphSearchHandler, rbacGuards) RegisterFAQRoutes(v1, params.FAQHandler, rbacGuards) RegisterChunkRoutes(v1, params.ChunkHandler, rbacGuards) RegisterSessionRoutes(v1, params.SessionHandler, params.MessageSuggestionHandler, rbacGuards) diff --git a/internal/router/routes_graph.go b/internal/router/routes_graph.go new file mode 100644 index 00000000..f81729e7 --- /dev/null +++ b/internal/router/routes_graph.go @@ -0,0 +1,18 @@ +package router + +import ( + "net/http" + + "github.com/Tencent/WeKnora/internal/handler" + "github.com/gin-gonic/gin" +) + +// RegisterGraphSearchRoutes is a read-only KB content route, even though the +// query is POSTed. Role, API-key capability and exact KB grant are independent. +func RegisterGraphSearchRoutes(r *gin.RouterGroup, h *handler.GraphSearchHandler, g *rbacGuards) { + if h == nil { + return + } + g.apiKeyRoute(r, http.MethodPost, "/knowledge-bases/:id/graph-search", + apiKeyRetrieve(apiKeyFullAccess()), g.Viewer(), g.KBAccessRead("id"), h.Search) +} diff --git a/internal/router/routes_graph_test.go b/internal/router/routes_graph_test.go new file mode 100644 index 00000000..e876ebb8 --- /dev/null +++ b/internal/router/routes_graph_test.go @@ -0,0 +1,27 @@ +package router + +import ( + "net/http" + "testing" + + "github.com/Tencent/WeKnora/internal/handler" + "github.com/Tencent/WeKnora/internal/types" + "github.com/gin-gonic/gin" + "github.com/stretchr/testify/require" +) + +func TestGraphSearchRouteCapability(t *testing.T) { + gin.SetMode(gin.TestMode) + g := &rbacGuards{} + r := gin.New() + RegisterGraphSearchRoutes(r.Group("/api/v1"), &handler.GraphSearchHandler{}, g) + g.assertAPIKeyPoliciesMatchRoutes(r) + policy := mustLookupAPIKeyPolicy(t, g, http.MethodPost, "/api/v1/knowledge-bases/:id/graph-search") + require.True(t, policy.RequireFullAccess) + require.True(t, policyHasCapability(policy, types.APIKeyCapabilityRetrieve)) + require.False(t, policyHasCapability(policy, types.APIKeyCapabilityChat)) + require.False(t, policyHasCapability(policy, types.APIKeyCapabilityIngest)) + require.False(t, policyHasCapability(policy, types.APIKeyCapabilityManageKnowledgeBases)) + require.Len(t, r.Routes(), 1) + require.Equal(t, http.MethodPost, r.Routes()[0].Method) +} diff --git a/internal/types/graph_search.go b/internal/types/graph_search.go new file mode 100644 index 00000000..e930e39d --- /dev/null +++ b/internal/types/graph_search.go @@ -0,0 +1,114 @@ +package types + +import ( + "fmt" + "strings" + "time" + "unicode/utf8" +) + +// Internal candidate budgets are independent of the caller's response limits. +const ( + GraphSearchMaxSeeds = 100 + GraphSearchMaxRows = 512 + GraphSearchMaxEvidence = 512 + GraphSearchMaxNameRunes = 512 + GraphSearchMaxAttributeRunes = 1000 + GraphSearchMaxAttributes = 20 + GraphSearchMaxContentRunes = 2000 + GraphSearchTimeout = 10 * time.Second +) + +// GraphSearchRequest matches a case-sensitive entity-name substring. It does +// not run a model, generate embeddings or change the regular retrieval pipeline. +type GraphSearchRequest struct { + Query string `json:"query" binding:"required" minLength:"1" maxLength:"512"` + MaxNodes int `json:"max_nodes" minimum:"0" maximum:"100" default:"50"` + MaxRelations int `json:"max_relations" minimum:"0" maximum:"200" default:"100"` + MaxSourceChunks int `json:"max_source_chunks" minimum:"0" maximum:"50" default:"20"` +} + +// Normalize validates both HTTP and direct service callers. Zero means default. +func (r *GraphSearchRequest) Normalize() error { + r.Query = strings.TrimSpace(r.Query) + if r.Query == "" || !utf8.ValidString(r.Query) || utf8.RuneCountInString(r.Query) > GraphSearchMaxNameRunes { + return fmt.Errorf("query must contain 1 to %d characters", GraphSearchMaxNameRunes) + } + for _, limit := range []struct { + name string + value *int + defaultValue, maximum int + }{ + {"max_nodes", &r.MaxNodes, 50, 100}, + {"max_relations", &r.MaxRelations, 100, 200}, + {"max_source_chunks", &r.MaxSourceChunks, 20, 50}, + } { + if *limit.value < 0 || *limit.value > limit.maximum { + return fmt.Errorf("%s must be between 1 and %d, or 0 for the default", limit.name, limit.maximum) + } + if *limit.value == 0 { + *limit.value = limit.defaultValue + } + } + return nil +} + +// GraphSearchCandidates is internal: physical graph identities never cross the +// public API boundary. Truncation reports candidate caps, not an invented total. +type GraphSearchCandidates struct { + Graph *GraphData + TruncationReasons []string +} + +// GraphSearchEntity identifies an entity instance within a live document. +type GraphSearchEntity struct { + ID string `json:"id"` + Name string `json:"name"` + KnowledgeID string `json:"knowledge_id"` + Attributes []string `json:"attributes"` + SourceChunkIDs []string `json:"source_chunk_ids"` +} + +// GraphSearchRelation connects two returned, same-document entities. +type GraphSearchRelation struct { + ID string `json:"id"` + SourceID string `json:"source_id"` + TargetID string `json:"target_id"` + Type string `json:"type"` + SourceChunkIDs []string `json:"source_chunk_ids"` +} + +// GraphSearchSourceChunk is a bounded, live SQL projection, not a raw Chunk or +// Knowledge row. It excludes file paths, metadata, image URLs and owner details. +type GraphSearchSourceChunk struct { + ID string `json:"id"` + KnowledgeID string `json:"knowledge_id"` + Title string `json:"title"` + Content string `json:"content"` + ChunkIndex int `json:"chunk_index"` + StartAt int `json:"start_at"` + EndAt int `json:"end_at"` + ContentTruncated bool `json:"content_truncated" gorm:"-"` + TitleTruncated bool `json:"title_truncated" gorm:"-"` + TenantID uint64 `json:"-"` + KnowledgeBaseID string `json:"-"` +} + +// GraphSearchMeta reports effective limits and observed clipping, not totals. +type GraphSearchMeta struct { + Truncated bool `json:"truncated"` + TruncationReasons []string `json:"truncation_reasons"` + MaxNodes int `json:"max_nodes"` + MaxRelations int `json:"max_relations"` + MaxSourceChunks int `json:"max_source_chunks"` +} + +// GraphSearchResult is the stable public JSON contract, separate from GraphData. +type GraphSearchResult struct { + KnowledgeBaseID string `json:"knowledge_base_id"` + Query string `json:"query"` + Entities []GraphSearchEntity `json:"entities"` + Relationships []GraphSearchRelation `json:"relationships"` + SourceChunks []GraphSearchSourceChunk `json:"source_chunks"` + Meta GraphSearchMeta `json:"meta"` +} diff --git a/internal/types/graph_search_test.go b/internal/types/graph_search_test.go new file mode 100644 index 00000000..56b96bf6 --- /dev/null +++ b/internal/types/graph_search_test.go @@ -0,0 +1,36 @@ +package types + +import ( + "strings" + "testing" + + "github.com/stretchr/testify/require" +) + +func TestGraphSearchRequestNormalize(t *testing.T) { + req := GraphSearchRequest{Query: " 腾讯 "} + require.NoError(t, req.Normalize()) + require.Equal(t, "腾讯", req.Query) + require.Equal(t, 50, req.MaxNodes) + require.Equal(t, 100, req.MaxRelations) + require.Equal(t, 20, req.MaxSourceChunks) + for _, req := range []GraphSearchRequest{ + {Query: ""}, + {Query: "\n\t"}, + {Query: strings.Repeat("中", 513)}, + {Query: string([]byte{0xff})}, + {Query: "Acme", MaxNodes: -1}, + {Query: "Acme", MaxNodes: 101}, + {Query: "Acme", MaxRelations: -1}, + {Query: "Acme", MaxRelations: 201}, + {Query: "Acme", MaxSourceChunks: -1}, + {Query: "Acme", MaxSourceChunks: 51}, + } { + require.Error(t, req.Normalize(), "%+v", req) + } + req = GraphSearchRequest{ + Query: strings.Repeat("中", 512), + MaxNodes: 100, MaxRelations: 200, MaxSourceChunks: 50, + } + require.NoError(t, req.Normalize()) +} diff --git a/internal/types/interfaces/graph_search.go b/internal/types/interfaces/graph_search.go new file mode 100644 index 00000000..7617f306 --- /dev/null +++ b/internal/types/interfaces/graph_search.go @@ -0,0 +1,25 @@ +package interfaces + +import ( + "context" + + "github.com/Tencent/WeKnora/internal/types" +) + +// GraphSearchRepository is separate from the agent retrieval contract: the +// public API needs isolated entities, bounded fields and explicit cap metadata. +type GraphSearchRepository interface { + SearchGraph(context.Context, types.NameSpace, string) (*types.GraphSearchCandidates, error) +} + +// GraphSearchEvidenceRepository reads validated, bounded source content. +type GraphSearchEvidenceRepository interface { + // GetGraphSourceChunks joins live chunks/documents in exactly one owner + // tenant and KB, projecting bounded text in the same SQL read as validation. + GetGraphSourceChunks(context.Context, uint64, string, []string) ([]types.GraphSearchSourceChunk, error) +} + +// GraphSearchService requires an exact KB grant before any graph/database read. +type GraphSearchService interface { + Search(context.Context, *types.KnowledgeBase, types.GraphSearchRequest) (*types.GraphSearchResult, error) +} diff --git a/website-docs/03-features/09-knowledge-graph.md b/website-docs/03-features/09-knowledge-graph.md index 07f28514..0c759bf1 100644 --- a/website-docs/03-features/09-knowledge-graph.md +++ b/website-docs/03-features/09-knowledge-graph.md @@ -21,7 +21,7 @@ | `NEO4J_USERNAME` | string | `neo4j` | 用户名 | | `NEO4J_PASSWORD` | string | `password` | 密码 | -`initNeo4jClient` 启动时最多重试 30 次(间隔 2s)建立并验证连接;未启用时返回 `nil` driver,此时 `Neo4jRepository` 的所有方法降级为 no-op(日志 `NOT SUPPORT RETRIEVE GRAPH`)。`GET /system` 信息接口通过 `getGraphDatabaseEngine()` 报告 `"Neo4j"` 或 `"Not Enabled"`(`internal/handler/system.go`)。 +`initNeo4jClient` 启动时最多重试 30 次(间隔 2s)建立并验证连接;未启用时返回 `nil` driver,此时原有构建、删除及内部 `SearchNode` 路径降级为 no-op(日志 `NOT SUPPORT RETRIEVE GRAPH`)。独立公共查询接口则明确返回 503,不把未配置后端伪装成“没有匹配”。`GET /system` 信息接口通过 `getGraphDatabaseEngine()` 报告 `"Neo4j"` 或 `"Not Enabled"`(`internal/handler/system.go`)。 docker-compose 的 `neo4j` 服务预装 APOC:`NEO4JLABS_PLUGINS=["apoc"]`(图谱写入依赖 `apoc.merge.node` / `apoc.merge.relationship`,删除依赖 `apoc.periodic.iterate`)。 @@ -131,6 +131,12 @@ SET node.chunks = apoc.coll.union(node.chunks, row.chunks) Agent 模式则提供 `query_knowledge_graph` 工具(`internal/agent/tools/query_knowledge_graph.go`):校验各知识库是否配置了图谱(`ExtractConfig.Nodes/Relations` 非空),并发对多库执行检索、按 chunk 去重排序,输出中附带各库的图谱配置状态(实体类型 / 关系类型清单);未配置图谱的库回落为普通混合检索结果。该工具的能力要求是 `all_of: [graph]`,并且只有当 Agent 作用域内存在启用图谱的知识库时才会提供给模型——`agent_service.go` 装配工具白名单时会把它从没有图谱库的作用域中移除,避免模型反复调用一个只能返回退化结果的工具。 +## 独立 JSON 查询 + +外部应用可使用 `POST /api/v1/knowledge-bases/{id}/graph-search`,按区分大小写的实体名子串读取实体、定向关系及有效来源分块。它是单 KB 的只读接口,不调用模型、不修改默认问答/检索管线,亦不是可执行任意 Cypher 的入口。 + +该接口使用独立的有界读取契约:保留无关系实体,返回结果/候选/字段截断标记,并在输出属性与关系前验证完整来源。删除或禁用任一引用分块会使相关实体与关系被保守省略。权限、请求参数、响应字段和上限见 [graph-search API](../04-api/02-api-knowledge.md#graph-search)。 + ## 流程图 ### 构建流程 @@ -168,5 +174,5 @@ flowchart TD ## 可视化 - **Mermaid 图生成**:`internal/application/service/graph.go` 的 `graphBuilder` 是 `types.GraphBuilder` 接口的内存版实现(LLM 抽实体 → 抽关系 → PMI×0.6 + Strength×0.4 计算关系权重并归一到 1-10 → 计算实体度数 → 构建 chunk 关联图),其 `generateKnowledgeGraphDiagram` 用 DFS 找连通分量并输出 Mermaid `graph TD` 子图(高频实体高亮、强度 >7 的关系用粗箭头)。注意:`NewGraphBuilder` 目前没有被容器装配调用(仓库内无其他引用),属于独立/遗留的图构建与可视化实现;生成的 Mermaid 图输出到日志。 -- **对外 API**:知识图谱本身没有专门的可视化 REST 端点;`query_knowledge_graph` 工具的结构化输出(`graph_configs`、结果列表)供 Agent 前端渲染。`GET /wiki/graph`(`wikiHandler.GetGraph`)是 Wiki 功能自己的图接口,与本文的实体关系图谱无关。 +- **对外 API**:`POST /knowledge-bases/{id}/graph-search` 提供独立 JSON 数据,可用于外部可视化,不包含新的内置可视化页面;`query_knowledge_graph` 仍是 Agent 自己的工具输出。`GET /wiki/graph`(`wikiHandler.GetGraph`)是 Wiki 功能自己的图接口,与本文的实体关系图谱无关。 - **prompt 模板**:`config/prompt_templates/graph_extraction.yaml` 提供 `default_extract_entities` 等模板(实体类型枚举 Person/Organization/Location/... 与 JSON 输出协议),经 `internal/config/config.go` 的 `extract_entities_prompt_id` / `extract_relationships_prompt_id` 解析进 `Conversation.ExtractEntitiesPrompt` / `ExtractRelationshipsPrompt`,供上述内存版 `graphBuilder` 使用;生产异步抽取路径使用的是 `config.yaml` 中 `extract.extract_graph` / `extract.extract_entity` 模板(`ExtractManagerConfig`)。 diff --git a/website-docs/04-api/02-api-knowledge.md b/website-docs/04-api/02-api-knowledge.md index a0fcad45..23695565 100644 --- a/website-docs/04-api/02-api-knowledge.md +++ b/website-docs/04-api/02-api-knowledge.md @@ -37,6 +37,45 @@ curl -X POST $BASE/api/v1/knowledge-bases -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' -d '{"name":"产品文档","type":"document"}' ``` +### POST /api/v1/knowledge-bases/:id/graph-search {#graph-search} + +独立的只读 JSON 图谱查询。按 `query` 对实体名称做**区分大小写的子串匹配**,返回匹配实体、其一跳邻居、定向关系和来源分块;也返回没有关系的匹配实体。无需把 Agent 对话输出重新解析成结构化数据。 + +权限:Viewer+ 且对该 KB 有 read 权限(自有、组织共享或共享 Agent)。API key 需 `retrieve`/full,并受 KB 白名单约束。共享 Agent 可带 `agent_id` / `agent_source_tenant_id`,授权规则与 KB 详情一致。 + +本接口不调用 Chat、Embedding 或 Rerank 模型,不修改数据,也不改变 `knowledge-search` / `hybrid-search` 的默认行为。自然语言实体抽取、跨库搜索、多跳遍历不在此接口范围内。 + +| JSON 字段 | 默认值 | 上限 / 含义 | +| --- | --- | --- | +| `query` | 必填 | 去除首尾空白后 1–512 字符;不是 Cypher | +| `max_nodes` | 50 | 100,包含匹配实体和邻居 | +| `max_relations` | 100 | 200 | +| `max_source_chunks` | 20 | 50,来源按 ID 去重 | + +上限字段 `0` 使用默认值;负数或超过上限返回 400。请求体最多 8 KiB,仅接收一个 JSON 对象,未知字段会被拒绝。 + +```bash +curl -X POST "$BASE/api/v1/knowledge-bases/$KB_ID/graph-search" \ + -H "X-API-Key: $API_KEY" -H 'Content-Type: application/json' \ + -d '{"query":"Acme","max_nodes":50,"max_relations":100,"max_source_chunks":20}' +``` + +响应:200 `{"success":true,"data":{...}}`。`data` 字段: + +- `knowledge_base_id`、`query`:本次作用域和规范化查询。 +- `entities`:`id`、`name`、`knowledge_id`、`attributes`、`source_chunk_ids`。ID 是不透明的文档实体身份,不暴露 Neo4j element ID;同名但不同文档的实体不会合并。名称/所属文档不变时,重建图存储不会改变公共 ID。 +- `relationships`:`id`、`source_id`、`target_id`、`type`、`source_chunk_ids`。方向为存储方向,不随查询命中哪一端而反转;两端必须实际出现在 `entities`。来源列表是两端实体来源的并集,不表示每个分块都直接陈述该关系。 +- `source_chunks`:`id`、`knowledge_id`、`title`、`content`、`chunk_index`、`start_at`、`end_at`、`content_truncated`、`title_truncated`。正文最多 2000 字符,标题最多 512 字符;截断时保留原始位置字段,不伪装成完整正文。无匹配结果时三个列表均为 `[]`。 +- `meta`:`truncated`、`truncation_reasons` 和本次生效的三个上限。它不是全图总量统计,也不提供分页游标;需要更完整的结果时应缩小实体名范围。 + +为限制模糊查询成本,内部最多检查 100 个名称匹配种子、512 条一跳关系和 512 个来源分块;查询执行最多 10 秒。候选种子按名称完全匹配优先、名称长度、名称、文档身份排序。属性最多 20 项,每项最多 1000 字符。 + +`truncation_reasons` 的值包括 `candidate_seeds`、`candidate_relations`、`candidate_source_chunks`、`max_nodes`、`max_relations`、`max_source_chunks`、`entity_fields`、`relation_fields`、`source_fields`。只有实际触达的上限才标注,不推测被省略结果的精确数量。 + +来源校验采用保守规则:实体引用的**所有**分块都必须属于当前授权 KB 的该文档,且文档/分块未删除、未禁用,文档不在删除中、分块当前索引就绪;任一来源失效即省略该实体及相关关系。关系两端还必须属于同一文档。无法校验或因预算未检查的图谱事实不会作为已验证结果返回。这可能降低部分旧图谱的召回率;查询不会自动重建图谱,也不能保证模型抽取的事实本身正确。 + +状态:400 参数错误;401 未认证;403 无读取权限/超出 key 范围;404 KB 不存在;409 KB 未开启图谱;500 来源数据库校验失败;503 图谱未配置、连接失败或查询超时。错误不附带部分图谱结果。部署配置见[知识图谱](../03-features/09-knowledge-graph.md)。 + ### 自动标签与 AI 描述配置 创建知识库时 `auto_tag_config`、`profile_config` 位于顶层;更新时放在 `config.auto_tag_config`、`config.profile_config`。两者仅 document 知识库支持,默认 enabled=false。