Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
feat(graph): add standalone JSON graph search API (#4395)
Xinliang Zheng164dafca85a4
diff --git a/docs/docs.go b/docs/docs.goindex 4464d9d2f..826588e67 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.jsonindex 2b7d1306b..5ae09e897 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.yamlindex ee9b480ad..ffa670703 100644--- a/docs/swagger.yaml+++ b/docs/swagger.yaml@@ -3546,6 +3546,119 @@ definitions:type:type: stringtype: 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: objectgithub_com_Tencent_WeKnora_internal_types.History:properties:answer:@@ -17748,6 +17861,77 @@ paths:summary: 搜索FAQtags:- 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.goindex 1be752cfa..fcf5816aa 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.gonew file mode 100644index 000000000..5b951c9ff--- /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.gonew file mode 100644index 000000000..02dbfddb3--- /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.gonew file mode 100644index 000000000..9d47d530c--- /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.gonew file mode 100644index 000000000..2b6d4e1b3--- /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.gonew file mode 100644index 000000000..fbcec51b5--- /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.gonew file mode 100644index 000000000..d4e5c85a1--- /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.goindex edb2a304f..99b49b7b9 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 KnowledgeTagServicemust(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.gonew file mode 100644index 000000000..7aee3726a--- /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.gonew file mode 100644index 000000000..e6c38d2d6--- /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.goindex d2545215d..29f37d3b1 100644--- a/internal/router/router.go+++ b/internal/router/router.go@@ -44,6 +44,7 @@ type RouterParams struct {KBShareService interfaces.KBShareServiceAgentShareService interfaces.AgentShareServiceKBHandler *handler.KnowledgeBaseHandler+ GraphSearchHandler *handler.GraphSearchHandlerKnowledgeHandler *handler.KnowledgeHandlerTenantHandler *handler.TenantHandlerTenantService 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.gonew file mode 100644index 000000000..f81729e77--- /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.gonew file mode 100644index 000000000..e876ebb8a--- /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.gonew file mode 100644index 000000000..e930e39d5--- /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.gonew file mode 100644index 000000000..56b96bf67--- /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.gonew file mode 100644index 000000000..7617f3062--- /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.mdindex 07f28514b..0c759bf1f 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.mdindex a0fcad45f..236955659 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。