feat(graph): add standalone JSON graph search API (#4395)

main
Xinliang Zheng 2026-10-17 23:00:55 +08:00 committed by GitHub
parent b373374bf3
commit 164dafca85
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
21 changed files with 2386 additions and 2 deletions

View File

@ -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": {

View File

@ -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": {

View File

@ -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:

View File

@ -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) {

View File

@ -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
}

View File

@ -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")
}

View File

@ -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
}

View File

@ -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)
})
}

View File

@ -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[:])
}

View File

@ -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")
}

View File

@ -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))

View File

@ -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})
}

View File

@ -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)
}
})
}
}

View File

@ -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)

View File

@ -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)
}

View File

@ -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)
}

View File

@ -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"`
}

View File

@ -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())
}

View File

@ -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)
}

View File

@ -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`)。

View File

@ -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。