Agent 搜索 API 文档

面向 agent 提供 pattern 数据库的分类树和元素查询接口

本文档包含三个搜索相关的 API 接口：

关键词搜索 - 根据关键词搜索分类和元素
获取分类树 - 获取指定分类的完整路径和子树
获取全量元素 - 分页浏览元素，支持排序和筛选

接口 1：关键词搜索

接口地址

GET http://8.147.104.190:8001/api/agent/search

功能说明

搜索全局分类库中的分类（Category）和元素（Element），支持文本匹配、上下文扩展、平台筛选等功能。

请求参数

参数名	类型	必填	默认值	说明
q	string	✓	-	搜索关键词
source_type	string	✓	-	元素类型：`实质` / `形式` / `意图`
entity_type	string	✗	all	搜索对象类型：`category`（分类）/ `element`（元素）/ `all`（全部）
top_k	integer	✗	20	返回结果数量，范围 1-100
use_description	boolean	✗	false	是否在描述字段中搜索（true=搜索名称+描述，false=仅搜索名称）
execution_id	integer	✗	null	按执行 ID 筛选（可选）
platform	string	✗	null	按平台筛选元素（如：`小红书`、`抖音` 等），仅对元素有效
include_ancestors	boolean	✗	false	是否返回祖先路径（从根节点到父节点的完整路径）
descendant_depth	integer	✗	0	返回 N 代以内的子孙节点，0=不返回，1=直接子节点，2=子节点+孙节点...

返回格式

{
  "success": true,
  "query": "搜索关键词",
  "source_type": "实质",
  "entity_type": "all",
  "count": 3,
  "results": [
    {
      "entity_type": "category",
      "entity_id": 123,
      "stable_id": 456,
      "name": "分类名称",
      "description": "分类描述",
      "path": "/一级分类/二级分类",
      "category_nature": "领域层级",
      "level": 2
    },
    {
      "entity_type": "element",
      "entity_id": 789,
      "name": "元素名称",
      "description": "元素描述",
      "category_path": "/一级分类/二级分类"
    }
  ]
}

返回字段说明

通用字段

success: 请求是否成功
query: 搜索关键词
source_type: 元素类型
entity_type: 搜索对象类型
count: 返回结果数量
results: 结果列表

结果对象字段（分类 Category）

entity_type: 固定为 "category"
entity_id: 分类数据库 ID
stable_id: 分类稳定 ID（source_stable_id）
name: 分类名称
description: 分类描述
path: 分类路径（如 /主体/角色类型/人物角色）
category_nature: 分类性质（领域层级/元描述层级）
level: 层级深度（1=根节点）

结果对象字段（元素 Element）

entity_type: 固定为 "element"
entity_id: 元素数据库 ID
name: 元素名称
description: 元素描述
category_path: 所属分类路径

使用示例

1. 基础搜索

搜索所有（分类+元素）

curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=角色" \
  --data-urlencode "source_type=实质"

只搜索分类

curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=主体" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "entity_type=category"

只搜索元素

curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=猫咪" \
  --data-urlencode "source_type=形式" \
  --data-urlencode "entity_type=element"

限制返回数量

curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=角色" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "top_k=5"

2. 扩展搜索范围

搜索名称+描述

curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=拟人" \
  --data-urlencode "source_type=形式" \
  --data-urlencode "use_description=true"

3. 获取上下文信息

返回祖先路径

curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=人物角色" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "entity_type=category" \
  --data-urlencode "include_ancestors=true"

返回1代子孙节点

curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=主体" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "entity_type=category" \
  --data-urlencode "descendant_depth=1"

返回2代子孙节点

curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=主体" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "entity_type=category" \
  --data-urlencode "descendant_depth=2"

同时返回祖先+子孙

curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=角色类型" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "entity_type=category" \
  --data-urlencode "include_ancestors=true" \
  --data-urlencode "descendant_depth=2"

4. 平台筛选

只搜索小红书平台的元素

curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=角色" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "entity_type=element" \
  --data-urlencode "platform=小红书"

搜索抖音平台的元素

curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=主体" \
  --data-urlencode "source_type=形式" \
  --data-urlencode "platform=抖音"

平台筛选+描述搜索

curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=拟人" \
  --data-urlencode "source_type=形式" \
  --data-urlencode "platform=小红书" \
  --data-urlencode "use_description=true"

5. 组合查询

全功能组合

curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=角色" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "entity_type=all" \
  --data-urlencode "top_k=10" \
  --data-urlencode "use_description=true" \
  --data-urlencode "include_ancestors=true" \
  --data-urlencode "descendant_depth=1" \
  --data-urlencode "platform=小红书"

不同 source_type 的搜索

# 搜索意图维度
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=情感" \
  --data-urlencode "source_type=意图"

# 搜索形式维度
curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=视觉" \
  --data-urlencode "source_type=形式"

6. 浏览器直接访问

http://8.147.104.190:8001/api/agent/search?q=角色&source_type=实质
http://8.147.104.190:8001/api/agent/search?q=主体&source_type=实质&entity_type=category&include_ancestors=true&descendant_depth=2
http://8.147.104.190:8001/api/agent/search?q=猫咪&source_type=形式&platform=小红书

7. FastAPI 交互式文档

访问以下地址可以在网页上直接测试 API：

http://8.147.104.190:8001/docs

在文档页面找到 /api/search 接口，点击 "Try it out" 按钮，填写参数后点击 "Execute" 即可测试。

返回示例

示例 1：基础搜索

请求：

curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=角色" \
  --data-urlencode "source_type=实质"

响应：

{
  "success": true,
  "query": "角色",
  "source_type": "实质",
  "entity_type": "all",
  "count": 2,
  "results": [
    {
      "entity_type": "category",
      "entity_id": 123,
      "stable_id": 456,
      "name": "角色类型",
      "description": "内容主体的角色分类",
      "path": "/主体/角色类型",
      "category_nature": "领域层级",
      "level": 2,
      "score": 0.95,
      "scores": {
        "text": 0.95,
        "vector": 0.0
      }
    },
    {
      "entity_type": "element",
      "entity_id": 789,
      "name": "人物角色",
      "description": "真实或虚拟的人物形象",
      "belong_category_stable_id": 456,
      "occurrence_count": 25,
      "score": 0.88,
      "scores": {
        "text": 0.88,
        "vector": 0.0
      }
    }
  ]
}

示例 2：带祖先和子孙的搜索

请求：

curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=角色类型" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "entity_type=category" \
  --data-urlencode "include_ancestors=true" \
  --data-urlencode "descendant_depth=2"

响应：

{
  "success": true,
  "query": "角色类型",
  "source_type": "实质",
  "entity_type": "category",
  "count": 1,
  "results": [
    {
      "entity_type": "category",
      "entity_id": 123,
      "stable_id": 456,
      "name": "角色类型",
      "description": "内容主体的角色分类",
      "path": "/主体/角色类型",
      "category_nature": "领域层级",
      "level": 2,
      "score": 1.0,
      "scores": {
        "text": 1.0,
        "vector": 0.0
      },
      "ancestors": [
        {
          "stable_id": 1,
          "name": "主体",
          "level": 1
        }
      ],
      "descendants": [
        {
          "stable_id": 500,
          "name": "人物角色",
          "level": 3,
          "depth_from_parent": 1,
          "is_leaf": false
        },
        {
          "stable_id": 501,
          "name": "动物角色",
          "level": 3,
          "depth_from_parent": 1,
          "is_leaf": false
        },
        {
          "stable_id": 600,
          "name": "真人角色",
          "level": 4,
          "depth_from_parent": 2,
          "is_leaf": true
        },
        {
          "stable_id": 601,
          "name": "虚拟角色",
          "level": 4,
          "depth_from_parent": 2,
          "is_leaf": true
        }
      ]
    }
  ]
}

示例 3：平台筛选

请求：

