feat: add knowledge management functionality with CRUD operations and database schema
- Implemented KnowledgeHandler for managing knowledge groups and items, including listing, creating, updating, and deleting operations. - Added database migration scripts to create necessary tables for knowledge management, including knowledge_groups, knowledge_items, knowledge_parse_tasks, and knowledge_chunks_meta. - Introduced prompt_rule_knowledge_groups table to associate prompt rules with knowledge groups.
This commit is contained in:
@@ -0,0 +1,462 @@
|
||||
# AI 品牌监测数据抓取可行性与采集方案 V1
|
||||
|
||||
## 1. 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
| --- | --- |
|
||||
| 文档名称 | AI 品牌监测数据抓取可行性与采集方案 V1 |
|
||||
| 文档版本 | V1.0 |
|
||||
| 文档状态 | 待评审 |
|
||||
| 创建日期 | 2026-04-05 |
|
||||
| 适用范围 | AI 品牌监测的数据采集、解析、可行性验证 |
|
||||
| 关联文档 | `docs/ai-brand-monitoring-tech-design-v2.md` |
|
||||
| 关联文档 | `docs/question-driven-monitoring-design-v1.md` |
|
||||
| 验证方式 | 本地代码审阅 + 官方文档核验（核验日期：2026-04-05） |
|
||||
|
||||
## 2. 目标与非目标
|
||||
|
||||
### 2.1 目标
|
||||
|
||||
本文回答三个问题：
|
||||
|
||||
1. 现有“品牌监测”数据抓取是否技术上可行。
|
||||
2. 如果可行，主链路应该怎么设计才稳定、可扩展、可验证。
|
||||
3. 哪些结果可以承诺，哪些结果不能承诺。
|
||||
|
||||
### 2.2 非目标
|
||||
|
||||
本文不试图解决以下问题：
|
||||
|
||||
1. 不承诺“100% 复刻用户在各家 APP / Web 端看到的答案、排序和引用”。
|
||||
2. 不展开前端页面与汇总查询设计，这部分仍以 `docs/ai-brand-monitoring-tech-design-v2.md` 为主。
|
||||
3. 不直接替代各平台的商务接入、法务评估和账号申请流程。
|
||||
|
||||
## 3. 核心结论
|
||||
|
||||
结论先说：
|
||||
|
||||
1. **“官方 API 口径下的品牌监测”是可行的。**
|
||||
2. **“搜索增强 / 引用型品牌监测”是部分可行的，但要按平台能力分层实现。**
|
||||
3. **“完全等价于终端用户在 APP / Web 里看到的内容”不可承诺，至少 DeepSeek 官方已明确 API 与 APP/Web 版本不同。**
|
||||
|
||||
因此，监测目标必须拆成三档：
|
||||
|
||||
| 档位 | 定义 | 可行性 | 是否建议纳入主链路 |
|
||||
| --- | --- | --- | --- |
|
||||
| A. 标准化 API 监测 | 统一问题、统一温度、统一提示词，通过官方 API 取回答，再做品牌/竞品/引用解析 | 高 | 是 |
|
||||
| B. 搜索增强监测 | 使用平台官方搜索增强、联网搜索、引文能力，监测“搜索型回答中的品牌曝光” | 中到高 | 是，但只对支持平台开启 |
|
||||
| C. APP/Web 拟真监测 | 模拟用户在各家产品前台提问，追求与终端用户体验一致 | 低到中 | 否，不建议作为主数据源 |
|
||||
|
||||
对 V2 方案的建议是：
|
||||
|
||||
1. **主数据源只走官方 API。**
|
||||
2. **搜索增强能力按平台单独开关，不搞“全平台统一假设”。**
|
||||
3. **如果业务一定要看终端用户视角，单独做“小样本 UI 观测集”，不要并入核心统计口径。**
|
||||
|
||||
## 4. 官方能力核验结果
|
||||
|
||||
以下结论基于 2026-04-05 当天核验到的官方材料。
|
||||
|
||||
### 4.1 平台能力矩阵
|
||||
|
||||
| 平台 | 官方能力核验 | 可用于监测的能力 | 可行性判断 | 备注 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| DeepSeek | 官方 API 与 OpenAI 兼容；官方文档明确 API 对应的 `deepseek-chat` / `deepseek-reasoner` 与 APP/Web 版本不同；官方 rate limit 页面说明高流量下会排队，10 分钟未开始推理会断开 | 标准对话、流式、工具调用入口 | **标准 API 监测可行；终端拟真不可承诺** | 适合作为“基础语言口径”，不适合作为“用户端搜索曝光”唯一来源 |
|
||||
| 通义千问 / 百炼 | OpenAI 兼容；支持 `tools`；支持 `enable_search` 与 `search_options.forced_search`；支持 Batch Chat 与文件批量提交 | 标准对话、函数调用、联网搜索、批量离线推理 | **高可行** | 很适合作为主力采集平台之一 |
|
||||
| 豆包 / 火山方舟 | 官方文档明确有 `Web Search（联网搜索）`、`Function Calling`、`File API`；部署文档区分在线推理与批量推理；常规在线推理说明公共资源池下延迟和并发一般、共享限流 | 标准对话、联网搜索、工具调用、批量推理 | **高可行** | 适合做搜索型监测，但生产要避免完全依赖公共在线推理 |
|
||||
| 腾讯混元 | OpenAI 兼容；默认 5 并发；支持 `enable_enhancement`、`force_search_enhancement`、`search_info`、`citation` | 标准对话、搜索增强、返回搜索信息、回答角标引文 | **能力强，但默认并发偏低** | 搜索引用监测非常适合，但必须提前做并发扩容或限额申请 |
|
||||
| 文心一言 / 千帆 | 百度官方产品页确认企业服务由千帆大模型平台提供，含推理服务和工具链，并支持私有资源托管保障并发 | 平台接入可行 | **中可行，需先做 PoC** | 本次核验中，官方可抓取材料足以确认“能接入”，但不足以确认搜索/引文参数细节 |
|
||||
|
||||
### 4.2 关键判断
|
||||
|
||||
#### 判断 1：能抓到数据，不代表能复刻用户端
|
||||
|
||||
DeepSeek 官方文档明确说 API 模型与 APP/Web 版本不同，这意味着：
|
||||
|
||||
1. 即使问题文案一样，回答内容也可能不同。
|
||||
2. 即使回答主题相近，排序、措辞、引用也可能不同。
|
||||
3. 因此不能把 API 数据直接包装成“终端用户真实看到的内容”。
|
||||
|
||||
#### 判断 2：搜索增强和引用能力不是全平台对齐的
|
||||
|
||||
各家平台差异很大：
|
||||
|
||||
1. 混元已经把 `search_info` 和 `citation` 直接定义成参数。
|
||||
2. 千问已明确支持 `enable_search`，还能强制搜索。
|
||||
3. 方舟已把 Web Search 作为标准工具能力。
|
||||
4. DeepSeek 在本次核验的官方材料里，没有看到同等级别的“原生联网搜索 + 引文返回”说明。
|
||||
5. 百度千帆本次核验只确认了平台接入能力，搜索与引文细节仍需单独 PoC。
|
||||
|
||||
因此，**“平台统一采集器 + 平台能力开关”是必须的，不是可选项。**
|
||||
|
||||
#### 判断 3：批量离线比凌晨突发跑批更靠谱
|
||||
|
||||
监测任务本质是离线任务，不是用户实时请求。对于大批量问题：
|
||||
|
||||
1. 千问官方明确提供 Batch Chat，适合“无需实时响应”的场景。
|
||||
2. 方舟文档体系也区分了在线推理和批量推理。
|
||||
3. 混元默认只有 5 并发，不适合把所有任务集中在 2 小时窗口内硬跑。
|
||||
|
||||
所以应把采集方案设计成：
|
||||
|
||||
1. **全天分布式执行。**
|
||||
2. **优先使用批量接口。**
|
||||
3. **只有需要搜索增强或即时补采时，才走在线 API。**
|
||||
|
||||
## 5. 建议的数据抓取目标口径
|
||||
|
||||
### 5.1 统一采集单位
|
||||
|
||||
沿用 V1 结论，但扩展成更适合多平台的形式：
|
||||
|
||||
`1 question_version x 1 ai_platform x 1 run_mode x 1 run_time = 1 条原始采集记录`
|
||||
|
||||
其中 `run_mode` 必须显式记录：
|
||||
|
||||
1. `api_standard`
|
||||
2. `api_search_grounded`
|
||||
3. `ui_sample`
|
||||
|
||||
没有这个字段，后续所有跨平台比较都会失真。
|
||||
|
||||
### 5.2 必须采集的原始字段
|
||||
|
||||
建议在现有 `question_monitor_runs` / `question_monitor_parse_results` 之外，至少保证以下信息能落盘：
|
||||
|
||||
| 类别 | 字段 |
|
||||
| --- | --- |
|
||||
| 请求侧 | `provider_key`, `model`, `run_mode`, `prompt_template_version`, `temperature`, `top_p`, `seed`, `search_enabled`, `tool_enabled` |
|
||||
| 响应侧 | `raw_answer_text`, `raw_response_json_key`, `response_latency_ms`, `finish_reason`, `usage_prompt_tokens`, `usage_completion_tokens` |
|
||||
| 搜索证据 | `search_hit`, `search_provider`, `search_info_json`, `citation_markers`, `normalized_citations_json` |
|
||||
| 解析结果 | `brand_mentioned`, `brand_position`, `top1_mentioned`, `first_recommended`, `competitor_mentions`, `sentiment_label`, `brand_keywords_extract` |
|
||||
| 调试追踪 | `request_id`, `retry_count`, `error_code`, `error_message`, `parser_version`, `extractor_version` |
|
||||
|
||||
其中：
|
||||
|
||||
1. `raw_answer_text` 可以存对象存储。
|
||||
2. `raw_response_json_key` 也应该存对象存储，方便 badcase 回放。
|
||||
3. `search_info_json` 必须保留原始返回，后续才能验证引用解析是否正确。
|
||||
|
||||
## 6. 推荐抓取架构
|
||||
|
||||
### 6.1 平台适配器，而不是一个通用 LLM Client 硬扛全部平台
|
||||
|
||||
当前代码里 `Config` 只有一份全局 `LLMConfig`，`llm.New()` 也只按单个 provider 初始化客户端，这不足以支撑监测场景的多平台采集。
|
||||
|
||||
相关代码：
|
||||
|
||||
1. `server/internal/shared/config/config.go`
|
||||
2. `server/internal/shared/llm/client.go`
|
||||
|
||||
建议改成：
|
||||
|
||||
```go
|
||||
type ProviderCapability struct {
|
||||
Chat bool
|
||||
Search bool
|
||||
Citation bool
|
||||
ToolCalling bool
|
||||
Batch bool
|
||||
Streaming bool
|
||||
Deterministic bool
|
||||
}
|
||||
|
||||
type MonitoringProvider interface {
|
||||
Key() string
|
||||
Capability() ProviderCapability
|
||||
Generate(ctx context.Context, req CollectRequest) (*CollectResponse, error)
|
||||
SubmitBatch(ctx context.Context, jobs []CollectRequest) (*BatchJob, error)
|
||||
PollBatch(ctx context.Context, jobID string) (*BatchJobResult, error)
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 建议的抓取链路
|
||||
|
||||
```text
|
||||
调度器
|
||||
-> 任务生成（按品牌 / 问题版本 / 平台 / 模式）
|
||||
-> 去重与幂等校验
|
||||
-> 队列
|
||||
-> Provider Adapter
|
||||
-> 原始响应落对象存储
|
||||
-> 标准化解析器
|
||||
-> 引用规范化
|
||||
-> 质量采样 / badcase
|
||||
-> question_monitor_runs / parse_results
|
||||
-> 日级聚合
|
||||
```
|
||||
|
||||
### 6.3 任务状态机
|
||||
|
||||
必须补全任务状态，不建议只保留 `pending/running/completed/failed` 四态。
|
||||
|
||||
建议至少支持：
|
||||
|
||||
1. `pending`
|
||||
2. `leased`
|
||||
3. `running`
|
||||
4. `succeeded`
|
||||
5. `retryable_failed`
|
||||
6. `dead_letter`
|
||||
7. `cancelled`
|
||||
8. `skipped_dedup`
|
||||
|
||||
原因：
|
||||
|
||||
1. 平台 API 容易超时、排队、限流。
|
||||
2. 搜索增强请求比普通请求更容易波动。
|
||||
3. 如果没有 `retryable_failed` 和 `dead_letter`，PoC 阶段会很难判断是平台问题还是解析问题。
|
||||
|
||||
### 6.4 幂等策略
|
||||
|
||||
建议幂等 key：
|
||||
|
||||
`tenant_id + brand_id + question_version_id + ai_platform_id + run_mode + business_date`
|
||||
|
||||
这样可以保证：
|
||||
|
||||
1. 同一天重复调度不会重复记账。
|
||||
2. 同题跨平台不会互相覆盖。
|
||||
3. `api_standard` 与 `api_search_grounded` 能并存。
|
||||
|
||||
## 7. Prompt 与解析方案
|
||||
|
||||
### 7.1 Prompt 原则
|
||||
|
||||
抓取时不要用自由发挥的产品提示词，要用固定模板。
|
||||
|
||||
建议：
|
||||
|
||||
1. 系统提示词固定版本化。
|
||||
2. 用户问题原文直接使用 `question_version.question_text`。
|
||||
3. 除非平台要求，否则 `temperature` 设为低值。
|
||||
4. 能设置 `seed` 的平台尽量设置，提升复现性。
|
||||
5. 搜索增强模式下，显式要求模型给出品牌推荐及可验证来源。
|
||||
|
||||
### 7.2 解析顺序
|
||||
|
||||
解析不要一上来全交给 LLM。
|
||||
|
||||
建议顺序：
|
||||
|
||||
1. **规则层**：品牌名、竞品名、URL、角标、序号。
|
||||
2. **轻语义层**：品牌排名、首位提及、是否明确推荐。
|
||||
3. **LLM 兜底层**：情感倾向、品牌印象词、复杂引用归因。
|
||||
|
||||
原因：
|
||||
|
||||
1. 规则层稳定、便宜、可复跑。
|
||||
2. 复杂语义才需要 LLM。
|
||||
3. 这样 badcase 也更容易定位。
|
||||
|
||||
### 7.3 引用解析策略
|
||||
|
||||
引用解析建议拆成三层：
|
||||
|
||||
1. **显式链接**：从平台返回的 `search_info`、角标链接、正文 URL 中直接抽取。
|
||||
2. **正文映射**：把角标 `[1]`、`[2]` 映射回 `search_info`。
|
||||
3. **规范化**：统一域名、小写 host、去掉追踪参数、提取站点名、生成 `citation_hash`。
|
||||
|
||||
建议新增规范化后的引用事实结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "https://example.com/a",
|
||||
"normalized_url": "https://example.com/a",
|
||||
"domain": "example.com",
|
||||
"site_name": "Example",
|
||||
"citation_type": "editorial",
|
||||
"position": 1,
|
||||
"source": "search_info",
|
||||
"confidence": 0.98
|
||||
}
|
||||
```
|
||||
|
||||
## 8. 吞吐与调度建议
|
||||
|
||||
### 8.1 不要把采集窗口锁死在凌晨 1 点到 3 点
|
||||
|
||||
以 V2 的规模假设为例：
|
||||
|
||||
`100 品牌 x 100 问题 x 5 平台 x 1 次/天 = 50,000 条/天`
|
||||
|
||||
如果把 50,000 条任务都塞进 2 小时窗口：
|
||||
|
||||
1. 平均需要 `6.94 req/s`。
|
||||
2. 算上超时、重试、抖动，实际需要按 `15~20 req/s` 设计。
|
||||
3. 对默认 5 并发的混元，这个窗口过于激进。
|
||||
|
||||
因此建议：
|
||||
|
||||
1. 日常采集分 6 个时间窗执行，或者全天滚动执行。
|
||||
2. 重要品牌再补一轮搜索增强采集。
|
||||
3. 聚合 Job 与采集 Job 解耦，不要求同一夜全部完成。
|
||||
|
||||
### 8.2 平台分流策略
|
||||
|
||||
建议把平台分成三类：
|
||||
|
||||
| 类别 | 平台 | 建议方式 |
|
||||
| --- | --- | --- |
|
||||
| 标准对话主链路 | DeepSeek | 在线 API，低温、固定 prompt |
|
||||
| 搜索增强主链路 | 千问、混元、方舟 | 优先开官方搜索能力 |
|
||||
| 待验证平台 | 百度千帆 | 先做 PoC，不直接承诺上线指标 |
|
||||
|
||||
### 8.3 批量优先级
|
||||
|
||||
建议优先级：
|
||||
|
||||
1. 能批量就批量。
|
||||
2. 需要搜索增强或引用时再走在线 API。
|
||||
3. 需要“接近用户侧”验证时，只做样本观测，不做全量。
|
||||
|
||||
## 9. PoC 可行性验证方案
|
||||
|
||||
这部分是本方案最核心的落地动作。
|
||||
|
||||
### 9.1 PoC 目标
|
||||
|
||||
在决定正式开发前，先验证四件事：
|
||||
|
||||
1. 各平台能否稳定返回可解析的回答。
|
||||
2. 搜索增强模式下能否拿到可追溯引用。
|
||||
3. 同一个问题多次执行时，结果波动是否在可接受范围内。
|
||||
4. 成本、时延、失败率是否可控。
|
||||
|
||||
### 9.2 PoC 样本设计
|
||||
|
||||
建议最小样本：
|
||||
|
||||
1. 3 个品牌
|
||||
2. 每品牌 30 个问题
|
||||
3. 5 个平台
|
||||
4. 2 种模式：`api_standard`、`api_search_grounded`
|
||||
5. 连续跑 3 天
|
||||
|
||||
总任务量：
|
||||
|
||||
`3 x 30 x 5 x 2 x 3 = 2,700`
|
||||
|
||||
这个规模足够看出：
|
||||
|
||||
1. 平台成功率
|
||||
2. 搜索命中率
|
||||
3. 引用解析效果
|
||||
4. 回答波动
|
||||
|
||||
### 9.3 PoC 验收指标
|
||||
|
||||
建议先用下面的阈值：
|
||||
|
||||
| 指标 | 目标 |
|
||||
| --- | --- |
|
||||
| API 调用成功率 | >= 97% |
|
||||
| 解析成功率 | >= 99% |
|
||||
| 搜索增强模式下“存在可用引用”的比例 | >= 60% |
|
||||
| 品牌提及检测准确率 | >= 95% |
|
||||
| 引用 URL 规范化成功率 | >= 95% |
|
||||
| 单任务 P95 延迟 | <= 20s |
|
||||
| 重试后仍失败率 | <= 2% |
|
||||
|
||||
如果某平台低于阈值：
|
||||
|
||||
1. 不要强行并入统一统计。
|
||||
2. 先降级成“样本观测平台”。
|
||||
|
||||
### 9.4 PoC 输出物
|
||||
|
||||
PoC 结束后必须产出：
|
||||
|
||||
1. 平台能力对比表
|
||||
2. badcase 样本集
|
||||
3. 成本与时延报告
|
||||
4. 建议上线的平台白名单
|
||||
|
||||
## 10. 建议补充的数据表
|
||||
|
||||
V2 当前只覆盖了运行表和解析表，若要把抓取做扎实，建议再补三类表：
|
||||
|
||||
### 10.1 `monitoring_collect_tasks`
|
||||
|
||||
用途：
|
||||
|
||||
1. 存调度任务
|
||||
2. 管理状态机
|
||||
3. 支撑重试、死信、优先级
|
||||
|
||||
### 10.2 `monitoring_citation_facts`
|
||||
|
||||
用途：
|
||||
|
||||
1. 保存规范化后的引用事实
|
||||
2. 便于后续按域名、站点、页面统计
|
||||
3. 避免每次都从 JSONB 重新解析
|
||||
|
||||
### 10.3 `monitoring_parse_badcases`
|
||||
|
||||
用途：
|
||||
|
||||
1. 保存低置信度或人工标错样本
|
||||
2. 支撑解析器迭代
|
||||
3. 给后续模型评测提供数据集
|
||||
|
||||
## 11. 实施建议
|
||||
|
||||
### Phase A：两周内完成 PoC
|
||||
|
||||
1. 先接 3 个最清晰的平台：千问、混元、方舟。
|
||||
2. DeepSeek 只做 `api_standard`。
|
||||
3. 百度千帆只做可接入性验证，不承诺引用链路。
|
||||
|
||||
### Phase B：收敛主链路
|
||||
|
||||
1. 形成统一 `MonitoringProvider` 抽象。
|
||||
2. 完成搜索增强、引用解析、规范化。
|
||||
3. 上线 badcase 采样与抽检。
|
||||
|
||||
### Phase C：再决定是否做 UI 观测
|
||||
|
||||
只有当业务方明确要求“终端用户真实视角”时，才考虑单独建设 UI 观测链路；且必须先做：
|
||||
|
||||
1. 法务 / ToS 评估
|
||||
2. 账号稳定性评估
|
||||
3. 样本规模评估
|
||||
|
||||
它不应进入 V1 主数据链路。
|
||||
|
||||
## 12. 对现有 V2 方案的直接修正建议
|
||||
|
||||
基于本文结论，建议对 `docs/ai-brand-monitoring-tech-design-v2.md` 做以下修正：
|
||||
|
||||
1. 把“采集流水线”从通用 `llm.Client` 调整为“平台适配器 + 能力开关”。
|
||||
2. 增加 `run_mode` 字段，区分标准模式与搜索增强模式。
|
||||
3. 增加任务表、死信策略、重试退避、幂等 key。
|
||||
4. 不再默认所有平台都能产出引用来源数据。
|
||||
5. 把凌晨集中跑批改成“滚动采集 + 批量优先”。
|
||||
6. 在上线前增加 PoC 验收阶段，而不是直接进入全量开发。
|
||||
|
||||
## 13. 官方核验链接
|
||||
|
||||
以下均为本次用于判断可行性的官方材料：
|
||||
|
||||
1. DeepSeek API Docs: https://api-docs.deepseek.com/
|
||||
2. DeepSeek Rate Limit: https://api-docs.deepseek.com/quick_start/rate_limit
|
||||
3. 阿里云百炼 OpenAI 兼容: https://help.aliyun.com/zh/model-studio/compatibility-of-openai-with-dashscope
|
||||
4. 阿里云百炼 Batch Chat: https://help.aliyun.com/zh/model-studio/openai-compatible-batch-chat
|
||||
5. 腾讯混元 OpenAI 兼容接口: https://cloud.tencent.com/document/product/1729/111007
|
||||
6. 火山方舟 Web Search: https://www.volcengine.com/docs/82379/1756990
|
||||
7. 火山方舟常规在线推理: https://www.volcengine.com/docs/82379/2121998
|
||||
8. 百度文心一言 / 千帆平台: https://cloud.baidu.com/wenxin.html
|
||||
|
||||
## 14. 最终结论
|
||||
|
||||
一句话总结：
|
||||
|
||||
**这件事能做，但必须把“官方 API 监测”与“终端用户视角监测”分开设计。**
|
||||
|
||||
对当前项目最现实的路线是：
|
||||
|
||||
1. 先做基于官方 API 的标准化品牌监测。
|
||||
2. 对具备官方搜索能力的平台，叠加搜索增强与引用监测。
|
||||
3. 用 PoC 决定百度千帆是否进入第一批上线平台。
|
||||
4. 不把 APP/Web 前台抓取作为主链路承诺项。
|
||||
Reference in New Issue
Block a user