refactor: --id 改为真实 ID 列,新增 --sn 对应总排号

此前接口 --id 实际按总排号列查询,与数据库真实 ID 字段语义混淆。
现明确区分两种键类型:
- --id  -> 数据库真实 ID 列(config id_field)
- --sn  -> 总排号列(config id_column,即原先 --id 的语义)
- --ids-file 视为总排号(键类型 sn)

db.py: fetch_params_by_ids 改为接受 (标识符, 键类型) 列表,返回
  {标识符: {param, sn}};id 键回取对应总排号;新增 id_field 配置读取
classifier.py: classify_batch/classify_single 透传键类型,输出 zong_pai_hao
  一律为回查到的总排号,not_found 时回退输入标识符便于追溯
main.py / write_attachments.py: 新增 --sn,--id 改指真实 ID,二者可混用;
  全表扫描回退仍按总排号(sn)查询
README.md: 对齐 --id/--sn 语义并补充 id_field 配置说明

注:config.yaml 含密钥被 .gitignore 忽略,id_field 仅存于本地配置;
db.py 在未配置 id_field 时优雅降级为按总排号查询并告警。

Co-Authored-By: WorkBuddy <workbuddy@tencent.com>
This commit is contained in:
Misaka_Company
2026-07-24 16:00:21 +08:00
parent 622f348cf1
commit ee566e3fbd
5 changed files with 236 additions and 121 deletions

View File

@@ -20,7 +20,9 @@ pip install -r requirements.txt
编辑 `config.yaml`,填入以下三部分(首次使用需替换为真实值,**请勿将含真实
数据库密码 / API Key 的配置文件提交到版本库**
- `database`SQL Server 连接信息(含 `schema`)、表名、字段名
- `database`SQL Server 连接信息(含 `schema`)、表名、字段名。其中
`id_column` 为**总排号**列(接口 `--sn` 使用),`id_field` 为数据库**真实 ID**
列(接口 `--id` 使用);二者需按源表实际列名填写
- `llm`OpenAI 兼容接口的 `base_url``api_key``model`
- `business`:并发数、日志级别、默认分类模式(`default_mode`)、日志目录(`log_dir`)、
是否启用"其他"兜底类目(`enable_other_category`,默认关闭)
@@ -28,32 +30,41 @@ pip install -r requirements.txt
## 使用
```bash
# 指定方式有两种键类型,可混用:
# --sn 按总排号列查询(如 26B742即原先 --id 的语义
# --id 按数据库真实 ID 列查询(如 802
# 无论用哪种,输出 JSON 的 zong_pai_hao 一律为回查到的总排号
# 单个总排号,默认粗分类
python main.py --id 26B742
python main.py --sn 26B742
# 批量,逗号分隔
python main.py --id 26B742,26B743,26B744
python main.py --sn 26B742,26B743,26B744
# 按数据库真实 ID 指定(单个 / 多个)
python main.py --id 802
python main.py --id 802,803,804
# 批量,文件输入(每行一个总排号)
python main.py --ids-file ids.txt
# 精分类:输出"大类:细分类目"组合
python main.py --id 26B742 --mode fine
python main.py --sn 26B742 --mode fine
# 指定其他配置文件
python main.py --id 26B742 --config other_config.yaml
python main.py --id 802 --config other_config.yaml
# 临时覆盖日志目录
python main.py --id 26B742 --log-dir /tmp/debug_logs
python main.py --sn 26B742 --log-dir /tmp/debug_logs
# 格式化输出(默认是紧凑的 JSON Lines每行一条
python main.py --id 26B742,26B743 --pretty
python main.py --sn 26B742,26B743 --pretty
# 允许模型使用"其他"兜底类目
python main.py --id 26B742 --mode fine --enable-other
python main.py --sn 26B742 --mode fine --enable-other
# 额外在 stderr 打印本批运行汇总(耗时/token/缓存命中率stdout 仍只输出干净 JSON Lines
python main.py --id 26B742,26B743 --summary
python main.py --sn 26B742,26B743 --summary
```
## 分类粒度coarse / fine
@@ -230,12 +241,18 @@ python write_attachments.py
# 仅前 N 个总排号(测试用,避免一次性消耗大量 LLM 额度)
python write_attachments.py --limit 10
# 指定总排号文件(每行一个)
# 指定总排号文件(每行一个,键类型 sn
python write_attachments.py --ids-file ids.txt
# 直接指定总排号:单个或逗号分隔多个(与 --ids-file 可合并,提供后不再全表扫描)
python write_attachments.py --id 26B742
python write_attachments.py --id 26B742,26B743,26B744
# 按总排号指定(键类型 sn即原先 --id 的语义):单个或逗号分隔多个
python write_attachments.py --sn 26B742
python write_attachments.py --sn 26B742,26B743,26B744
# 按数据库真实 ID 指定(键类型 id单个或逗号分隔多个
python write_attachments.py --id 802
python write_attachments.py --id 802,803
# --id / --sn / --ids-file 可混用;提供任一后不再全表扫描(--limit 此时无效)
# 粗分类写入(小类统一填占位值);不指定 --mode 则用配置文件 business.default_mode
python write_attachments.py --mode coarse
@@ -271,10 +288,10 @@ python write_attachments.py --mode fine --enable-other
```
├── config.yaml # 配置文件
├── main.py # 命令行入口:分类并输出 JSON Lines支持 --summary 在 stderr 打印批汇总;直接 import 同目录各模块)
├── write_attachments.py # 写入入口:分类结果落库到 Common.Attachment全量/--limit/--ids-file/--mode/--dry-run/--enable-other/--config运行后打印 token/缓存汇总)
├── write_attachments.py # 写入入口:分类结果落库到 Common.Attachment全量/--limit/--id/--sn/--ids-file/--mode/--dry-run/--enable-other/--config运行后打印 token/缓存汇总)
├── requirements.txt
├── config_loader.py # YAML 配置读取与校验
├── db.py # SQL Server 查询与落库fetch_params_by_ids / fetch_all_ids / upsert_attachmentspyodbc
├── db.py # SQL Server 查询与落库fetch_params_by_ids 支持按 id/sn 双键查询、fetch_all_ids / upsert_attachmentspyodbc
├── prompts.py # 提示词与细分类目枚举(唯一需要改分类边界时编辑的文件)
├── llm_client.py # LLM 调用 (OpenAI 兼容接口)
├── parser.py # LLM 输出格式校验与清洗 → 结构化数据