curl -G "http://8.147.104.190:8001/api/agent/search" \
  --data-urlencode "q=猫咪" \
  --data-urlencode "source_type=形式" \
  --data-urlencode "entity_type=element" \
  --data-urlencode "platform=小红书"

响应：

{
  "success": true,
  "query": "猫咪",
  "source_type": "形式",
  "entity_type": "element",
  "count": 3,
  "results": [
    {
      "entity_type": "element",
      "entity_id": 1001,
      "name": "猫咪",
      "description": "可爱的猫咪形象",
      "belong_category_stable_id": 200,
      "occurrence_count": 15,
      "score": 1.0,
      "scores": {
        "text": 1.0,
        "vector": 0.0
      }
    },
    {
      "entity_type": "element",
      "entity_id": 1002,
      "name": "猫咪拟人",
      "description": "拟人化的猫咪角色",
      "belong_category_stable_id": 201,
      "occurrence_count": 8,
      "score": 0.85,
      "scores": {
        "text": 0.85,
        "vector": 0.0
      }
    }
  ]
}

错误处理

错误响应格式

{
  "detail": "错误信息描述"
}

常见错误

HTTP 状态码	错误原因	解决方法
400	缺少必填参数（q 或 source_type）	检查请求参数
400	source_type 值不合法	使用 `实质`、`形式` 或 `意图`
400	entity_type 值不合法	使用 `category`、`element` 或 `all`
400	mode 不支持	当前仅支持 `text` 模式
500	服务器内部错误	联系技术支持

注意事项

中文参数编码：使用 curl 时，中文参数需要用 --data-urlencode 进行 URL 编码
平台筛选限制：platform 参数仅对元素（element）有效，对分类（category）无效
性能考虑：
- use_description=true 会增加搜索范围，可能降低精确度
- descendant_depth 越大，返回数据越多，响应时间越长
- 建议 top_k 不超过 50
搜索模式：当前仅支持 text 模式，vector 和 hybrid 模式将在后续版本中支持
平台名称：platform 参数值需要与数据库中的平台名称完全一致（区分大小写）

接口 2：获取分类树

接口地址

GET http://8.147.104.190:8001/api/agent/search/category/{stable_id}

功能说明

获取指定分类的完整路径和子树结构，用于导航和展示分类层级关系。

请求参数

参数名	类型	必填	默认值	说明
stable_id	integer	✓	-	分类的 stable_id（路径参数）
source_type	string	✓	-	元素类型：`实质` / `形式` / `意图`
include_ancestors	boolean	✗	true	是否返回祖先路径（从根节点到当前节点）
descendant_depth	integer	✗	-1	返回子孙深度，-1=全部，0=仅当前节点，1=子节点，2=子+孙...

返回格式

{
  "success": true,
  "current": {
    "stable_id": 125,
    "name": "吉祥用语",
    "description": "通用的吉祥话语和祝福词句",
    "path": "/表象/符号/表达符号/祝福语/吉祥用语",
    "level": 5
  },
  "ancestors": [
    {
      "stable_id": 38,
      "name": "表象",
      "path": "/表象",
      "level": 1
    },
    {
      "stable_id": 40,
      "name": "符号",
      "path": "/表象/符号",
      "level": 2
    }
  ],
  "descendants": [
    {
      "stable_id": 126,
      "name": "新年祝福",
      "description": "新年相关的祝福语",
      "path": "/表象/符号/表达符号/祝福语/吉祥用语/新年祝福",
      "level": 6,
      "children": []
    }
  ]
}

使用示例

获取分类的完整路径和所有子孙

curl -G "http://8.147.104.190:8001/api/agent/search/category/125" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "include_ancestors=true" \
  --data-urlencode "descendant_depth=-1"

只获取当前节点和祖先路径

curl -G "http://8.147.104.190:8001/api/agent/search/category/125" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "include_ancestors=true" \
  --data-urlencode "descendant_depth=0"

获取2代子孙节点

curl -G "http://8.147.104.190:8001/api/agent/search/category/125" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "descendant_depth=2"

