把 news-crawler 抓到的新闻,变成结构化、可查询的情报:
- 分大类 —— 每篇新闻先归入唯一的一个一级大类(项目申报 / 行业政策 / 人才申报 / 企业资质申报 / 资金补贴 / 其他);
- 打标签 —— 再只在该大类允许的标签里做闭集多标签打标,模型不许自己造标签;
- 抽关键线索 —— 命中
project_application这类标签后,进入 schema 驱动的事实抽取,例如项目申报的申报主体、材料清单、截止时间、资助额度、申报渠道; - 出准备清单 —— 把抽到的事实按申报执行顺序排成可直接照做的清单(确认项目 → 核对资格 → 备材料 → 系统填报 → 截止提交),每条标注原文依据或「流程建议」;
- 落库 + 出接口 —— 结果存独立 SQLite,通过 HTTP API 查询,供后续业务系统消费;
- 推提醒 —— 新分析出项目申报类公告时写入站内通知,前端铃铛展示未读角标,点开直达详情。
它不抓网页、不解析正文、不碰爬虫的数据库。与 news-crawler 之间只有一条 HTTP 契约。
news-crawler (GPL-3.0) news-insight (MIT)
┌──────────────────────┐ GET /v1/articles ┌────────────────────────────┐
│ GNE 抽取 + SQLite │ ───────────────────► │ 一级分类(单选 6 类) │
│ FastAPI /v1 │ GET /v1/articles/{id}│ └─► tag(类内闭集多标签) │
│ /app/data/news.db │ │ └─► 标签命中 schema? │
│ │ │ └─► extract │
└──────────────────────┘ │ → insight.db(独立文件) │
│ → HTTP API :8020 │
└────────────────────────────┘
| 关注点 | news-crawler | news-insight |
|---|---|---|
| 职责 | 抓取、正文抽取、去重 | 语义标注、结构化抽取 |
| 依赖 | lxml / Playwright | LLM API |
| 写库 | news.db(单 worker 写入) |
insight.db(另一个进程,另一个文件) |
| 失败影响 | 抓不到新闻 | 分析结果缺失,可重跑 |
| 许可证 | GPL-3.0 | MIT |
两个进程写同一个 SQLite 文件会制造 database is locked,这也是本项目把结果放在独立库文件的原因。关联靠 article_id(上游 id)。
cp .env.example .env # 填 LLM_API_KEY;不填也能跑(降级为规则引擎)
docker compose up -d --build
curl http://localhost:8020/health
# 配了 INSIGHT_API_KEY 后,除 /health 与 /docs 外都要带 key
KEY=your-insight-key
curl -X POST "http://localhost:8020/v1/analyze?limit=10" -H "X-API-Key: $KEY"
# 长批次用异步作业:202 立即返回 job_id,轮询 /v1/jobs/{id}
curl -X POST "http://localhost:8020/v1/jobs" -H "X-API-Key: $KEY" -H "Content-Type: application/json" -d '{"limit":1000}'
curl "http://localhost:8020/v1/extractions?schema=project_application&due_before=2026-06-30" -H "X-API-Key: $KEY"几个默认值值得先知道:
- 端口只绑
127.0.0.1。POST /v1/analyze会花 LLM 额度,不该默认暴露给局域网。要让别的机器访问,设INSIGHT_BIND=0.0.0.0,并先配好INSIGHT_API_KEY。 - 数据落在命名卷
insight_data。bind mount 的./data由 docker daemon 以root:root创建,而容器以 uid 10001 运行,Linux 上首次启动会因 SQLite 无法读写而崩溃循环。想直接看insight.db:mkdir -p data && sudo chown 10001 data,再设INSIGHT_DATA_DIR=./data。 - API 默认 8 个 uvicorn worker(
INSIGHT_API_WORKERS,仅docker compose默认值;直接docker run仍为 1)。多 worker 用于把 20 并发混合查询的 p95 压到 3 秒内;分析批次通过DATA_DIR/.insight.analyze.lock跨进程串行,不会因为多 worker 重复消耗 LLM。
不启动爬虫也能验证:NEWS_SOURCE_MODE=demo 时使用 fixtures/articles.json 的内置新闻(含两篇申报公告、一篇降准、一篇融资)。
| 模式 | 行为 |
|---|---|
auto(默认) |
先请求爬虫 /v1;连不上则回退内置演示数据,并在 /v1/runs 里记录实际模式 |
live |
只走真实上游,失败直接报错(生产用) |
demo |
完全不联网(CI / 演示用) |
上游 news-crawler 先按站点配置抓一批进 SQLite,再让本服务读它的 /v1。真实站点配置只放本地 sources.local.json(已被 .gitignore 忽略),不要提交:
两个坑(一个已在代码里处理,一个靠配置约定):
- 有些站点的
<title>是站点名,真标题在正文h1里:配置article_title_xpath,推荐以/text()结尾(写元素节点也能兜底,但不要用string(),它只返回第一个字符); - 上游
/v1/articles的order只接受published_desc/published_asc/updated_desc,传别的会 422(本服务已固定用published_desc)。
跑通后:
curl -s -X POST -H "X-API-Key: $INSIGHT_API_KEY" \
"http://127.0.0.1:8020/v1/analyze?limit=10&force=true"
# {"mode":"live","scanned":10,"analyzed":10,"errors":0,"tag_engines":{"llm":10,"rules":0}}
curl -s -H "X-API-Key: $INSIGHT_API_KEY" "http://127.0.0.1:8020/v1/extractions?field=deadline"
# 申报截止日按区间右端取值:2025年11月25日17:00至2025年12月1日9:00 → 2025-12-01任何 OpenAI 兼容接口都行:
# DeepSeek
LLM_BASE_URL=https://api.deepseek.com
LLM_MODEL=deepseek-chat
# 本地 Ollama(注意容器内不能写 127.0.0.1)
LLM_BASE_URL=http://host.docker.internal:11434/v1
LLM_MODEL=qwen2.5:7b
LLM_API_KEY=ollama没有 LLM_API_KEY 时:打标降级为关键词规则(engine=rules),申报抽取降级为正则 + 日期归一(engine=rules,置信度 0.4~0.5)。这不是替代方案,只是让流水线在没凭证时也能端到端跑通、便于验证部署;生产请配置模型。
| 变量 | 默认 | 说明 |
|---|---|---|
ANALYZE_CONCURRENCY |
100 | 同时在途的文章数(1–200);每篇串行最多 6 次 LLM 调用(行业 1 + 语义相关性 1 + 分类 1 + 打标 1 + 抽取 1 + 清单 1) |
ANALYZE_WRITE_BATCH |
50 | 主线程每 N 篇提交一次 SQLite 事务 |
ANALYZE_MAX_PENDING_JOBS |
50 | 异步作业排队上限(queued + running),超过 POST /v1/jobs 返回 429 |
INSIGHT_API_WORKERS |
8(compose)/ 1(docker run) | API 的 uvicorn 进程数;只影响 HTTP 并发,不影响分析吞吐 |
NEWS_DETAIL_CONCURRENCY |
16 | 从上游补正文的并发请求数(1–64) |
LLM_MAX_CONCURRENCY |
100 | 供应商侧同时请求上限(1–200);超过时本地排队,用于避免瞬时打爆网关 |
RETENTION_DAYS |
90 | 分析结果保留天数(0–3650,0 = 不自动清理);启动时和每次成功分析后执行硬删除 |
清理也可手动触发:
docker compose run --rm insight python -m app prune --dry-run # 先看会删多少
docker compose run --rm insight python -m app prune --vacuum # 删除并回收磁盘| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /health |
健康检查(无需鉴权,不回显内网地址) |
| POST | /v1/auth/login、GET /v1/auth/me、POST /v1/auth/logout、POST /v1/auth/password |
本地账号:登录发数据库会话 Token(Authorization: Bearer)、查当前用户、登出、改密(需原密码,新密码≥8位且含大小写/数字/特殊字符) |
| GET/PATCH | /v1/me/profile、/v1/me/favorites、/v1/me/history、/v1/me/preferences |
个人中心:资料、收藏(增删查)、浏览历史(倒序/清空)、关注领域与推送偏好 |
| GET/POST/DELETE | /v1/me/search-history、/v1/me/search-history/{id}、/v1/me/search-history/{id}/click |
搜索历史:倒序列表(limit≤200、offset)、手工补录一次、删除单条、清空;{id}/click 把点击的文章回填到该条记录,供个性化画像加权。GET /v1/search 会自动留痕(登录用户,10 分钟内同词只更新时间与结果数),响应 meta.search_history_id 就是这次记录,前端点结果时带上它即可闭环归因 |
| GET/POST/PATCH/DELETE | /v1/admin/users、/v1/admin/users/{id}、/v1/admin/users/{id}/reset-password、/v1/admin/sites、/v1/admin/stats、/v1/admin/operation-logs |
管理员:用户/站点 CRUD、重置密码、统计看板、操作日志;登录管理员不能禁用/降级自己,服务级 API key 等同超级权限;admin/sites 代理 news-crawler 的 /v1/admin/sites(写前由爬虫备份配置,接口型源只能改非接口字段);admin/stats 的每日趋势、任务数与成功率均按近 N 天(本地日)统计 |
| POST | /v1/analyze?limit=10&force=false |
跑一批:拉取 → 打标 → 抽取 → 入库(同步兼容接口,limit 上限 50) |
| GET | /v1/search?q=&category=&industry=&source=&published_from=&published_to=&sort=&per_category=&include_body=&min_relevance= |
关键词检索:结果按 6 大类分组、类内按所选 sort 排序(排序全部在后端算完,前端只渲染);q 必填 1–100 字;登录用户的这次检索会被自动记入搜索历史,响应 meta.search_history_id 供点击归因 |
| POST | /v1/jobs |
提交异步分析作业,202 返回 {"code": 0, "msg": "ok", "data": {"id": ...}};body {"limit":1000,"force":false,"concurrency":100},limit 上限 10000;排队超过 ANALYZE_MAX_PENDING_JOBS 返回 429 |
| GET | /v1/jobs、/v1/jobs/{job_id} |
作业列表与状态(queued/running/succeeded/failed,含结果统计) |
| GET | /v1/articles?...&include_highlights=true |
include_highlights 默认 false:只有 ≥80 分的文章才附 highlights(要素摘要),列表默认不带该字段以节省带宽 |
| GET | /v1/articles?tag=project_application&limit=20&sort=relevance_desc |
已分析文章列表,可按标签、大类(category=funding_subsidy)、受控行业(industry=new_energy)或语义相关性阈值(min_relevance=0.5,0–1)过滤(AND 组合);category、industry 均可重复或逗号分隔;sort 支持 published_desc/asc、updated_desc、confidence_desc/asc、relevance_score_desc/asc(文章级语义评分,NULL 最后)与 relevance_desc/asc(用户画像相关度,只在前 2000 条候选内计算,offset+limit 超过时 422);每项含 relevance(0–1,画像分)、profile_reason(画像排序理由)与 relevance_score(0–1,语义分)、relevance_reason(语义评分依据) |
| GET | /v1/search?q=申报&category=project_application&industry=new_energy&per_category=20&include_body=false&source=&published_from=&published_to=&sort=relevance&min_relevance=0.5 |
关键词检索:结果按 6 大类分组、类内按所选 sort 排序(默认相关度降序;排序全部在后端算完,前端直接渲染;详见下节)。sort 取 relevance/published_desc/published_asc;category、industry 与 source 均可重复或逗号分隔;min_relevance(0–1)按文章级语义评分过滤,每项同时带 relevance(查询相关度)与 relevance_score(语义评分) |
| GET | /v1/industries |
受控行业词表(10 个 id/中文名/描述/关键词)+ 每个行业的文章数,供前端行业筛选与徽标 |
| GET | /v1/recommendations?limit=10 |
首页 Top10 推荐:登录用户按关注领域/收藏/浏览历史、内容质量与文章语义相关性混合打分,匿名用户按内容质量、新鲜度与语义相关性打分;meta.personalized 标识是否个性化 |
| GET | /v1/todos?limit=5 |
首页近期申报截止:取项目申报抽取结果中未过期的 deadline,按剩余天数升序;meta.total 为全部未过期项数量 |
| — | 项目申报 schema 字段类型 | focus_areas 是数组(专项扶持的行业领域/技术方向,逐项列出),在 /v1/extractions 与文章详情里以 JSON 文本返回;deadline_raw 是未归一化的原文表述,规范化日期在 deadline;funding_amount 是字符串,可能带「不超过 500 万元」这类限定语 |
| GET | /v1/articles/{article_id} |
单篇详情:标签 + 抽取结果 |
| GET | /v1/articles/{article_id}/checklist |
申报准备清单(按执行顺序排列,每项带 basis=excerpt|suggested 与 verified);article_not_found / checklist_not_found 两种 404 分别用业务码 40401 / 40402 区分 |
| POST | /v1/articles/{article_id}/checklist |
生成/复用申报清单:body {"force": false};默认幂等复用已有清单,force=true 重新生成。文章不存在 404 40401;非项目申报或缺少可用要素/正文 409 40902;已有分析/清单生成任务持有同一把全局锁时也返回 409,业务码为 40901 |
| GET | /v1/notifications?limit=20&unread_only=false |
站内消息提醒(新分析出的项目申报公告):data 为通知列表,meta.total 与列表同筛选(unread_only=true 时为未读总数),meta.unread 为当前登录用户的未读数(未登录只读模式为全库;不受 unread_only 影响);写已读必须登录或使用服务级 API key;同一篇文章只提醒一次 |
| POST | /v1/notifications/{notification_id}/read |
标记单条已读;不存在 404 |
| POST | /v1/notifications/read-all |
全部标记已读,data 返回 {"updated": N, "unread": 0} |
| GET | /v1/categories |
一级分类词表(id/中文名/描述/关键词/允许的标签)+ 每类文章数 |
| GET | /v1/categories/stats |
分类分布与平均置信度(不含分类功能上线前的历史行) |
| GET | /v1/sources |
按抓取站点聚合:source(空串表示未标注来源,前端显示「未标注来源」)、source_filter(筛选时回传的值:普通来源等于 source,未标注来源为 __unlabeled__)、count、avg_confidence(平均分类置信度)、latest_published_at(按真实时刻取最新发布时间);前端「发布单位」筛选应使用 source_filter,统计看板用 source 展示 |
| GET | /v1/tags |
标签词表 + 每个标签的命中数;带 category= 时只统计该大类下的命中 |
| GET | /v1/tags/stats |
标签分布与平均置信度 |
| GET | /v1/schemas |
已注册的抽取 schema |
| GET | /v1/extractions?schema=&field=&due_before= |
抽取结果平铺查询,due_before 按截止日期过滤,可与 field 同时使用(按文章过滤,不是按字段) |
| GET | /v1/runs |
运行记录(模式、扫描/分析/跳过/错误数) |
除 /health、/docs、/redoc、/openapi.json 外,所有 /v1/* 接口返回统一信封:
{"code": 0, "msg": "ok", "data": {...}, "meta": {...}}- 成功时
code恒为0、msg为ok;meta只在分页/统计类接口出现(total、limit、offset等)。 - 失败时
data为null,HTTP 状态码保留;参数校验失败额外带details数组。客户端应优先读code,msg可直接展示。
| 业务码 | 含义 |
|---|---|
| 40001 | 请求参数不合法(通用 400) |
| 40101 | 未登录或登录已过期 |
| 40301 | 当前账号无权限 |
| 40400 | 资源不存在(通用 404;未匹配路由也归此码) |
| 40501 | 请求方法不允许 |
| 40401 | 文章不存在 |
| 40402 | 申报清单不存在 |
| 40901 | 资源冲突(含分析/清单任务锁占用) |
| 40902 | 申报清单不适用(非项目申报或缺要素) |
| 42201 | 参数校验失败(带 details) |
| 42301 | 账号临时锁定 |
| 42901 | 请求/作业过多 |
| 50001 | 服务内部错误 |
| 50201 | 上游新闻 API 不可用 |
| 50301 | 服务暂不可用(只读库/库忙) |
CLI 也可:docker compose run --rm insight python -m app analyze --limit 10 --concurrency 100;清理历史数据:python -m app prune --dry-run、python -m app prune --vacuum。
min_relevance 只对已评分行生效:传 0 也会排除历史未评分(relevance_score IS NULL)的文章。
搜索界面由前端实现,本服务只提供检索层与 API。排序必须在后端算完:前端虽然能从
items[] 里读到标签置信度,但拿不到查询覆盖度(那要复算词表匹配),默认也拿不到正文,
无法复算出同一个分数,所以 groups[].items[] 的顺序就是最终顺序。
curl -H "X-API-Key: $KEY" "http://localhost:8020/v1/search?q=%E4%BA%BA%E6%89%8D%E7%94%B3%E6%8A%A5&per_category=10"{
"data": {
"query": "人才申报",
"matched_tags": ["talent_application", "project_application"],
"terms": ["人才", "申报"],
"total": 276,
"returned": 120,
"truncated": false,
"undated_excluded": 0,
"sort": "relevance",
"groups": [
{"category": "talent_application", "count": 20, "items": [
{"article_id": "...", "title": "...", "published_at": "...", "tags": [...],
"relevance": {"score": 0.765, "tag_confidence": 0.9, "title_hits": 1,
"body_hits": 3, "matched_tags": ["talent_application"],
"matched_terms": ["人才", "申报"]}}
]}
]
}
}排序口径:score = 0.70×标签项 + 0.20×标题命中 + 0.10×正文命中,三项都在 [0,1],
所以总分天然落在 [0,1],可直接当作前端的进度条或权重。
-
标签项 = 命中的闭集标签置信度 × 查询覆盖度(取最大值,不累加)。用户输入先映射到标签词表: 输入「光伏」命中
new_energy这个闭集标签,比字面匹配更贴近语义; -
覆盖度 = 命中片段占用户输入的比例,实行长度惩罚:整词命中 1.0,4 字查询里命中 2 字记 0.5。 一个标签可能同时命中多个候选形态(词表里大量短词是长词的前缀,如「人才」→「人才计划」), 实现会遍历该标签全部候选再取最大值 —— 命中第一个就停会让用户输入完整标签名时只拿到 0.5, 而且结果会随
keywords的书写顺序变化。 它不做语义消歧 —— 「人才申报」里「人才」和「申报」各覆盖一半、权重相同,真正把两类文章分开的是标签置信度与标题命中。 这一条有真实教训:最初以为覆盖度能区分这两类,实测才发现两类同为 0.5,project_application曾凭置信度以 0.893 压过talent_application的 0.879。 -
标题命中按条数计(1 条即饱和),正文命中 10 条饱和 —— 长文堆词不再自动占优; 计数按出现次数而不是「候选形态命中次数」:词表里短词常是长词前缀(「人才」⊂「人才申报」), 若每个形态各自
count,标题里一次「人才申报」会被记成 3 次;实现按权重降序(长形态优先)逐个计数, 命中过的位置记在一个bytearray里,后续形态只认同「未被占用的位置」的出现,保证一处文本只计一次, 同时短形态仍能命中长形态覆盖不到的文本(不用哨兵字符占位,正文真含 NUL 也不会伪造命中)。 同一形态的重叠出现(「aa」在「aaa」里)覆盖的是同一段字符,也只计一次。 记账用标记数组而不是区间列表:列表方案每命中一次都要跟全部已记区间比一遍, 6000 字正文里单字高频命中(「的」「年」)会退化到 O(n²),实测 0.87s;标记数组同一场景 0.004s。matched_terms只列实际贡献了命中的形态 —— 被长形态吃掉的短形态不列,否则排障时会误判它是加分来源; -
分数相同按发布时间降序、再按
article_id兜底,顺序不依赖 SQLite 的返回顺序(只按时间兜底时,同分同时间的几篇会退回行序,查询计划一变就抖); -
类顺序固定为
categories.json的声明顺序,但分组数不是固定的:除 6 大类外,历史未分类行会单独成组并排在最后,前端应按响应里的groups动态渲染,不要硬编码分段数; -
字面匹配用
instr()而不是LIKE:关键词是用户自由输入,%和_在LIKE里是通配符,搜「50%」会命中全库。 SQL 预筛与内存打分跑同一份归一代码:search._norm被注册成 SQL 函数py_norm,instr(py_norm(title), ?)与打分侧的_norm()是同一个函数,物理上不会分叉。这不是洁癖 —— SQLite 的lower()只折 ASCII(Ärger折完还是Ärger),而 Python 的casefold()折成ärger, 两层用不同实现时「用户输入与标题字面完全一致」也会返回空结果(真实触发词:ÖBB、Ärzte、Müller、École)。 空白同理:只对齐大小写不够,搜「gpt 模型」而标题写「GPT模型」时,SQL 拿带空格的原文去instr会直接空集。 代价是每行每列每个形态一次 Python 回调。实测规模统一为「候选集打满 2000 行、正文 6000 字」 (本机 min-of-3,不同机器可能差 2–3×):场景( instr(py_norm(title), ?) OR instr(py_norm(body), ?))预筛 全链路 标题命中(第一个条件即为真,短路掉 body) 约 0.05s 约 0.5s 仅正文命中(标题不含,必须算完 body 才为真) 约 0.55s 约 2.0s 全不命中(候选为空、不打分) 约 0.52s 约 0.5s 全不命中、3 个形态(每行算 3×2 列) 约 1.5s 同上 历史行 body IS NULL、全不命中约 0.003s 同上 只有「标题命中」才便宜:
OR在首个条件为真时短路,省掉body的 6000 字归一。 标题不含查询词时(真实新闻里用户查的行业词、细分词大多只在正文出现),body的py_norm每行都要付,成本与「全不命中」同档——这是最常见路径,别按 0.05s 估。 纯 SQLinstr对照(不命中全扫)约 0.04s,即py_norm带来一个数量级预筛开销, 这是「两侧归一必须同源」的代价。逐行归一 +score_article是另一块大头 (仅正文命中且候选打满时约 1.5s)。 泛词会打满候选集,超时请按秒级设(最坏约 2–3s,建议 10s),不要按「几百毫秒」估。
为什么正文要落库:只靠标题和标签,用户搜一个正文里才出现的词(如某个细分行业)会全军覆没。
正文在 analyzed_articles.body,只有上游详情页真取到文本时才覆盖(COALESCE(NULLIF(excluded.body,''), body)),
避免某次详情抖动把历史正文写成 NULL 让检索静默丢文章。检索默认不返回正文,include_body=true 才带。
历史行(本功能上线前分析的)body 为 NULL,需要回填一次(只搬文本、不重跑模型、不消耗 token):
python -m app backfill-bodies --limit 500 --batch 50NEWS_SOURCE_MODE=demo 时会直接拒绝(demo 模式不访问网络,而回填必须逐个请求上游详情接口);候选按「最新优先 + article_id 兜底」取;每批先把正文全部取回,再开写事务统一写库,网络请求期间不持有未提交事务。参数约束:--batch 必须 ≥ 1,--limit 不能为负(SQLite 把 LIMIT -1 当不限,不拦会回填整库),--limit 0 等于空跑(不发请求、不写库)。
回填只处理 body IS NULL OR body = '' 或 body_html IS NULL OR body_html = '' 的行(已有一侧时只补另一侧,不覆盖已有内容),可重复执行;单篇失败不中断整批,返回
{"filled", "html_filled", "failed", "skipped", "remaining"}。limit 限制的是写入篇数,扫描预算为
5×limit(_SCAN_FACTOR),所以少量死链不会钉死小 --limit 的窗口。
但它不是无限的:连续 5×limit 篇都不可回填时会退回「每轮重试同一批」的行为
(实测 --limit 1 时,4 篇连续死链仍能摸到更早的文章,5 篇就摸不到)。遇到这种情况调大
--limit(预算随之放大),或先手工处理掉这批死链。
另注意 remaining 不一定能归零:上游确实没有正文的行(skipped)不会被写占位符、下一轮还会再试。
但 remaining 稳定不能单独作为停止依据:它稳定有两种成因,含义完全不同——
- 真的只剩不可回填的行(
skipped,上游确实没正文):可以停; - 卡在扫描预算上:
--limit 1时若前 5 篇都不可回填,每轮都在重试这 5 篇,remaining同样稳定,但后面仍有可回填的文章,此时停下来等于漏回填。
区分办法要看是否扫描覆盖了全部剩余候选,而不是只看 filled 有没有变。日志「已回填 X/Y(候选 Z)」
里的 Z = 5×limit 就是本轮实际扫过的候选数。判据:
Z < remaining:这一轮根本没扫完,filled=0什么都证明不了,必须调大--limit(Z随之放大) 直到Z ≥ remaining再判断;Z ≥ remaining且filled=0:只说明扫描覆盖完成、这一轮扫过的行都没写进正文,不等于回填完成。 还要看failed:failed > 0(上游错误/超时)说明是临时故障,稍后重跑即可,不能当完成;failed == 0且filled == 0才是「这些行上游确实没有正文」(skipped),此时可以停。
只看「调大 --limit 后 filled 是否为 0」会误判。实测(死链在前、唯一可回填的行在最旧处):
| 场景 | --limit 1(Z=5) |
--limit 50(Z=250) |
|---|---|---|
| 5 篇死链 + 1 篇可回填 | filled=0 remaining=6 |
filled=1 remaining=5 |
| 250 篇死链 + 1 篇可回填 | filled=0 remaining=251 |
filled=0 remaining=251(Z=250 < 251,仍没扫到) |
| 3 篇死链、没有别的行 | filled=1 remaining=3 |
filled=1 remaining=3 |
第二行就是反例:把 --limit 从 1 调到 50 后 filled 依然为 0,但回填并没有完成——预算 250 恰好被
250 篇死链吃满,最旧那篇可回填的行仍没进入候选集。所以 filled=0 只有在 Z ≥ remaining 时才可信。
这个上限是结构性的(预算有限),不想被卡住就继续调大 --limit,或先手工清掉这批死链。
注意 skipped 与 failed 的区别很重要,它决定「要不要重跑」:
skipped:上游明确表示这篇没正文可给——请求成功但正文为空,或返回 404/410(文章已删除/不存在)。 重跑也不会有,属于常态;failed:请求本身出错(超时、5xx、连接失败、鉴权失败等),是临时故障,稍后重跑可能就补上了。
上游临时不可用会让整批都进 failed,这时 remaining 一篇没少也不奇怪——该重跑,而不是把结果当成
「这些文章永远没有正文」。反过来,死链持续返回 404 时会计入 skipped 而不是 failed,所以「failed == 0
就可以停」不会被几个死链永久卡住。
行业分类是闭集单选,历史行可用 python -m app backfill-industries --limit 500 单独补齐(只写 industry 三列,不重跑标签/抽取/清单),可重复执行。/v1/industries 的 article_count 来自该列统计。
语义相关性评分由分析流水线在分类后独立调用一次 LLM 得出(relevance_score/relevance_engine/relevance_reason 三列,0–1;无 LLM 时降级规则引擎,规则分支会使用分类先验)。历史行可用 python -m app backfill-relevance --limit 500 补齐,只写这三列,不重跑标签/抽取/清单,可重复执行;只补 relevance_score IS NULL 的行,已有分不会被覆盖。该分数同时参与 /v1/recommendations 的内容质量分与画像分(各占 20%),并支持 /v1/articles 与 /v1/search 的 min_relevance 过滤。
已知取舍:
- 检索是字面 + 闭集标签的混合,没有分词也没有同义词扩展,「补贴」与「资助」靠词表里的
keywords打通; - 候选集上限 2000 行(
search_candidates(limit=2000)),命中极多的泛词(如「的」)会被截断,所以total是候选集内命中的行数,不是全库真实命中数; 截断前按与sort一致的时间顺序取候选:sort=published_asc保留最早的 2000 行(按真实时刻ASC, article_id ASC,两列皆空的记录排在最后,不占早段名额), 其余排序(relevance/published_desc)保留最新的 2000 行(按真实时刻DESC, article_id DESC)—— 所以升序查不会丢掉最老的文章,但最新的命中可能搜不到;降序查则相反,极老的命中可能搜不到; 候选集打满上限时服务端会记一条 WARNING(带 terms / tag_ids 数量),便于判断是不是关键词太泛导致结果不完整; 判断方式是「多取一行看是否还有更多」,所以库里恰好 2000 行(全取完)不会误报; category=不做闭集校验,未知类返回空结果而不是 422(同/v1/articles?category=);- 分类功能上线前分析的历史行
category为NULL(≠other),它们会单独成组,category_order之外排在最后。
入站支持两种凭据:用户登录后的数据库会话 Authorization: Bearer <token>(/v1/auth/login 获取,按 users/sessions 校验、可撤销、过期失效),或服务级 X-API-Key: <INSIGHT_API_KEY>。设置 INSIGHT_API_KEY 后,除 /health、/docs、/openapi.json 外都要求其中一种;INSIGHT_REQUIRE_AUTH=1 表示强制(未配置 key 时业务请求一律 401)。无鉴权部署下匿名只能读 /v1/notifications,写已读必须登录或服务 key。注意 NEWS_API_KEY 是出站凭证(访问爬虫),与本服务入站鉴权无关。
/v1/analyze 是同步兼容接口,limit 上限 50;分析作业全局串行,同步接口遇到已有批次会立刻返回 409,异步作业遇到分析锁被占用会直接标 failed(不会并行烧 token),排队作业总数超过 ANALYZE_MAX_PENDING_JOBS 时 POST /v1/jobs 返回 429。长批次请用 POST /v1/jobs + 轮询;单篇内部依次「行业 → 语义相关性 → 分大类 → 打标 → 抽取 → 清单」,最多 6 次串行 LLM 调用,整体吞吐由 ANALYZE_CONCURRENCY(默认 100)决定。
编辑 app/vocab/categories.json,往 categories 里加一条:
{
"id": "funding_subsidy",
"name": "资金补贴",
"description": "财政资金、补贴、奖补、贴息、资助等资金支持政策与兑现通知。",
"keywords": ["补贴", "补助", "奖补", "专项资金", "贴息"],
"tags": ["subsidy", "funding", "policy_release"]
}- 一级分类是单选:每篇只落一个
category,跨类内容取最贴近的一类; tags是该类允许的二级标签白名单,二级打标只能在这个集合里选,这是防跨类污染的护栏(一篇人才通知不会被挂上资金补贴标签);other是兜底类:keywords与tags留空。归到other的文章不做语义打标(省一次模型调用),只用规则引擎按group=domain保住行业标签(金融/科技/农业等),所以「央行降准」这类非 5 大类新闻仍能按finance查到;- 并列时的归属由
categories.json的声明顺序决定(先声明者胜),调整顺序等于调整并列归属,属于行为变更;比较用的是原始关键词分,不是封顶到 0.95 的confidence,所以高分先命中的类不会被后面的低分翻盘; - 大类与标签是两级关系:
/v1/articles?category=查大类,?tag=查二级标签,两者可组合; category参数不做闭集校验:传一个不存在的类名返回 200 空集(而不是 422),沿用标签参数的一贯行为; 空串的语义在三个接口上有意不同,调用方不要混用:/v1/articles?category=:空串按「未知类」处理(a.category = '')→ 200 空集;/v1/search?category=:空串归一为「不传」(cleaned or None)。若透传,SQL 会变成COALESCE(category,'') IN ('')只命中「分类功能上线前」的历史行;若只在 Python 侧过滤掉空串, 剩下的空列表又会被当成「筛完没结果」直接返回空集。两条路都会让用户只是清空了筛选框却看不到结果;/v1/tags?category=:词表照旧返回,计数按该类统计(空串下计数全 0);
industry的空串语义:/v1/articles?industry=按空集处理返回 0 行(不再命中未分类行业,也无法用空串筛「未分类」);/v1/search?industry=归一为「不传」。categories.json里少了兜底类other时不会启动失败,但会记一条 WARNING:模型答出表外大类就没有去处,那篇文章的二级打标与抽取都会被跳过。
编辑 app/vocab/tags.json,往 tags 里加一条:{ "id": "tender", "name": "招标采购", "group": "event", "keywords": ["招标","中标"] }。
id是唯一契约,落库与查询都用它,改名不要改 id;keywords只在无 LLM 的规则降级时使用,模型看的是id + name + group + keywords的完整描述;- 几十个标签全部塞进单次 prompt 完全放得下,不需要两阶段召回。词表涨到几百条再考虑先粗筛候选;
- 新加的标签要在
categories.json里被至少一个类引用,否则任何文章都打不到它(只有group=domain且文章落到other时才可能命中); group决定二级范围:domain是行业维度,event/policy是业务维度。归到other的文章只保留domain组,业务标签必须由大类白名单授权。
在 app/vocab/schemas/ 下加 JSON:
{
"schema_id": "tender_notice",
"name": "招标公告关键线索",
"trigger_tags": ["tender"],
"fields": [
{ "name": "tenderer", "type": "string", "description": "招标人" },
{ "name": "bid_deadline", "type": "date", "description": "投标截止时间" }
]
}trigger_tags 就是路由:标签命中它才会跑这个抽取器,避免对无关新闻付 token。
- 先分大类,再在类内闭集打标。 一级分类把标签空间切成互不重叠的几块:模型先选唯一一类,第二级只能看到该类允许的标签。好处是跨类污染从提示词层面就消失了(人才通知看不到资金补贴标签),代价是类别边界要人工维护;归到兜底类
other的文章跳过第二次模型调用,只用规则引擎保住group=domain的行业标签,避免「不属于 5 大类」等于「一无所知」。 - 闭集打标,标签外一律丢弃。 放任模型自造标签,会把
Artificial Intelligence和AI变成两个标签——这是 karakeep issue #111 记录的原始问题,#529 的解法就是「只允许使用用户已建的标签」,并已合入。本项目在tagging.py里做了同样的守卫(词表外丢弃 + 告警)。标签集合与「标签→schema 路由」借鉴 autolabel 的闭集思路。 - 打标与抽取分离。 打标的输出空间是闭合的(必须是词表内 id),抽取的输出空间是固定的(必须是 schema 内字段);打标漏标只是少一条线索,抽取编造会污染下游。因此两者用的是不同 prompt、不同校验:标签必须
in词表,抽取值必须能在原文定位。 - 相对时间以发布时间为基准。 「自发布之日起30日内」「本月底」如果用抓取时间换算,会随重跑静默漂移。抽取提示词里显式传入
published_at_utc(缺失时回退published_at),normalize_deadline()按下这个基准推算。 - 缺失字段返回 null,值要能在原文定位。
_locate()做空白无关的子串校验,定位不到的值保留但标verified=false,供人工复核,而不是静默采信。模型给出的日期还会用原文重算一遍,与原文对不上就降级可信度;规则引擎(无 LLM 降级)产出的一切恒为verified=false——正则只证明文本出现过,不证明语义正确(「3月1日至4月20日」取左端就是活生生的反例)。 - 结果独立成库。 见上文对照表。
- 清单是派生视图,不是新事实。 清单项要么引用已抽取的事实(
basis="excerpt":原文片段必须能在正文定位,且text里的日期/金额/电话等事实 token 必须被该片段支持,否则丢弃),要么显式标成suggested(盖章、留存回执这类流程建议,禁止出现任何数字)。规则引擎生成的项沿用抽取行的verified标记(通常为false),不会冒充已核验事实。它单独存在article_checklists,重新生成不重写标签/抽取表;已分析但缺清单的文章会在下次运行自动补生成。 - 单篇失败不拖垮批次,但「没拿到正文」不算成功。 单篇异常计入
errors并继续,运行统计落到runs表。详情接口没取到正文的文章只拿标题打标会把「确无截止日」永久定档,所以这类文章不入库、计入errors,下次运行自然重试;save_analysis整体在一个事务里,中途失败立即回滚,不会留下「有主行、无标签」的脏状态。
| 表 | 内容 |
|---|---|
analyzed_articles |
已分析文章元数据(article_id 主键,与上游对齐),含一级分类 category 与 category_confidence/category_engine(NULL = 分类功能上线前分析的历史行,与 other 不是一回事)、受控行业 industry/industry_confidence/industry_engine、文章级语义评分 relevance_score/relevance_engine/relevance_reason(relevance_score 为 NULL = 尚未评分,与 0 分不同);title_norm/body_norm 是检索用归一化副本;body 存正文副本供检索,body_html 存清洗后的正文 HTML 供详情页富文本渲染(两者都可能为 NULL,需 backfill-bodies 回填,已有一侧不会互相覆盖) |
article_tags |
(article_id, tag) 主键,含置信度、原文依据、引擎 |
extractions |
(article_id, schema_id, field) 主键,含值、原文片段、置信度、是否定位成功 |
article_checklists |
article_id 主键,清单项 JSON(text/basis/source_text)、生成引擎与时间 |
notifications |
站内消息提醒:article_id 唯一(同一篇只提醒一次),kind、标题快照、消息、created_at(带 Z 的 UTC);个人已读状态在 notification_reads(notification_id + user_id 主键) |
runs |
每次批处理的统计 |
analysis_jobs |
异步分析作业状态与结果(queued/running/succeeded/failed) |
# 宿主机(dev 依赖已固定 ruff/mypy/pyyaml 版本,与 CI 一致)
pip install -e ".[dev]"
ruff check .
mypy
python tools/yaml_lint.py # 与 CI 的 yaml lint job 跑同一份脚本
pytest -q
# 或在镜像里跑(tests/ 与 tools/ 不进镜像,必须挂载;镜像也不带 pytest)
docker compose run --rm -v "$(pwd)/tests:/app/tests" -v "$(pwd)/tools:/app/tools" \
--entrypoint sh insight -c "pip install --user -q pytest pyyaml && python -m pytest tests -q".github/workflows/ci.yml 在 PR 与 master 推送时跑三个 job,全部为合并前必须通过的检查:
| job | 内容 |
|---|---|
python 3.10–3.14 |
compileall + ruff + mypy(仅 3.12)+ pytest,五个版本矩阵 |
yaml lint |
用 tools/yaml_lint.py 解析仓库内所有 YAML:拒绝重复映射键、支持多文档、不误杀 << 合并键 |
docker build + container smoke |
构建镜像、容器内跑 pytest、启动容器请求 /health |
配合仓库规则集 pr-protection(master):禁止删除分支与强推、要求上述 7 个 GitHub Actions 检查全绿、要求所有 review thread 已解决、CodeRabbit 机器人为必过检查。required_approving_review_count 为 0——GitHub 不允许仓库所有者批准自己的 PR,若设为 1 会让单人维护的 PR 永久卡住。
规则集保留了 bypass_actors(RepositoryRole / always),单人维护时只有这一条路可走。允许 bypass 的情形仅限:CodeRabbit 侧故障或配额耗尽导致 required check 永久 pending,且此时必须人工确认本地 ruff check .、mypy、pytest -q 与 docker build 全部通过后再合入。GitHub Actions 的 7 个检查不允许 bypass——它们是本地可复现的。
覆盖:日期归一(绝对/相对/跨年/月底/无基准)、闭集守卫(词表外丢弃、去重、max_tags)、一级分类(词表外大类回落兜底、置信度夹取、并列按声明顺序、未带 categories.json 的旧部署退回单级打标、类别引用标签必须存在)、类内打标范围(跨类标签打不进、兜底类只保留 domain 组)、demo 模式端到端(分类 + 打标 + 申报抽取 + due_before 查询)、申报准备清单(规则顺序、excerpt 原文定位校验、「LLM 不可用 → 规则」降级、清单端点 404/200)、分类与标签端点、重跑幂等。
-
q至少要有 1 个非空白字符:空串与纯空白都返回 422,避免同一件事两种响应码; -
抽取质量取决于模型与 prompt,本项目只保证「不越界」(不造标签、不造字段、值可定位),不保证召回;
-
相对截止时间只覆盖常见表述(
N日内/N个工作日/本月底),「公示结束后5个工作日」这类链式表述仍会漏; -
分析作业跨进程全局串行(同步接口与异步 job 共用
DATA_DIR/.insight.analyze.lock文件锁),长批次请用POST /v1/jobs;API 多 worker 只提升查询并发,分析仍单批次执行,多副本部署仍需外部队列; -
清单生成按篇多一次 LLM 调用(正文按
EXTRACT_BODY_CHARS截断),每篇最多 6 次 LLM 请求(受控行业 1 + 语义相关性 1 + 分大类 1 + 类内打标 1 + 抽取 1 + 清单 1;归到 other 时会做行业、语义评分与分类 3 次,跳过打标/抽取/清单);实际吞吐取决于供应商并发与限流,ANALYZE_CONCURRENCY只是本地上限,LLM_MAX_CONCURRENCY另外限制真正同时在途的供应商请求;遇到 429/5xx 会优先按Retry-After、否则指数退避并加抖动重试; -
RETENTION_DAYS默认 90:启动时和每次成功分析后自动硬删除更早的analyzed_articles/article_tags/extractions/article_checklists/notifications、runs以及已完成的analysis_jobs,不保留归档; -
一级分类的边界靠
categories.json的description与keywords人工维护:规则引擎按关键词计分,遇到「专项资金申报通知」这种同时命中资金补贴与项目申报的文章,会归到分数更高的那一类,另一类的二级标签随之拿不到(目前funding_subsidy的白名单不含project_application,这类文章不会触发申报抽取);需要时给该类补project_application标签即可; -
分类按「保留式」写入:重跑时没做分类(例如临时移走
categories.json、回退到旧版本)只会更新标签,不会清空已有分类;但此时标签是按全词表打的,可能出现分类与标签不同源的行(category=project_application却带ipo标签)。恢复词表后再跑一次即回到类内一致; -
分类功能上线前已分析的历史行
category为NULL:/v1/categories里统计不到、?category=也筛不出来,需要analyze --force重跑才会补上分类;这与归到other是不同的状态; -
检索是字面匹配 + 闭集标签的混合,不做分词、不做同义词扩展(「补贴/资助」靠词表
keywords打通),也不做拼音或错别字容忍;候选集上限 2000 行,命中面极广的泛词会被截断; -
检索排序是人工设定的权重(标签 0.70 / 标题 0.20 / 正文 0.10),不是学习出来的排序模型;它保证「标签命中优先、长文不占优、结果稳定可复现」,不保证符合每个人的直觉。要调权重改
app/search.py顶部常量并补用例; -
正文副本(
body)使库体积约增加一倍多,且会随保留期一起被删除;RETENTION_DAYS之后连同正文一起消失,检索结果也随之减少; -
演示数据与规则引擎只用于跑通链路,不作为效果基线。
架构取舍来自这几个项目的公开实践:karakeep(闭集标签)、autolabel(LLM 标注 + 校验)、TrendRadar(新闻流水线与推送形态)、GeneralNewsExtractor(上游正文抽取)。
MIT,见 LICENSE。注意上游 news-crawler 为 GPL-3.0,本项目通过 HTTP 调用其 API,不链接其代码。