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.
- cninvoice-0.1.0/.gitignore +57 -0
- cninvoice-0.1.0/LICENSE +21 -0
- cninvoice-0.1.0/PKG-INFO +205 -0
- cninvoice-0.1.0/README.md +158 -0
- cninvoice-0.1.0/docs/MODELS.md +83 -0
- cninvoice-0.1.0/docs/PUBLISHING.md +72 -0
- cninvoice-0.1.0/examples/benchmark_backends.py +234 -0
- cninvoice-0.1.0/examples/read_invoice.py +6 -0
- cninvoice-0.1.0/pyproject.toml +52 -0
- cninvoice-0.1.0/src/cninvoice/__init__.py +20 -0
- cninvoice-0.1.0/src/cninvoice/_merge.py +97 -0
- cninvoice-0.1.0/src/cninvoice/backends.py +170 -0
- cninvoice-0.1.0/src/cninvoice/bundles.py +74 -0
- cninvoice-0.1.0/src/cninvoice/cli.py +67 -0
- cninvoice-0.1.0/src/cninvoice/cloud.py +145 -0
- cninvoice-0.1.0/src/cninvoice/config.py +64 -0
- cninvoice-0.1.0/src/cninvoice/documents.py +259 -0
- cninvoice-0.1.0/src/cninvoice/errors.py +10 -0
- cninvoice-0.1.0/src/cninvoice/models.py +209 -0
- cninvoice-0.1.0/src/cninvoice/ocr.py +226 -0
- cninvoice-0.1.0/src/cninvoice/parsers.py +323 -0
- cninvoice-0.1.0/src/cninvoice/profiles.py +80 -0
- cninvoice-0.1.0/src/cninvoice/py.typed +0 -0
- cninvoice-0.1.0/src/cninvoice/reader.py +117 -0
- cninvoice-0.1.0/src/cninvoice/review.py +43 -0
- cninvoice-0.1.0/src/cninvoice/specialists.py +92 -0
- cninvoice-0.1.0/src/cninvoice/vat_anchors.py +198 -0
- cninvoice-0.1.0/src/cninvoice/vision.py +239 -0
- cninvoice-0.1.0/src/cninvoice/xbrl.py +144 -0
- cninvoice-0.1.0/tests/conftest.py +59 -0
- cninvoice-0.1.0/tests/test_backends.py +119 -0
- cninvoice-0.1.0/tests/test_benchmark.py +39 -0
- cninvoice-0.1.0/tests/test_bundles.py +118 -0
- cninvoice-0.1.0/tests/test_cloud.py +88 -0
- cninvoice-0.1.0/tests/test_corpus_teacher.py +85 -0
- cninvoice-0.1.0/tests/test_ocr.py +119 -0
- cninvoice-0.1.0/tests/test_official_xbrl.py +78 -0
- cninvoice-0.1.0/tests/test_pseudo_dataset.py +65 -0
- cninvoice-0.1.0/tests/test_pseudo_labels.py +55 -0
- cninvoice-0.1.0/tests/test_reader.py +356 -0
- cninvoice-0.1.0/tests/test_specialists.py +173 -0
- cninvoice-0.1.0/tests/test_teacher_dataset.py +76 -0
- cninvoice-0.1.0/tests/test_training_data.py +24 -0
- cninvoice-0.1.0/tests/test_training_policy.py +32 -0
- cninvoice-0.1.0/tests/test_vat_anchors.py +199 -0
- cninvoice-0.1.0/tests/test_vision.py +175 -0
- cninvoice-0.1.0/tools/build_model_bundle.py +65 -0
- cninvoice-0.1.0/tools/prepare_release.py +53 -0
- cninvoice-0.1.0/training/build_specialists.py +119 -0
- cninvoice-0.1.0/training/build_teacher_dataset.py +169 -0
- cninvoice-0.1.0/training/collect_public_samples.py +114 -0
- cninvoice-0.1.0/training/collect_repository_media.py +97 -0
- cninvoice-0.1.0/training/export_detector.py +46 -0
- cninvoice-0.1.0/training/label_corpus.py +241 -0
- cninvoice-0.1.0/training/merge_pseudo_dataset.py +76 -0
- cninvoice-0.1.0/training/prepare_annotation_tasks.py +42 -0
- cninvoice-0.1.0/training/prepare_data.py +212 -0
- cninvoice-0.1.0/training/pseudo_label.py +189 -0
- cninvoice-0.1.0/training/train_detector.py +188 -0
- 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
|
cninvoice-0.1.0/LICENSE
ADDED
|
@@ -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.
|
cninvoice-0.1.0/PKG-INFO
ADDED
|
@@ -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/)。
|