cninvoice 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. cninvoice-0.1.0/.gitignore +57 -0
  2. cninvoice-0.1.0/LICENSE +21 -0
  3. cninvoice-0.1.0/PKG-INFO +205 -0
  4. cninvoice-0.1.0/README.md +158 -0
  5. cninvoice-0.1.0/docs/MODELS.md +83 -0
  6. cninvoice-0.1.0/docs/PUBLISHING.md +72 -0
  7. cninvoice-0.1.0/examples/benchmark_backends.py +234 -0
  8. cninvoice-0.1.0/examples/read_invoice.py +6 -0
  9. cninvoice-0.1.0/pyproject.toml +52 -0
  10. cninvoice-0.1.0/src/cninvoice/__init__.py +20 -0
  11. cninvoice-0.1.0/src/cninvoice/_merge.py +97 -0
  12. cninvoice-0.1.0/src/cninvoice/backends.py +170 -0
  13. cninvoice-0.1.0/src/cninvoice/bundles.py +74 -0
  14. cninvoice-0.1.0/src/cninvoice/cli.py +67 -0
  15. cninvoice-0.1.0/src/cninvoice/cloud.py +145 -0
  16. cninvoice-0.1.0/src/cninvoice/config.py +64 -0
  17. cninvoice-0.1.0/src/cninvoice/documents.py +259 -0
  18. cninvoice-0.1.0/src/cninvoice/errors.py +10 -0
  19. cninvoice-0.1.0/src/cninvoice/models.py +209 -0
  20. cninvoice-0.1.0/src/cninvoice/ocr.py +226 -0
  21. cninvoice-0.1.0/src/cninvoice/parsers.py +323 -0
  22. cninvoice-0.1.0/src/cninvoice/profiles.py +80 -0
  23. cninvoice-0.1.0/src/cninvoice/py.typed +0 -0
  24. cninvoice-0.1.0/src/cninvoice/reader.py +117 -0
  25. cninvoice-0.1.0/src/cninvoice/review.py +43 -0
  26. cninvoice-0.1.0/src/cninvoice/specialists.py +92 -0
  27. cninvoice-0.1.0/src/cninvoice/vat_anchors.py +198 -0
  28. cninvoice-0.1.0/src/cninvoice/vision.py +239 -0
  29. cninvoice-0.1.0/src/cninvoice/xbrl.py +144 -0
  30. cninvoice-0.1.0/tests/conftest.py +59 -0
  31. cninvoice-0.1.0/tests/test_backends.py +119 -0
  32. cninvoice-0.1.0/tests/test_benchmark.py +39 -0
  33. cninvoice-0.1.0/tests/test_bundles.py +118 -0
  34. cninvoice-0.1.0/tests/test_cloud.py +88 -0
  35. cninvoice-0.1.0/tests/test_corpus_teacher.py +85 -0
  36. cninvoice-0.1.0/tests/test_ocr.py +119 -0
  37. cninvoice-0.1.0/tests/test_official_xbrl.py +78 -0
  38. cninvoice-0.1.0/tests/test_pseudo_dataset.py +65 -0
  39. cninvoice-0.1.0/tests/test_pseudo_labels.py +55 -0
  40. cninvoice-0.1.0/tests/test_reader.py +356 -0
  41. cninvoice-0.1.0/tests/test_specialists.py +173 -0
  42. cninvoice-0.1.0/tests/test_teacher_dataset.py +76 -0
  43. cninvoice-0.1.0/tests/test_training_data.py +24 -0
  44. cninvoice-0.1.0/tests/test_training_policy.py +32 -0
  45. cninvoice-0.1.0/tests/test_vat_anchors.py +199 -0
  46. cninvoice-0.1.0/tests/test_vision.py +175 -0
  47. cninvoice-0.1.0/tools/build_model_bundle.py +65 -0
  48. cninvoice-0.1.0/tools/prepare_release.py +53 -0
  49. cninvoice-0.1.0/training/build_specialists.py +119 -0
  50. cninvoice-0.1.0/training/build_teacher_dataset.py +169 -0
  51. cninvoice-0.1.0/training/collect_public_samples.py +114 -0
  52. cninvoice-0.1.0/training/collect_repository_media.py +97 -0
  53. cninvoice-0.1.0/training/export_detector.py +46 -0
  54. cninvoice-0.1.0/training/label_corpus.py +241 -0
  55. cninvoice-0.1.0/training/merge_pseudo_dataset.py +76 -0
  56. cninvoice-0.1.0/training/prepare_annotation_tasks.py +42 -0
  57. cninvoice-0.1.0/training/prepare_data.py +212 -0
  58. cninvoice-0.1.0/training/pseudo_label.py +189 -0
  59. cninvoice-0.1.0/training/train_detector.py +188 -0
  60. cninvoice-0.1.0/training/training_policy.py +43 -0
