220 lines
4.8 KiB
Markdown
220 lines
4.8 KiB
Markdown
# 采集规则使用文档（含 AI 工具 Demo）
|
||
|
||
本文面向当前项目内置采集器，目标是让你从 0 到 1 跑通一条规则，并把数据入库到站点模块（如 `AI 工具`、`AI 模型`）。
|
||
|
||
## 1. 功能概览
|
||
|
||
当前支持：
|
||
|
||
- 后台配置采集规则（入口 URL、定时、抓取参数、Extractor JSON、AI 配置）。
|
||
- 定时执行（Laravel Scheduler）与手动触发。
|
||
- 运行日志、失败明细、告警中心。
|
||
- 目标模块入库：`AI 工具`、`AI 模型`。
|
||
- 三种抽取模式：
|
||
- `xpath`：只用 XPath 规则。
|
||
- `ai`：只用 AI 抽取结构化数据。
|
||
- `hybrid`：XPath + AI 合并（XPath 优先）。
|
||
- 页面预览 + 点选元素生成 XPath。
|
||
- AI 一键生成 Extractor 规则（从页面内容推断）。
|
||
|
||
## 2. 前置准备
|
||
|
||
### 2.1 迁移数据库
|
||
|
||
```bash
|
||
php artisan migrate --force
|
||
```
|
||
|
||
确保存在以下表：
|
||
|
||
- `crawl_rules`
|
||
- `crawl_runs`
|
||
- `crawl_run_items`
|
||
- `crawl_alerts`
|
||
|
||
### 2.2 启动队列与调度
|
||
|
||
采集任务通过队列执行，建议至少一个 worker：
|
||
|
||
```bash
|
||
php artisan queue:work
|
||
```
|
||
|
||
系统 cron 每分钟执行一次调度器：
|
||
|
||
```cron
|
||
* * * * * cd /path/to/ai-web && php artisan schedule:run >> /dev/null 2>&1
|
||
```
|
||
|
||
### 2.3 AI 配置（用于 AI 抽取/AI 规则生成）
|
||
|
||
在 `.env` 中配置：
|
||
|
||
```env
|
||
CRAWLER_AI_ENDPOINT=
|
||
CRAWLER_AI_KEY=
|
||
CRAWLER_AI_MODEL=gpt-4o-mini
|
||
```
|
||
|
||
## 3. 后台入口
|
||
|
||
- 采集规则：`/admin/crawlers`
|
||
- 运行记录：`/admin/crawl-runs`
|
||
- 告警中心：`/admin/crawl-alerts`
|
||
|
||
## 4. AI 工具 Demo（推荐先跑）
|
||
|
||
### 4.1 新建规则
|
||
|
||
在 `采集规则` 页面点击“新建采集规则”：
|
||
|
||
- 规则名称：`AI工具-Demo`
|
||
- 目标模块：`AI 工具`
|
||
- 发布策略：`草稿待审核`
|
||
- Cron：`0 */6 * * *`
|
||
- 时区：`Asia/Shanghai`
|
||
- 最大页面数：`30`
|
||
- 启用规则：勾选
|
||
- 入口 URL：
|
||
|
||
```text
|
||
https://your-demo-site.com/ai-tools
|
||
```
|
||
|
||
### 4.2 选择抽取模式
|
||
|
||
可按场景选：
|
||
|
||
- 页面结构稳定：`xpath`
|
||
- 页面结构变化大：`ai`
|
||
- 追求稳定 + 覆盖：`hybrid`
|
||
|
||
### 4.3 配置 Extractor JSON（XPath 模式/Hybrid 建议）
|
||
|
||
可直接用：
|
||
|
||
```json
|
||
{
|
||
"list_link_xpath": "//a[contains(@class,'tool-link')]/@href",
|
||
"fields": {
|
||
"name": "//h1/text()",
|
||
"summary": "//meta[@name='description']/@content",
|
||
"official_url": "//a[contains(@class,'visit-official')]/@href",
|
||
"logo_url": "//meta[@property='og:image']/@content",
|
||
"pricing_type": "//span[@data-field='pricing']/text()",
|
||
"platform": "//span[@data-field='platform']/text()",
|
||
"language": "//span[@data-field='language']/text()",
|
||
"description": "//article[contains(@class,'tool-content')]//text()"
|
||
}
|
||
}
|
||
```
|
||
|
||
或使用示例文件：`docs/examples/ai-tools-extractor.json`
|
||
|
||
### 4.4 用“页面预览 + 选元素”快速生成 XPath
|
||
|
||
1. 在表单里输入 `预览 URL`。
|
||
2. 点击“加载预览”。
|
||
3. 在预览 iframe 点击目标元素，页面会显示当前 XPath。
|
||
4. 填写“写入字段”（如 `name` / `summary` / `list_link_xpath`）。
|
||
5. 点击“写入 Extractor JSON”。
|
||
|
||
### 4.5 用 AI 一键生成规则
|
||
|
||
1. 填写（可选）AI 提示词、模型、温度等。
|
||
2. 点击“AI 生成抽取规则并合并到 Extractor JSON”。
|
||
3. 检查合并后的 JSON 并微调。
|
||
|
||
### 4.6 Mapping / Dedupe（可选）
|
||
|
||
`Mapping JSON` 示例：`docs/examples/ai-tools-mapping.json`
|
||
|
||
```json
|
||
{
|
||
"name": "title",
|
||
"summary": "desc",
|
||
"official_url": "website"
|
||
}
|
||
```
|
||
|
||
`Dedupe JSON` 当前可先留空对象：`docs/examples/ai-tools-dedupe.json`
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
## 5. 如何执行
|
||
|
||
### 5.1 后台手动执行
|
||
|
||
在规则列表点击“立即执行”。
|
||
|
||
### 5.2 命令行执行
|
||
|
||
执行指定规则：
|
||
|
||
```bash
|
||
php artisan crawler:run 规则ID --sync
|
||
```
|
||
|
||
按 cron 执行到期规则：
|
||
|
||
```bash
|
||
php artisan crawler:run
|
||
```
|
||
|
||
忽略 cron 执行全部启用规则：
|
||
|
||
```bash
|
||
php artisan crawler:run --all
|
||
```
|
||
|
||
重试某次运行：
|
||
|
||
```bash
|
||
php artisan crawler:retry-failed 运行ID
|
||
```
|
||
|
||
## 6. 验证结果
|
||
|
||
1. 打开 `/admin/crawl-runs` 查看该次运行状态。
|
||
2. 进入运行详情看 `list/detail/extract/upsert` 各阶段结果。
|
||
3. 到目标模块（如 AI 工具）确认有新数据，状态应为 `draft`。
|
||
|
||
## 7. 常见问题
|
||
|
||
### 7.1 `Table '...crawl_rules' doesn't exist`
|
||
|
||
未执行迁移：
|
||
|
||
```bash
|
||
php artisan migrate --force
|
||
```
|
||
|
||
### 7.2 保存时报 `validation.json` 或 JSON 格式错误
|
||
|
||
检查以下字段是否是合法 JSON：
|
||
|
||
- `Extractor JSON`
|
||
- `Mapping JSON`
|
||
- `Headers JSON`
|
||
- `Cookies JSON`
|
||
|
||
### 7.3 运行成功但没入库
|
||
|
||
通常是缺少必填字段：
|
||
|
||
- AI 工具至少需 `name`、`summary`
|
||
- AI 模型至少需 `name`、`summary`、`modality`、`deployment_mode`
|
||
|
||
去运行详情看 `extract` 阶段的 `Missing required fields`。
|
||
|
||
### 7.4 预览或 AI 规则生成失败
|
||
|
||
常见原因：
|
||
|
||
- URL 不可访问
|
||
- URL 命中安全限制（内网/保留地址）
|
||
- AI 配置缺失（`CRAWLER_AI_ENDPOINT` / `CRAWLER_AI_KEY`）
|
||
|