---
title: fapiaoxia
canonical_url: "https://www.modelscope.cn/studios/taohuaJS/fapiaoxia"
md_url: "https://www.modelscope.cn/studios/taohuaJS/fapiaoxia.md"
repository: taohuaJS/fapiaoxia
chinese_name: "发票侠"
last_updated: 2026-09-19
sdk_type: docker
sdk_version: 6.17.3
downloads: 0
stars: 0
---

# fapiaoxia

> fapiaoxia - taohuaJS 在 ModelScope 创建的在线 Demo。发票侠 · 个人报销智能助手（魔搭创空间部署版）

taohuaJS/fapiaoxia 是 ModelScope 魔搭社区上的在线可交互 Demo（创空间），基于 docker 6.17.3 构建，中文名为「发票侠」。

- **Repository**: taohuaJS/fapiaoxia
- **SDK**: docker
- **SDK version**: 6.17.3
- **Downloads**: 0
- **Stars**: 0
- **Last updated**: 2026-09-19

Source: https://www.modelscope.cn/studios/taohuaJS/fapiaoxia

---

# 发票侠 · 个人报销智能助手（魔搭创空间部署版）

上传发票图片 → 火山方舟多模态模型自动识别字段 → 结构化入库 → 勾稽校验 → 一键导出报销 Excel。

- 前端：Vue3 + Element Plus（已预构建在 `frontend/dist`）
- 后端：Python FastAPI + SQLite
- 识别：火山方舟多模态模型（`doubao-seed-evolving`）
- 部署：单容器，魔搭创空间（ModelScope Studio）Docker 类型

---

## 一、部署到魔搭创空间（上线）

### 1. 准备
- 注册魔搭账号并完成**实名认证**（创空间必须）。
- 准备好火山方舟 API Key（套餐用户注意接入地址是 `/api/plan/v3`）。

### 2. 创建创空间
1. 打开 [创空间列表页](https://www.modelscope.cn/studios) → 点击「创建创空间」。
2. 选择「**编程式创空间 / Programmatic Studio**」，并切换到「**快速部署创建**」模式。
3. 填写名称、描述、封面（名称建议英文，如 `fapiao-hero`）。

### 3. 上传本文件夹
- 把 **fapiao-hero 整个文件夹的内容**（含 `Dockerfile`、`ms_deploy.json`、`backend/`、`frontend/`）上传到创空间根目录。
- 关键点：`Dockerfile` 必须在根目录。

### 4. 配置（二选一）

**方式 A：创空间环境变量（推荐，重启不丢）**
在创空间「环境变量 / 高级配置」里设置：
- `ARK_API_KEY`：你的火山方舟 Key（`ark-` 开头）
- `ARK_MODEL`：`doubao-seed-evolving`
- `ARK_BASE_URL`：
  - 套餐用户：`https://ark.cn-beijing.volces.com/api/plan/v3`
  - 标准用户：`https://ark.cn-beijing.volces.com/api/v3`

**方式 B：上线后在页面里配置**
部署成功后，打开网页右上角「**模型配置**」，粘贴 Key、测试连接、保存。
配置会写入持久化目录 `/mnt/workspace/.env`，重启后仍然保留。

### 5. 部署
- 点击「确认创建并部署」。`ms_deploy.json` 已指定 `sdk_type=docker`、端口 `7860`、免费规格（2vCPU/16G）。
- 等待构建完成，创空间会分配一个可公开访问的网址。

> 端口约定：魔搭创空间强制要求服务监听 `0.0.0.0:7860`，Dockerfile 已配置好，无需改动。

---

## 二、本地运行（开发 / 自测）

### 方式 1：直接用 Python（推荐，最快）

需要 Python 3.10+、Node.js 18+（前端已构建，无需重新 npm）。

```bash
# 1. 后端
cd backend
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate      # macOS/Linux
pip install -r requirements.txt

# 2. 配置 Key（复制 .env.example 为 .env 并填写，或在页面"模型配置"里填）
copy .env.example .env          # Windows

# 3. 启动
uvicorn app.main:app --host 127.0.0.1 --port 8000
```
浏览器打开 http://127.0.0.1:8000 。前端用的是 `frontend/dist` 预构建产物。

### 方式 2：本地 Docker 验证（与魔搭一致）

```bash
docker build -t fapiao-hero .
docker run -p 7860:7860 -e ARK_API_KEY=你的Key fapiao-hero
```
浏览器打开 http://127.0.0.1:7860 。

### 修改前端后重新构建
```bash
cd frontend
npm install
npm run build      # 产物输出到 frontend/dist
```

---

## 三、目录结构

```
fapiao-hero/
├── Dockerfile            # 魔搭容器构建（单容器，端口 7860）
├── ms_deploy.json        # 魔搭部署配置（sdk=docker / port=7860 / 环境变量）
├── .dockerignore
├── backend/
│   ├── app/              # FastAPI 源码（路由、识别、校验、导出、配置）
│   ├── tests/            # 离线测试
│   ├── requirements.txt
│   └── .env.example
├── frontend/
│   ├── dist/             # 已构建的前端（Docker 直接使用，无需 Node）
│   └── src/              # 前端源码（Vue3 + Element Plus）
└── samples/
    └── mock_vat_invoice.png   # 模拟专票，可用于上线后验证识别链路
```

## 四、数据与隐私

- 数据（SQLite 数据库、上传图片）默认存在 `/mnt/workspace/data`（魔搭持久化目录），本地运行时在 `backend/data`。
- 发票图片仅在「识别」时发送给火山方舟，其余时间不离开服务。
- API Key 建议用环境变量或页面配置，不要写进代码。

## 五、支持的票据与字段

增值税专用发票、增值税普通发票（含电子票）、火车票、航空运输电子客票行程单、出租车发票。
内置勾稽校验：金额+税额=价税合计（容差 0.01）、税额÷金额与税率吻合（±0.01）；
字段置信度低于 0.85 自动标红提示人工复核；勾稽不平自动重识别一次；识别失败明确给出原因。