@@ -0,0 +1,57 @@
1
+ # Local environments and generated files
2
+ .venv/
3
+ venv/
4
+ .pytest_cache/
5
+ __pycache__/
6
+ *.py[cod]
7
+ *.egg-info/
8
+ build/
9
+ dist/
10
+ release/
11
+ *.log
12
+ .DS_Store
13
+
14
+ # Private research, samples, labels, and provider configuration
15
+ .private/
16
+ experiments/
17
+ datasets/
18
+ data/
19
+ models/
20
+ checkpoints/
21
+ .env
22
+ .env.*
23
+ .pypirc
24
+ .netrc
25
+ pypi-token
26
+ credentials.json
27
+ credentials.yml
28
+ credentials.yaml
29
+ config/annotation_models/
30
+
31
+ # Credentials and model artifacts
32
+ *.pem
33
+ *.key
34
+ *.p12
35
+ *.pfx
36
+ *.onnx
37
+ *.pt
38
+ *.pth
39
+ *.ckpt
40
+ *.safetensors
41
+ *.bin
42
+ *.zip
43
+ *.tar.gz
44
+
45
+ # Invoice documents and raw sample media (add public fixtures deliberately)
46
+ *.pdf
47
+ *.ofd
48
+ *.xml
49
+ *.png
50
+ *.jpg
51
+ *.jpeg
52
+ *.webp
53
+ *.tif
54
+ *.tiff
55
+ *.bmp
56
+ *.jsonl
57
+ *.parquet
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 cninvoice contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,205 @@
1
+ Metadata-Version: 2.5
2
+ Name: cninvoice
3
+ Version: 0.1.0
4
+ Summary: Local-first structured extraction of Chinese invoices and reimbursement tickets
5
+ Project-URL: Homepage, https://github.com/YuqiPlus/CN-Invoice
6
+ Project-URL: Repository, https://github.com/YuqiPlus/CN-Invoice
7
+ Project-URL: Issues, https://github.com/YuqiPlus/CN-Invoice/issues
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: china,fapiao,invoice,ocr,vat
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3 :: Only
14
+ Requires-Python: >=3.10
15
+ Requires-Dist: defusedxml<1,>=0.7
16
+ Requires-Dist: pillow<13,>=11
17
+ Requires-Dist: pydantic<3,>=2.10
18
+ Requires-Dist: pypdf<8,>=5
19
+ Requires-Dist: pypdfium2<6,>=4
20
+ Provides-Extra: benchmark
21
+ Requires-Dist: httpx<1,>=0.28; extra == 'benchmark'
22
+ Requires-Dist: pyyaml<7,>=6; extra == 'benchmark'
23
+ Provides-Extra: dev
24
+ Requires-Dist: build<2,>=1.2; extra == 'dev'
25
+ Requires-Dist: httpx<1,>=0.28; extra == 'dev'
26
+ Requires-Dist: pytest<10,>=8; extra == 'dev'
27
+ Requires-Dist: twine<8,>=7; extra == 'dev'
28
+ Provides-Extra: http
29
+ Requires-Dist: httpx<1,>=0.28; extra == 'http'
30
+ Provides-Extra: ocr
31
+ Requires-Dist: onnxruntime<2,>=1.20; extra == 'ocr'
32
+ Requires-Dist: rapidocr<4,>=3.10; extra == 'ocr'
33
+ Provides-Extra: qwen
34
+ Requires-Dist: accelerate<2,>=1; extra == 'qwen'
35
+ Requires-Dist: torch<3,>=2.6; extra == 'qwen'
36
+ Requires-Dist: transformers<5,>=4.57; extra == 'qwen'
37
+ Provides-Extra: train
38
+ Requires-Dist: numpy<3,>=1.26; extra == 'train'
39
+ Requires-Dist: onnx<2,>=1.17; extra == 'train'
40
+ Requires-Dist: onnxruntime<2,>=1.20; extra == 'train'
41
+ Requires-Dist: torch<3,>=2.6; extra == 'train'
42
+ Requires-Dist: torchvision<1,>=0.21; extra == 'train'
43
+ Provides-Extra: vision
44
+ Requires-Dist: onnxruntime<2,>=1.20; extra == 'vision'
45
+ Requires-Dist: rapidocr<4,>=3.10; extra == 'vision'
46
+ Description-Content-Type: text/markdown
47
+
48
+ # CN-Invoice
49
+
50
+ 中国发票与报销票据解析库:输入 PDF、OFD、XML 或图片,返回统一的 Python `Invoice` 对象。
51
+
52
+ 优先解析文件中的结构化数据和文字,必要时接入本地视觉模型与 OCR。适合用于报销系统、发票归档和票据信息提取。
53
+
54
+ - 支持增值税发票、数电发票以及铁路、航空等报销票据的数据结构。
55
+ - 金额使用 `Decimal`,缺失字段返回 `None`,保留发票号码的前导零。
56
+ - 提供字段来源、金额一致性检查和待复核标记。
57
+ - 支持按票种配置本地专用模型,也可选用云端识别或 AI 复核。
58
+
59
+ ## 安装
60
+
61
+ Python 3.10+。
62
+
63
+ 从 GitHub 安装:
64
+
65
+ ```bash
66
+ python -m pip install "git+https://github.com/YuqiPlus/CN-Invoice.git"
67
+ ```
68
+
69
+ PyPI 发行版的安装命令:
70
+
71
+ ```bash
72
+ python -m pip install cninvoice
73
+ ```
74
+
75
+ 本地图片识别需要额外安装 `vision` 依赖:
76
+
77
+ ```bash
78
+ python -m pip install "cninvoice[vision]"
79
+ # 或从 GitHub 安装:
80
+ python -m pip install "cninvoice[vision] @ git+https://github.com/YuqiPlus/CN-Invoice.git"
81
+ ```
82
+
83
+ ## 快速开始
84
+
85
+ ```python
86
+ from cninvoice import read_invoice
87
+
88
+ invoice = read_invoice("invoice.pdf")
89
+
90
+ print(invoice.kind) # 票据类型
91
+ print(invoice.invoice_number) # 发票号码
92
+ print(invoice.amount) # 不含税金额
93
+ print(invoice.tax) # 税额
94
+ print(invoice.total) # 价税合计
95
+ print(invoice.needs_review) # 是否需要人工核对
96
+
97
+ # 转为 JSON,金额序列化为字符串
98
+ print(invoice.model_dump_json(indent=2))
99
+ ```
100
+
101
+ `read_invoice()` 接受文件路径、`bytes` 或二进制文件对象。PDF、OFD、XML 优先直接解析;扫描件和图片需要配置识图后端。
102
+
103
+ ```python
104
+ from pathlib import Path
105
+ from cninvoice import read_invoice
106
+
107
+ invoice = read_invoice(Path("invoice.xml"))
108
+ invoice = read_invoice(Path("invoice.ofd").read_bytes())
109
+
110
+ with open("invoice.pdf", "rb") as file:
111
+ invoice = read_invoice(file)
112
+ ```
113
+
114
+ ## 返回字段
115
+
116
+ | 字段 | 类型 | 含义 |
117
+ | --- | --- | --- |
118
+ | `kind` | `InvoiceKind` | 增值税发票、铁路客票、航空行程单等票据类型 |
119
+ | `invoice_number` | `str \| None` | 发票号码,保留前导零 |
120
+ | `invoice_code` | `str \| None` | 发票代码 |
121
+ | `issue_date` | `date \| None` | 开票日期 |
122
+ | `amount` | `Decimal \| None` | 不含税合计金额 |
123
+ | `tax` | `Decimal \| None` | 合计税额 |
124
+ | `total` | `Decimal \| None` | 价税合计或票据总金额 |
125
+ | `buyer` / `seller` | `Party` | 购销方名称、税号、地址及银行信息 |
126
+ | `items` | `list[LineItem]` | 明细项目 |
127
+ | `rail` / `air` | `RailJourney \| AirJourney \| None` | 铁路或航空行程信息 |
128
+ | `sources` | `dict[str, Evidence]` | 字段来源及可用的票面证据 |
129
+ | `issues` | `list[Issue]` | 缺项、冲突和校验提示 |
130
+ | `needs_review` | `bool` | 是否需要人工核对 |
131
+
132
+ 字段是否有值取决于票面内容、文件格式和识别后端。未识别出的金额保持 `None`;票面明确为零才返回零。`amount`、`tax`、`total` 全部读取到时会检查相加关系,但不会通过计算补齐缺项。
133
+
134
+ ## 本地图片识别
135
+
136
+ 本地识别使用 ONNX 字段检测器与 OCR,支持 CPU 推理,不需要部署大语言模型。按票据类型选择一个专用检测器,增值税模型重点提取发票号码、不含税金额、税额和价税合计。
137
+
138
+ 模型文件与 Python 包分开管理。**仓库目前提供推理及训练代码,尚无公开的预训练模型下载。** 使用图片识别前,需要准备兼容的模型包或自行训练并导出模型。
139
+
140
+ ### 加载模型包
141
+
142
+ 将模型包解压,传入包含 `bundle.json` 的目录:
143
+
144
+ ```python
145
+ from cninvoice import ReaderConfig
146
+
147
+ reader = ReaderConfig.from_bundle("./models/vat-bundle").create_reader()
148
+ invoice = reader.read("invoice.png")
149
+
150
+ print(invoice.total)
151
+ print(invoice.needs_review)
152
+ ```
153
+
154
+ `from_bundle()` 校验模型文件的大小与 SHA-256,使用包内的检测器及 OCR 文件。
155
+
156
+ ### 直接指定模型目录
157
+
158
+ ```python
159
+ from cninvoice import ReaderConfig
160
+
161
+ reader = ReaderConfig(
162
+ recognizer="specialists",
163
+ specialist_model_dirs={"vat_invoice": "./models/vat"},
164
+ ocr_model_dir="./models/ocr",
165
+ ).create_reader()
166
+
167
+ invoice = reader.read("invoice.jpg")
168
+ ```
169
+
170
+ 检测器目录包含 `detector.onnx` 和 `model.json`。票种配置项包括 `vat_invoice`、`rail_einvoice`、`ride_itinerary`、`air_itinerary`;每项需要对应的模型。OCR 模型文件名及模型包构建方式见 [模型配置](https://github.com/YuqiPlus/CN-Invoice/blob/main/docs/MODELS.md)。
171
+
172
+ 视觉识别当前用于单张图片或单页文件。OCR/模型结果会标记为待复核,模糊、遮挡、红字及不同版式可能导致字段缺失。
173
+
174
+ ## 命令行
175
+
176
+ ```bash
177
+ cninvoice invoice.pdf
178
+ cninvoice invoice.xml
179
+ cninvoice invoice.png --vision-model ./models/vat --ocr-models ./models/ocr
180
+ ```
181
+
182
+ 输出为 JSON。更多选项见 `cninvoice --help`。
183
+
184
+ ## 开发与训练
185
+
186
+ ```bash
187
+ git clone https://github.com/YuqiPlus/CN-Invoice.git
188
+ cd CN-Invoice
189
+ python -m pip install -e ".[dev,benchmark]"
190
+ python -m pytest
191
+ ```
192
+
193
+ 训练依赖:
194
+
195
+ ```bash
196
+ python -m pip install -e ".[train,vision,benchmark]"
197
+ ```
198
+
199
+ `training/` 包含样本准备、可选教师模型标注、标注校验、票种拆分、检测器训练和 ONNX 导出工具。各脚本通过 `--help` 查看参数。数据处理工具的私有输出放在 `.private/` 下。
200
+
201
+ 欢迎通过 [Issues](https://github.com/YuqiPlus/CN-Invoice/issues) 提交问题和通过 Pull Request 贡献改进。发行流程见 [发布指南](https://github.com/YuqiPlus/CN-Invoice/blob/main/docs/PUBLISHING.md)。
202
+
203
+ ## 许可证
204
+
205
+ 代码采用 [MIT License](https://github.com/YuqiPlus/CN-Invoice/blob/main/LICENSE)。使用第三方模型或数据时,请保留其各自的许可证与来源说明。
@@ -0,0 +1,158 @@
1
+ # CN-Invoice
2
+
3
+ 中国发票与报销票据解析库:输入 PDF、OFD、XML 或图片,返回统一的 Python `Invoice` 对象。
4
+
5
+ 优先解析文件中的结构化数据和文字,必要时接入本地视觉模型与 OCR。适合用于报销系统、发票归档和票据信息提取。
6
+
7
+ - 支持增值税发票、数电发票以及铁路、航空等报销票据的数据结构。
8
+ - 金额使用 `Decimal`,缺失字段返回 `None`,保留发票号码的前导零。
9
+ - 提供字段来源、金额一致性检查和待复核标记。
10
+ - 支持按票种配置本地专用模型,也可选用云端识别或 AI 复核。
11
+
12
+ ## 安装
13
+
14
+ Python 3.10+。
15
+
16
+ 从 GitHub 安装:
17
+
18
+ ```bash
19
+ python -m pip install "git+https://github.com/YuqiPlus/CN-Invoice.git"
20
+ ```
21
+
22
+ PyPI 发行版的安装命令:
23
+
24
+ ```bash
25
+ python -m pip install cninvoice
26
+ ```
27
+
28
+ 本地图片识别需要额外安装 `vision` 依赖:
29
+
30
+ ```bash
31
+ python -m pip install "cninvoice[vision]"
32
+ # 或从 GitHub 安装:
33
+ python -m pip install "cninvoice[vision] @ git+https://github.com/YuqiPlus/CN-Invoice.git"
34
+ ```
35
+
36
+ ## 快速开始
37
+
38
+ ```python
39
+ from cninvoice import read_invoice
40
+
41
+ invoice = read_invoice("invoice.pdf")
42
+
43
+ print(invoice.kind) # 票据类型
44
+ print(invoice.invoice_number) # 发票号码
45
+ print(invoice.amount) # 不含税金额
46
+ print(invoice.tax) # 税额
47
+ print(invoice.total) # 价税合计
48
+ print(invoice.needs_review) # 是否需要人工核对
49
+
50
+ # 转为 JSON,金额序列化为字符串
51
+ print(invoice.model_dump_json(indent=2))
52
+ ```
53
+
54
+ `read_invoice()` 接受文件路径、`bytes` 或二进制文件对象。PDF、OFD、XML 优先直接解析;扫描件和图片需要配置识图后端。
55
+
56
+ ```python
57
+ from pathlib import Path
58
+ from cninvoice import read_invoice
59
+
60
+ invoice = read_invoice(Path("invoice.xml"))
61
+ invoice = read_invoice(Path("invoice.ofd").read_bytes())
62
+
63
+ with open("invoice.pdf", "rb") as file:
64
+ invoice = read_invoice(file)
65
+ ```
66
+
67
+ ## 返回字段
68
+
69
+ | 字段 | 类型 | 含义 |
70
+ | --- | --- | --- |
71
+ | `kind` | `InvoiceKind` | 增值税发票、铁路客票、航空行程单等票据类型 |
72
+ | `invoice_number` | `str \| None` | 发票号码,保留前导零 |
73
+ | `invoice_code` | `str \| None` | 发票代码 |
74
+ | `issue_date` | `date \| None` | 开票日期 |
75
+ | `amount` | `Decimal \| None` | 不含税合计金额 |
76
+ | `tax` | `Decimal \| None` | 合计税额 |
77
+ | `total` | `Decimal \| None` | 价税合计或票据总金额 |
78
+ | `buyer` / `seller` | `Party` | 购销方名称、税号、地址及银行信息 |
79
+ | `items` | `list[LineItem]` | 明细项目 |
80
+ | `rail` / `air` | `RailJourney \| AirJourney \| None` | 铁路或航空行程信息 |
81
+ | `sources` | `dict[str, Evidence]` | 字段来源及可用的票面证据 |
82
+ | `issues` | `list[Issue]` | 缺项、冲突和校验提示 |
83
+ | `needs_review` | `bool` | 是否需要人工核对 |
84
+
85
+ 字段是否有值取决于票面内容、文件格式和识别后端。未识别出的金额保持 `None`;票面明确为零才返回零。`amount`、`tax`、`total` 全部读取到时会检查相加关系,但不会通过计算补齐缺项。
86
+
87
+ ## 本地图片识别
88
+
89
+ 本地识别使用 ONNX 字段检测器与 OCR,支持 CPU 推理,不需要部署大语言模型。按票据类型选择一个专用检测器,增值税模型重点提取发票号码、不含税金额、税额和价税合计。
90
+
91
+ 模型文件与 Python 包分开管理。**仓库目前提供推理及训练代码,尚无公开的预训练模型下载。** 使用图片识别前,需要准备兼容的模型包或自行训练并导出模型。
92
+
93
+ ### 加载模型包
94
+
95
+ 将模型包解压,传入包含 `bundle.json` 的目录:
96
+
97
+ ```python
98
+ from cninvoice import ReaderConfig
99
+
100
+ reader = ReaderConfig.from_bundle("./models/vat-bundle").create_reader()
101
+ invoice = reader.read("invoice.png")
102
+
103
+ print(invoice.total)
104
+ print(invoice.needs_review)
105
+ ```
106
+
107
+ `from_bundle()` 校验模型文件的大小与 SHA-256,使用包内的检测器及 OCR 文件。
108
+
109
+ ### 直接指定模型目录
110
+
111
+ ```python
112
+ from cninvoice import ReaderConfig
113
+
114
+ reader = ReaderConfig(
115
+ recognizer="specialists",
116
+ specialist_model_dirs={"vat_invoice": "./models/vat"},
117
+ ocr_model_dir="./models/ocr",
118
+ ).create_reader()
119
+
120
+ invoice = reader.read("invoice.jpg")
121
+ ```
122
+
123
+ 检测器目录包含 `detector.onnx` 和 `model.json`。票种配置项包括 `vat_invoice`、`rail_einvoice`、`ride_itinerary`、`air_itinerary`;每项需要对应的模型。OCR 模型文件名及模型包构建方式见 [模型配置](https://github.com/YuqiPlus/CN-Invoice/blob/main/docs/MODELS.md)。
124
+
125
+ 视觉识别当前用于单张图片或单页文件。OCR/模型结果会标记为待复核,模糊、遮挡、红字及不同版式可能导致字段缺失。
126
+
127
+ ## 命令行
128
+
129
+ ```bash
130
+ cninvoice invoice.pdf
131
+ cninvoice invoice.xml
132
+ cninvoice invoice.png --vision-model ./models/vat --ocr-models ./models/ocr
133
+ ```
134
+
135
+ 输出为 JSON。更多选项见 `cninvoice --help`。
136
+
137
+ ## 开发与训练
138
+
139
+ ```bash
140
+ git clone https://github.com/YuqiPlus/CN-Invoice.git
141
+ cd CN-Invoice
142
+ python -m pip install -e ".[dev,benchmark]"
143
+ python -m pytest
144
+ ```
145
+
146
+ 训练依赖:
147
+
148
+ ```bash
149
+ python -m pip install -e ".[train,vision,benchmark]"
150
+ ```
151
+
152
+ `training/` 包含样本准备、可选教师模型标注、标注校验、票种拆分、检测器训练和 ONNX 导出工具。各脚本通过 `--help` 查看参数。数据处理工具的私有输出放在 `.private/` 下。
153
+
154
+ 欢迎通过 [Issues](https://github.com/YuqiPlus/CN-Invoice/issues) 提交问题和通过 Pull Request 贡献改进。发行流程见 [发布指南](https://github.com/YuqiPlus/CN-Invoice/blob/main/docs/PUBLISHING.md)。
155
+
156
+ ## 许可证
157
+
158
+ 代码采用 [MIT License](https://github.com/YuqiPlus/CN-Invoice/blob/main/LICENSE)。使用第三方模型或数据时,请保留其各自的许可证与来源说明。
@@ -0,0 +1,83 @@
1
+ # 本地模型配置
2
+
3
+ 图片识别由两部分组成:字段检测器定位票面字段,OCR 读取文字。本地推理使用 ONNX Runtime CPU 后端;训练阶段使用 PyTorch。
4
+
5
+ ## 目录结构
6
+
7
+ 增值税字段模型目录:
8
+
9
+ ```text
10
+ models/vat/
11
+ ├── detector.onnx
12
+ └── model.json
13
+ ```
14
+
15
+ `detector.onnx` 使用项目训练及导出脚本生成,架构为 `ssdlite320_mobilenet_v3_large`。`model.json` 记录字段顺序、输入尺寸和阈值;它必须与检测器一起使用,不能仅把任意 ONNX 文件改成相同文件名。
16
+
17
+ OCR 目录需要以下兼容 RapidOCR 的文件:
18
+
19
+ ```text
20
+ models/ocr/
21
+ ├── PP-OCRv6_det_small.onnx
22
+ ├── ch_ppocr_mobile_v2.0_cls_mobile.onnx
23
+ └── PP-OCRv6_rec_small.onnx
24
+ ```
25
+
26
+ 安装 `cninvoice[vision]` 后可以加载这些模型;模型文件需要单独准备。
27
+
28
+ ## 按票种加载
29
+
30
+ ```python
31
+ from cninvoice import ReaderConfig
32
+
33
+ reader = ReaderConfig(
34
+ recognizer="specialists",
35
+ specialist_model_dirs={
36
+ "vat_invoice": "./models/vat",
37
+ # 取得对应模型后可增加以下票种:
38
+ # "rail_einvoice": "./models/rail",
39
+ # "ride_itinerary": "./models/ride",
40
+ # "air_itinerary": "./models/air",
41
+ },
42
+ ocr_model_dir="./models/ocr",
43
+ ).create_reader()
44
+ ```
45
+
46
+ OCR 标题及版式规则先选择票种,再调用对应检测器。未配置的票种不会借用其他检测器。`ReaderConfig(document_profile="vat_invoice", ...)` 可在已知票种时显式指定;冲突的票面标题仍会产生复核提示。
47
+
48
+ ## 训练和导出
49
+
50
+ 安装开发及训练依赖后,用以下命令查看数据、检测器和导出脚本的参数:
51
+
52
+ ```bash
53
+ python -m pip install -e ".[train,vision,benchmark]"
54
+ python training/build_specialists.py --help
55
+ python training/train_detector.py --help
56
+ python training/export_detector.py --help
57
+ ```
58
+
59
+ 训练脚本接收本地数据清单和初始权重,导出脚本从训练目录中的 `best.pt` 与 `model.json` 生成 `detector.onnx`,并检查 ONNX 与 PyTorch 输出的一致性。
60
+
61
+ ## 打包便携模型
62
+
63
+ 准备好字段模型目录、OCR 文件、模型说明及上游许可后:
64
+
65
+ ```bash
66
+ python tools/build_model_bundle.py \
67
+ --model-dir ./models/vat \
68
+ --ocr-dir ./models/ocr \
69
+ --ocr-license-dir ./models/ocr-licenses \
70
+ --model-card ./models/MODEL_CARD.md \
71
+ --output ./model-release
72
+ ```
73
+
74
+ `ocr-license-dir` 包含 `LICENSE` 和 `MODEL_LICENSES.md`。工具将运行文件、模型说明、许可和 SHA-256 清单打包为 ZIP;不包含训练数据和检查点。当前打包工具用于增值税专用模型。
75
+
76
+ 使用者解压后加载包含 `bundle.json` 的目录:
77
+
78
+ ```python
79
+ from cninvoice import ReaderConfig
80
+
81
+ reader = ReaderConfig.from_bundle("./models/vat-bundle").create_reader()
82
+ invoice = reader.read("invoice.png")
83
+ ```
@@ -0,0 +1,72 @@
1
+ # 发布指南
2
+
3
+ 项目通过 GitHub Release 发布到 PyPI。发布工作流会检查版本、运行测试、构建 wheel 和源码包,再使用 PyPI Trusted Publishing 上传。
4
+
5
+ ## 首次配置
6
+
7
+ 1. 登录 PyPI,打开 [账户 Publishing 页面](https://pypi.org/manage/account/publishing/)。
8
+ 2. 在 **Add a new pending publisher → GitHub** 中填写:
9
+
10
+ | 项目 | 填写内容 |
11
+ | --- | --- |
12
+ | PyPI Project Name | `cninvoice` |
13
+ | Owner | `YuqiPlus` |
14
+ | Repository name | `CN-Invoice` |
15
+ | Workflow name | `publish.yml` |
16
+ | Environment name | `pypi` |
17
+
18
+ 3. 点击 **Add**。如果项目已经存在,在项目的 **Manage → Publishing** 页面添加同样的发布配置。
19
+ 4. 在 GitHub 仓库的 **Settings → Environments** 中创建名为 `pypi` 的环境。
20
+
21
+ 该方式不需要生成或保存 PyPI API token。首次上传成功后,PyPI 会自动创建项目;配置 pending publisher 本身不会占用包名。
22
+
23
+ ## 发布一个版本
24
+
25
+ 1. 确认 `pyproject.toml` 的 `project.version` 与 `src/cninvoice/__init__.py` 的 `__version__` 一致。
26
+ 2. 将修改提交并推送到 GitHub。已经上传过 PyPI 的版本需要换用新版本号。
27
+ 3. 打开 [创建 Release 页面](https://github.com/YuqiPlus/CN-Invoice/releases/new)。
28
+ 4. 创建与版本对应的标签,例如版本 `0.1.0` 对应 `v0.1.0`;目标选择包含本次修改的提交。
29
+ 5. 填写更新说明。`0.1.0` 是正式版,不勾选 **Set as a pre-release**,点击 **Publish release**。
30
+ 6. 在仓库 **Actions → Publish to PyPI** 中查看测试、构建及发布结果。
31
+
32
+ 需要预先验证时,可在 **Actions → Publish to PyPI → Run workflow** 手动运行测试和构建;手动运行不会上传 PyPI。
33
+
34
+ Release 标签必须严格等于 `v` 加包版本号。工作流只在 Release 正式发布时触发,普通推送和保存草稿不会上传 PyPI。
35
+
36
+ 成功后,在新环境中验证:
37
+
38
+ ```bash
39
+ python -m pip install "cninvoice==0.1.0"
40
+ python -c "import cninvoice; print(cninvoice.__version__)"
41
+ cninvoice --help
42
+ ```
43
+
44
+ PyPI 不允许覆盖已上传的同名发行文件。后续发布应修改版本号并创建新标签。
45
+
46
+ ## 本机手动发布
47
+
48
+ 也可使用 Twine 从本机发布:
49
+
50
+ ```bash
51
+ python -m pip install -e ".[dev,benchmark]"
52
+ python -m pytest
53
+ python tools/prepare_release.py
54
+ ```
55
+
56
+ 构建工具会检查包内文件、许可证元数据和项目说明。输出目录为 `release/<version>/`,已有目录不会覆盖。以 `0.1.0` 为例:
57
+
58
+ ```bash
59
+ python -m twine upload --repository pypi --username __token__ \
60
+ release/0.1.0/cninvoice-0.1.0-py3-none-any.whl \
61
+ release/0.1.0/cninvoice-0.1.0.tar.gz
62
+ ```
63
+
64
+ 在密码提示中输入 PyPI API token。首次创建项目时使用具备创建权限的 token,项目创建后可改用项目级 token。不要把 token 放入仓库或命令参数。
65
+
66
+ 如需先试发 TestPyPI,将 `--repository pypi` 改成 `--repository testpypi`,并使用 TestPyPI 的账号及 token。
67
+
68
+ ## 模型文件
69
+
70
+ Python 发行包只包含库代码与文档。独立模型包可以作为 GitHub Release 附件或托管于模型仓库;其格式与构建命令见 [模型配置](https://github.com/YuqiPlus/CN-Invoice/blob/main/docs/MODELS.md)。
71
+
72
+ 参考:[PyPI 首次可信发布](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)、[Python 官方 GitHub 发布指南](https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/)。