接口 3：获取全量元素数据

接口地址

GET http://8.147.104.190:8001/api/agent/search/elements

功能说明

获取全量元素数据，支持分页、排序、筛选。主要用于获取高频元素、按分类浏览元素等场景。

请求参数

参数名	类型	必填	默认值	说明
source_type	string	✓	-	元素类型：`实质` / `形式` / `意图`
execution_id	integer	✗	null	按执行 ID 筛选（可选）
page	integer	✗	1	页码（从1开始）
page_size	integer	✗	50	每页数量（1-200）
sort_by	string	✗	name	排序字段：`name` / `id` / `occurrence_count`
order	string	✗	asc	排序方向：`asc` / `desc`
category_path	string	✗	null	按分类路径前缀筛选（可选）
platform	string	✗	null	按平台筛选（可选）
min_occurrence	integer	✗	null	最小出现次数（可选）

返回格式

{
  "success": true,
  "source_type": "实质",
  "page": 1,
  "page_size": 50,
  "total": 4082,
  "total_pages": 82,
  "results": [
    {
      "id": 45,
      "name": "祝福语",
      "description": "'吉祥如意'、'幸福安康'等文字内容",
      "occurrence_count": 974,
      "element_sub_type": "具象概念",
      "category": {
        "stable_id": 125,
        "name": "吉祥用语",
        "path": "/表象/符号/表达符号/祝福语/吉祥用语"
      }
    }
  ]
}

使用示例

获取高频元素前50（默认）

curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=实质"

获取高频元素前10

curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=10" \
  --data-urlencode "sort_by=occurrence_count" \
  --data-urlencode "order=desc"

按名称排序

curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=形式" \
  --data-urlencode "sort_by=name" \
  --data-urlencode "order=asc"

筛选指定分类下的元素

curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "category_stable_id=125"

筛选出现次数>=10的元素

curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "min_occurrence=10"

按平台筛选元素

curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=形式" \
  --data-urlencode "platform=小红书"

组合筛选：指定分类+最小出现次数

curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "category_stable_id=125" \
  --data-urlencode "min_occurrence=50" \
  --data-urlencode "page_size=20"

分页浏览

# 第1页
curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=50"

# 第2页
curl -G "http://8.147.104.190:8001/api/agent/search/elements" \
  --data-urlencode "source_type=实质" \
  --data-urlencode "page=2" \
  --data-urlencode "page_size=50"

内容树API.md 18 KB Lịch sử Raw

Agent 搜索 API 文档

接口 1：关键词搜索

接口地址

功能说明

请求参数

返回格式

返回字段说明

通用字段

结果对象字段（分类 Category）

结果对象字段（元素 Element）

使用示例

1. 基础搜索

搜索所有（分类+元素）

只搜索分类

只搜索元素

限制返回数量

2. 扩展搜索范围

搜索名称+描述

3. 获取上下文信息

返回祖先路径

返回1代子孙节点

返回2代子孙节点

同时返回祖先+子孙

4. 平台筛选

只搜索小红书平台的元素

搜索抖音平台的元素

平台筛选+描述搜索

5. 组合查询

全功能组合

不同 source_type 的搜索

6. 浏览器直接访问

7. FastAPI 交互式文档

返回示例

示例 1：基础搜索

示例 2：带祖先和子孙的搜索

示例 3：平台筛选

错误处理

错误响应格式

常见错误

注意事项

接口 2：获取分类树

接口地址

功能说明

请求参数

返回格式

使用示例

获取分类的完整路径和所有子孙

只获取当前节点和祖先路径

获取2代子孙节点

接口 3：获取全量元素数据

接口地址

功能说明

请求参数

返回格式

使用示例

获取高频元素前50（默认）

获取高频元素前10

按名称排序

筛选指定分类下的元素

筛选出现次数>=10的元素

按平台筛选元素

组合筛选：指定分类+最小出现次数

分页浏览

内容树API.md 18 KB

Lịch sử Raw