售后知识助手(一):一个 Postgres 干三份活
给一家设备厂部署软件,最先遇到的往往不是技术问题,而是 IT 部门的一句话:「你们要装几个东西?」
售后部门分到的通常是一台虚拟机,有时候连 Docker 都要单独申请。你报上去 PostgreSQL、Redis、Milvus、Elasticsearch、Celery,对方的第一反应不是「架构真先进」,而是「这些出了问题谁来管」。
所以这个项目在架构上只做了一个决定:能不加的组件都不加。剩下的篇幅,都是在讲这个决定的代价和收益。
你在这里
这一篇不讲某一站,讲的是整张全景图的地基:模块怎么分层、数据放在哪、项目按什么顺序搭起来。
一、两层:机制放 modules,词汇放 app
代码只有两层:
app/ 行业装配层:路由、配置、提示词、RAG 编排、品牌
modules/ 公共机制:llm · tasks · doc_ingest · retrieval · evidence · citation · identity规矩有三条,写在 modules/__init__.py 唯一的那行注释里:
"""未来公共件(机制公共、词汇行业;app → modules 单向依赖,模块之间互不 import)。"""依赖单向:app 可以 import modules,反过来不行。模块之间互不 import:retrieval 不认识 evidence,evidence 也不认识 citation。机制公共、词汇行业:怎么做是机制,叫什么、说什么是词汇。
最后一条最容易说、最难守,举几个具体的例子:
| 东西 | 归谁 | 为什么 |
|---|---|---|
| RRF 融合、BM25 公式 | modules | 换成空调售后也是这么算 |
| 证据门的三条指标 | modules | 判断逻辑与行业无关 |
| 证据门的阈值 | app 注入 | 不同语料、不同模型,阈值不一样 |
| 「带电检修」「短接安全回路」这张安全词表 | app | 换成医疗器械就是另一张表 |
| 证据编号前缀:手册 M、工单 T、FAQ F | app | 别的行业可能根本没有「工单」 |
| 「之前」「那台」这类口语停用词 | app | 是售后工程师的说话习惯 |
| 系统提示词、拒答话术、安全卡文案 | app | 都是对这个行业的用户说的话 |
模块连环境变量都不读。检索要用的参数打包成一个 dataclass,由 app 从配置里读出来再传进去:
@dataclass
class RetrievalSettings:
"""检索参数(由 app 层从配置注入,模块不读环境变量)。"""
top_k_dense: int = 20
top_k_bm25: int = 20
final_top_n: int = 6
rrf_k: int = DEFAULT_RRF_K
min_filtered_hits: int = 3
reranker_provider: str = "none"
rerank_candidates: int = 30模块之间怎么协作
模块之间不能 import,可它们总得配合。答案是结构化类型。第 4 篇提过,证据门要读检索结果的两个字段,就用 Protocol 声明「我只要有 content 和 dense_score 的对象」,检索结果天然满足。检索管线对 Embedding 客户端和重排客户端也是同样的写法:
class Embedder(Protocol):
def embed_one(self, text: str) -> list[float]: ...
class Reranker(Protocol):
def rerank(self, query: str, documents: list[str]): ...任务队列更进一步,用的是注册制。modules/tasks 只管领任务、写心跳、失败重试,至于「解析一份 PDF」「重建索引」这些具体任务,由 app 把处理函数注册进去:
# modules/tasks/worker.py:只认识「一个处理函数」长什么样
Handler = Callable[[queue.ClaimedJob, psycopg.Connection], None]
# app/worker.py:具体有哪些任务类型,由 app 决定
worker = TaskWorker(
connect=connect,
handlers=build_handlers(settings),
...
)这条纪律换来了什么
最直接的收益是换行业不动 modules。把演示语料换成空调售后的资料,在后台改掉欢迎语、示例问题、安全词表和品牌,app/domain.py 里的提示词改一改,七个模块一行不用碰。
第二个收益是每个模块能单独测。检索的单元测试不需要真的 Embedding 服务,塞一个返回固定向量的假对象就行,因为管线只认 Embedder 这个协议。仓库里 150 个测试函数,没有本地 PostgreSQL 时,需要数据库的用例自动跳过,其余照样跑。
代价也有:写起来更啰嗦。同一个概念(比如一个检索命中的切片)会在不同模块里以不同的「形状」出现,每次跨模块都得想清楚对方需要哪几个字段。我觉得这个代价值得。它逼着你在每个模块边界上回答「这里到底需要知道什么」,而不是顺手 import 一个大对象,最后谁都离不开谁。
二、一个 PostgreSQL 干三份活
整个系统只有一个有状态的组件:PostgreSQL,用的是 pgvector/pgvector:pg16 官方镜像。它同时承担三份工作。
第一份:业务库。 账号、知识源、问答日志、知识缺口、知识沉淀、运行时配置,11 个迁移文件,按编号顺序执行,应用容器启动时自动跑。
第二份:向量库。 切片表里直接有一列 1024 维的向量,建一个 HNSW 索引:
create table if not exists chunks (
id bigserial primary key,
document_id bigint not null references documents (id) on delete cascade,
evidence_id text not null, -- 对外引用 ID(如 M642 / T1187)
content text not null,
section_no text,
page_from int,
page_to int,
batch text,
...
embedding vector(1024), -- BGE-M3 = 1024 维
bm25_tokens text, -- jieba 预分词结果(空格分隔)
...
);
create index if not exists chunks_embedding_idx on chunks using hnsw (embedding vector_cosine_ops);注意第三行的 on delete cascade。向量和文档在同一个库里,删一份文档,它的切片和向量跟着一起删,在同一个事务里完成。如果向量存在另一个系统,你就得自己保证两边的删除是一致的,删了一边、另一边失败,就会留下「检索得到、却找不到原文」的孤儿向量。对一个以「每句话都能核对到原文」为卖点的系统来说,这是最不能接受的那种 bug。
第三份:任务队列。 文档解析、向量化这些慢活交给后台 worker。没有用 Redis + Celery,而是一张 jobs 表。领任务的 SQL 是整个队列的核心:
with candidate as (
select id from jobs
where status = 'queued'
order by created_at
for update skip locked
limit 1
)
update jobs j
set status = 'running',
worker_id = %s,
started_at = now(),
heartbeat_at = now(),
attempts = j.attempts + 1
from candidate c
where j.id = c.id
returning j.id, j.type, j.payload, j.attemptsmodules/tasks/queue.py#L48-L80
for update skip locked 是关键:多个 worker 同时来领,已经被别人锁住的行直接跳过,不会两个 worker 抢到同一个任务,也不会互相等锁。领取、改状态、计次数在一条语句里完成,是原子的。
剩下的可靠性靠三样东西:worker 每 15 秒写一次心跳;后台定期把心跳超过 120 秒的任务回收放回队列(worker 崩了也能自救);失败的任务最多重试 3 次,超过就标为 failed 并留下错误信息。
踩坑:心跳必须在独立线程里写
解析一份大 PDF 可能要好几分钟。如果心跳和任务处理在同一个线程里,处理期间心跳就停了,120 秒后任务被当成「worker 已死」回收,另一个 worker 领走重新跑一遍。同一份文档被解析两次、入库两遍。所以 worker 的心跳是一个独立线程,主线程阻塞多久,心跳都照常写。
还有两个部署上的小坑,都写在 docker-compose.yml 的注释里:worker 和 app 用同一个镜像,镜像自带的健康检查探的是 8000 端口,而 worker 不起 HTTP 服务,所以 worker 的健康检查要显式关掉,否则它永远是 unhealthy;worker 要等 app 启动之后再起,因为建表的迁移由 app 执行,worker 抢在前面就会去查一张还不存在的表。
什么时候该把 PostgreSQL 拆开
不是永远不拆。几个信号出现时再考虑:切片涨到百万级、HNSW 索引的内存和构建时间开始成为问题;任务量大到需要优先级、延迟队列、跨服务投递;检索 QPS 高到和业务读写抢资源。售后知识库在可见的未来离这些都很远。先用一个库跑起来,真到那一天,因为 modules 之间是靠协议协作的,换掉其中一块的代价也不大。
三、契约先行:先写 4,360 行 YAML
这个项目的第一个阶段(代码里叫 S0)没写业务代码,写的是接口契约 contracts/openapi.yaml。现在它有 4,360 行,描述了浮层问答链、后台治理链和 SSE 事件的全部形状。
契约目录的 README 只有四条规则,我觉得每一条都值得抄:
- 字段名、类型、错误码、SSE 事件名,前后端都以契约为唯一出处
- 改接口先改契约,再同步前后端,不要只改一边
- 拿不准的字段或行为标
[待确认],登记到待确认清单里,不臆造 - 示例数据只是快照,运行时数据一律来自真实接口
光有规则不够,得有门禁。tests/test_openapi_contract.py 会检查契约本身:YAML 是否合法、所有 $ref 能否解析、版本号是否和 pyproject.toml 一致、前端用到的每个接口是否都在契约里、SSE 的事件名集合对不对。还有一条我很喜欢的双链隔离检查:/admin/* 不接受浮层的凭证,/widget/* 和 /chat 不接受管理员的凭证。工程师端和管理端是两条完全隔开的会话链,契约层面就要写死。
契约先行的好处是前后端可以并行。前端照着契约和示例数据先把页面写出来,后端照着契约实现,联调的时候大多数问题已经在 CI 里被拦下了。
四、先通链路,再求答案
项目的推进顺序大致是:契约 → 骨架链路 → 文档解析 → 检索、证据门与引用校验 → 浮层支撑接口与前端托管 → 抽出评测与线上共用的问答管线 → 运行时配置。代码注释里能看到每一块是在哪个阶段(S0、S1……S7)落地的。
其中第二步「骨架链路」值得单独说。在还没有任何检索能力的时候,/chat 就已经能工作了:浮层建立会话、发问题、服务端调大模型、用 SSE 一帧一帧推回来、写进问答日志。只是答案没有任何依据,所以界面上会带一句醒目的前缀:
SKELETON_NOTICE = "(骨架模式:未接入资料检索,以下内容仅验证链路连通,不构成答案)"骨架模式至今还在,CHAT_MODE=skeleton 就能切过去,用来排查「到底是链路断了,还是检索出了问题」。
先通链路的意义在于,最难调的问题往往不在 RAG 本身:SSE 被反向代理缓冲住了、浮层跨域拿不到上下文、大模型的推理 token 把 max_tokens 吃光导致返回空内容……这些问题越早暴露越好。等检索上线,你可以确定答案不对就是检索和生成的问题,不用再怀疑管道。
五、运行时配置:读失败也不能阻断问答
检索阈值、证据门阈值、安全词表、欢迎语这些参数,售后主管需要在后台直接调,保存后下一次问答就生效,不能每次都改 .env、重启容器。
实现是一张 app_config 表加一个只读的加载函数。我最在意的是它失败时的行为:
def load_config(conn, groups):
"""读取 `config.<group>` 的 JSON 对象;失败返回空 dict。"""
keys = [GROUP_PREFIX + group for group in groups]
try:
with conn.cursor() as cur:
cur.execute("select key, value from app_config where key = any(%s)", (keys,))
rows = cur.fetchall()
except Exception as exc: # noqa: BLE001 - 配置是增强项,不能阻断主链路
logger.warning("load runtime config failed: %s", exc)
return {}
...表不存在、数据库抖了一下、存进去的值不合法,一律回退到环境变量里的默认值。运行时配置是锦上添花,主链路不能因为它而断。同样的原则贯穿整个项目:重排失败回退 RRF,批次追问查询失败就不追问,增强项失败要降级,不能升级成故障。
最后说一个很小但我很喜欢的细节,关于版本号。/health 接口会返回当前版本,这个版本号只有一个来源,就是 pyproject.toml。代码注释是这么写的:
写死的版本号在第二次发版时就会变成假话,而且是那种「页面上看着很确定」的假话。
读不到包元数据就显示 0.0.0-dev,宁可难看,也不编一个版本号。这和整个项目的气质是一样的:不知道就说不知道。
六、小结
| 决定 | 换来的 | 付出的 |
|---|---|---|
| app / modules 两层,依赖单向 | 换行业不动机制代码;模块可单独测试 | 跨模块要用协议,写起来更啰嗦 |
| 一个 PostgreSQL 干三份活 | 部署只有一个有状态组件;删除天然一致 | 规模上去以后要拆 |
| 契约先行 + 契约测试 | 前后端并行;接口漂移在 CI 里暴露 | 改接口要多改一个文件 |
| 先跑通骨架链路 | 管道问题早暴露,后面只用关心答案对不对 | 前期看不到「智能」 |
地基讲完了。下一篇讲资料怎么进来:一份 PDF、一张 Excel,怎么被切成一块一块「能被引用」的证据单元。