pingtai_agent/dedup_agent/USAGE.md

信息去重 Agent

---

本 Agent 提供基于 领域理解 的信息去重能力，通过 HTTP API 与 MCP（Model Context Protocol） 对外提供服务。

核心能力：

• 语义去重：基于深度语义分析识别本质相同的信息
• 重复检测：多粒度阈值的重复项识别
• 本质提取：信息核心语义的精准提炼

---

功能概览

提供信息集合的 语义理解、领域判断、重复检测、本质提取 能力，返回结构化分析结果。

支持能力：

• 语义聚类与去重
• 可调阈值的重复检测
• 信息本质与关键词提取
• 去重率统计

---

1⃣ deduplicate_info — 语义领域去重

功能说明

对输入的信息集合进行深度领域分析，识别 本质相同 的内容并归类合并，返回去重后的分组结果。

---

REST API 调用

POST /api/v1/deduplicate
Content-Type: application/json
api-key: {your-api-key}

{
  "items": [
    "苹果公司发布了新款 iPhone",
    "Apple 推出最新 iPhone 系列",
    "微软发布 Windows 更新",
    "苹果今天发布了 iPhone 新产品"
  ],
  "context": "科技新闻"
}

---

MCP 调用

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "deduplicate_info",
    "arguments": {
      "items": [
        "苹果公司发布了新款 iPhone",
        "Apple 推出最新 iPhone 系列",
        "微软发布 Windows 更新",
        "苹果今天发布了 iPhone 新产品"
      ],
      "context": "科技新闻"
    }
  }
}

---

参数说明

参数	类型	必需	默认值	说明
items	array<string>	✅	-	待去重的信息列表
context	string	❌	null	上下文说明，辅助语义理解

---

返回结果

{
  "success": true,
  "groups": [
    {
      "representative": "苹果公司发布了新款 iPhone",
      "members": [
        "苹果公司发布了新款 iPhone",
        "Apple 推出最新 iPhone 系列",
        "苹果今天发布了 iPhone 新产品"
      ],
      "essence": "苹果发布新iPhone"
    },
    {
      "representative": "微软发布 Windows 更新",
      "members": ["微软发布 Windows 更新"],
      "essence": "微软Windows更新"
    }
  ],
  "total_input": 4,
  "total_groups": 2,
  "dedup_ratio": "50%"
}

---

返回字段说明

字段	类型	说明
groups	array	去重后的分组列表
groups[].representative	string	该组的代表性表述（原文）
groups[].members	array	该组包含的所有原始信息
groups[].essence	string	该组信息的本质概括
total_input	integer	输入信息总数
total_groups	integer	去重后分组数
dedup_ratio	string	去重率

---

2️⃣ find_duplicates — 重复检测

功能说明

快速识别信息集合中的重复项，支持 多粒度阈值 控制检测严格程度。

---

REST API 调用

POST /api/v1/find-duplicates
Content-Type: application/json
api-key: {your-api-key}

{
  "items": [
    "今天天气很好",
    "今日阳光明媚",
    "明天会下雨",
    "天气晴朗适合外出"
  ],
  "threshold": "normal"
}

---

MCP 调用

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find_duplicates",
    "arguments": {
      "items": [
        "今天天气很好",
        "今日阳光明媚",
        "明天会下雨"
      ],
      "threshold": "strict"
    }
  }
}

---

参数说明

参数	类型	必需	默认值	说明
items	array<string>	✅	-	待检测的信息列表
threshold	string	❌	normal	检测阈值：strict / normal / loose

---

阈值说明

阈值	检测策略
strict	仅识别近乎完全相同的内容
normal	识别本质含义相同的内容
loose	识别主题相关的内容

---

返回结果

{
  "success": true,
  "has_duplicates": true,
  "duplicate_pairs": [
    {
      "items": [1, 2, 4],
      "reason": "均表达天气状况良好"
    }
  ],
  "unique_count": 2
}

---

3️⃣ extract_essence — 本质提取

功能说明

对每条信息进行语义分析，提取其 核心本质 与 关键词，便于后续比对或索引。

---

REST API 调用

POST /api/v1/extract-essence
Content-Type: application/json
api-key: {your-api-key}

{
  "items": [
    "特斯拉宣布下调全系车型售价",
    "OpenAI 发布了 GPT-5 模型",
    "中国央行决定降息25个基点"
  ]
}

---

MCP 调用

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "extract_essence",
    "arguments": {
      "items": [
        "特斯拉宣布下调全系车型售价",
        "OpenAI 发布了 GPT-5 模型"
      ]
    }
  }
}

---

参数说明

参数	类型	必需	默认值	说明
items	array<string>	✅	-	待提取本质的信息列表

---

返回结果

{
  "success": true,
  "essences": [
    {
      "original": "特斯拉宣布下调全系车型售价",
      "essence": "特斯拉降价",
      "keywords": ["特斯拉", "降价", "车型"]
    },
    {
      "original": "OpenAI 发布了 GPT-5 模型",
      "essence": "OpenAI发布新模型",
      "keywords": ["OpenAI", "GPT-5", "模型"]
    },
    {
      "original": "中国央行决定降息25个基点",
      "essence": "央行降息",
      "keywords": ["央行", "降息", "利率"]
    }
  ]
}

---

统一错误格式

成功：

{
  "success": true,
  "data": {}
}

失败：

{
  "success": false,
  "error": "错误描述"
}

---

服务端点

端点	方法	说明
/	GET	服务状态
/health	GET	健康检查
/mcp	POST	MCP JSON-RPC
/mcp/sse	GET/POST	MCP SSE 流式
/api/v1/deduplicate	POST	语义去重
/api/v1/find-duplicates	POST	重复检测
/api/v1/extract-essence	POST	本质提取

---

部署信息

配置项	值
镜像地址	agnettaiji.azurecr.io/ai-agents/dedup-agent:latest
服务端口	8000
健康检查	/health