FastAPI+SQLite构建轻量级本地素材标签索引服务

这次我们来看一个非常“轻”的本地项目：Just an idea。它不依赖 GPU，也不需要下载大模型，而是一个基于 FastAPI + SQLite 的创意素材标签索引服务。核心解决的是本地灵感文件越来越多、命名越来越乱、真要找的时候却翻不到的问题。像#Oai、#Fara、#Venus这类散落在文件名里的标签，完全可以自动解析、建索引、按标签检索，省掉手工整理目录的重复劳动。

如果你正在做内容创作、短视频分镜、音频采样、视觉参考图收集，或者只是单纯想给本地文件建立一个可搜索的“灵感仓库”，这篇文章可以直接收藏。下文会按一条完整可落地的流程展开：先说这个工具能做什么、适合什么场景，再给出环境准备、部署启动、功能测试、API 调用、批量任务和常见问题排查，最后补一套素材管理的工程化建议。

1. 核心能力速览

这里要说明一点：项目本身不存储图片或音视频内容，只保存文件路径、文件名和解析出的标签。真正需要读文件的时候，仍然靠本地文件系统或现有播放器、看图软件完成。这样设计的好处是索引体积小、扫描速度快、版权归属清晰，不会把素材复制到私有数据库里造成二次分发风险。

2. 适用场景与使用边界

2.1 适合谁用

这个项目的目标用户很明确：本地文件数量多、命名风格带标签、又不想为素材管理专门买商业化软件的人。典型场景包括：

• 内容创作者维护一个ideas目录，里面放着分镜截图、参考音乐、文案草稿、竞品案例截图。
• 设计师收集灵感图，文件名里习惯写#UI #配色 #字体。
• 配音或音频素材库中，文件前缀带着#角色 #情绪 #场景等标签。
• 视频创作者把分镜文件、音效片段统一放在本地目录，但受限于目录层级，无法快速跨文件夹检索。

当你把文件集中到一个根目录后，这个工具会自动扫描所有子目录，把标签提取到 SQLite 数据库，然后通过一个简单的 HTTP 接口返回搜索结果。相比“挨个目录翻文件”，效率提升非常明显。

2.2 不适合什么场景

它不适合作为大规模文件管理系统，也不提供文件版本管理、多人协同、在线预览这类能力。如果你的需求是团队级素材库，应该考虑成熟的 DAM（数字资产管理）系统。如果素材经常发生移动和重命名，本工具的索引会过期，需要手动触发重扫。

另外，标签只支持#开头的规则。如果你习惯用@标作者、用|分隔信息，需要先统一命名规范。

2.3 合规使用边界

本地素材管理工具本身不涉及版权问题，但有一个前提：所有被收录的文件都应该来自合法渠道。尤其要注意，涉及搬运、转载、二次剪辑的内容，必须确认获得了原作者授权。不要用“本地管理”作为侵权素材存储的借口。对于涉及人脸、声音、角色形象的内容，更要严格确认肖像权和版权授权范围。

本文的示例代码只做文件名元数据解析，不会读取文件内容，也不会上传任何数据到外部服务器，适合在个人电脑或内网环境使用。

3. 环境准备与前置条件

3.1 推荐运行环境

这个项目不挑硬件。CPU 和内存要求很低，普通办公电脑都能运行。我建议至少准备：

• Python 3.10 或更高版本。
• 2GB 可用内存即可，几百个素材文件的索引过程内存占用可以忽略。
• 磁盘空间：代码本身不到 5KB，索引数据库按文件数量增长，一千个文件大概几百 KB 到几 MB。
• 操作系统无硬性要求，Windows 11、Ubuntu 22.04、macOS 13 都可以。

3.2 安装 Python 依赖

项目只需要两个 Python 包：fastapi和uvicorn。如果你不希望污染全局环境，可以先用 venv 创建虚拟环境。

mkdir idea-index cd idea-index python -m venv .venv source .venv/bin/activate # Windows 使用 .venv\Scripts\activate pip install --upgrade pip pip install fastapi uvicorn

安装完成后，检查版本：

python --version uvicorn --version

没有报错就说明基础环境已经就绪。数据库使用 Python 自带 sqlite3，不需要额外安装数据库服务。

3.3 目录规划

在项目根目录创建ideas素材目录，后续所有需要被索引的文件都放进去。建议使用固定目录，不要随意更换路径，否则需要定期重扫。

mkdir ideas

整体目录结构如下：

idea-index/ │ ├── .venv/ # 虚拟环境 ├── ideas/ # 本地创意素材目录 │ ├── 分镜/ │ │ └── 随手涂鸦 #Oai #idea.png │ ├── 参考视频/ │ │ └── 酣睡的猫 - 片段 #Fara #Venus.mp4 │ └── 音乐/ │ └── 情绪板 #Oai #Venus.mp3 ├── main.py # FastAPI 项目代码 └── idea_index.db # 运行后自动生成的索引数据库

这种目录规划的好处是结构清晰，素材目录和程序目录分离，备份时可以只备份ideas和idea_index.db。

4. 安装部署与启动方式

4.1 编写核心代码

将下面的代码保存为main.py。这段代码实现了三个核心能力：扫描目录、解析标签、提供搜索 API。

import re import sqlite3 from pathlib import Path import uvicorn from fastapi import FastAPI, Query app = FastAPI(title="Just an idea - Local Creative Tag Index") ROOT_DIR = Path("./ideas") DB_PATH = Path("idea_index.db") TAG_RE = re.compile(r"#([A-Za-z0-9_\-\u4e00-\u9fa5]+)") def get_conn(): conn = sqlite3.connect(DB_PATH) return conn def init_db(): with get_conn() as conn: conn.execute(""" CREATE TABLE IF NOT EXISTS files ( id INTEGER PRIMARY KEY AUTOINCREMENT, path TEXT UNIQUE, name TEXT, tags TEXT, updated_at REAL ) """) conn.commit() def scan_ideas(): init_db() ROOT_DIR.mkdir(exist_ok=True) records = [] for p in ROOT_DIR.rglob("*"): if not p.is_file(): continue tags = TAG_RE.findall(p.name) records.append((str(p), p.name, ",".join(tags), p.stat().st_mtime)) with get_conn() as conn: conn.execute("DELETE FROM files") conn.executemany( "INSERT OR REPLACE INTO files(path, name, tags, updated_at) VALUES (?, ?, ?, ?)", records, ) conn.commit() return len(records) def query_files(tag: str = "", q: str = ""): with get_conn() as conn: if tag: rows = conn.execute( "SELECT path, name, tags FROM files WHERE tags LIKE ?", (f"%{tag}%",), ).fetchall() elif q: rows = conn.execute( "SELECT path, name, tags FROM files WHERE name LIKE ?", (f"%{q}%",), ).fetchall() else: rows = conn.execute( "SELECT path, name, tags FROM files LIMIT 50" ).fetchall() return [ {"path": r[0], "name": r[1], "tags": r[2].split(",") if r[2] else []} for r in rows ] def collect_stats(): with get_conn() as conn: total = conn.execute("SELECT COUNT(*) FROM files").fetchone()[0] rows = conn.execute("SELECT tags FROM files").fetchall() counter = {} for row in rows: if not row[0]: continue for tag in row[0].split(","): counter[tag] = counter.get(tag, 0) + 1 top_tags = sorted(counter.items(), key=lambda x: x[1], reverse=True)[:20] return {"total": total, "top_tags": top_tags} @app.on_event("startup") def on_startup(): ROOT_DIR.mkdir(exist_ok=True) scan_ideas() @app.get("/api/search") def api_search( tag: str = Query("", description="按标签过滤"), q: str = Query("", description="按文件名关键词过滤"), ): return query_files(tag=tag, q=q) @app.get("/api/stats") def api_stats(): return collect_stats() @app.post("/api/rescan") def api_rescan(): count = scan_ideas() return {"scanned": count} if __name__ == "__main__": uvicorn.run(app, host="127.0.0.1", port=8000)

这里有几个设计点需要解释：

• 正则TAG_RE支持中英文标签，也支持下划线、短横线和数字。文件名中的#Oai、#Fara、#Venus都会被自动提取。
• 扫描采用ROOT_DIR.rglob("*")，会递归处理所有子目录里的文件，但不会读取文件内容，因此速度很快。
• 每次重扫都会清空旧表再写入新数据，对中小规模素材库足够用。如果想做增量索引，需要在后续版本里比较文件修改时间和路径。
• 搜索接口支持tag和q两个参数，tag用于按标签精确过滤，q用于按文件名模糊搜索。

4.2 启动服务

在项目根目录执行：

python main.py

看到Uvicorn running on http://127.0.0.1:8000说明启动成功。这时可以直接用浏览器访问 FastAPI 自带接口文档：

http://127.0.0.1:8000/docs

docs页面是 FastAPI 自动生成的 Swagger 文档，所有接口都可以在页面上点击测试，不需要额外写客户端工具。如果你更习惯看原始 JSON 接口，也可以直接访问：

http://127.0.0.1:8000/api/stats

首次启动会自动创建ideas目录，并且立即执行一次全量扫描。如果目录是空的，stats接口会返回total为 0。

5. 功能测试与效果验证

5.1 准备测试素材

先创建几个带标签的测试文件。注意：Windows 文件名不能包含/和|，因此示例中的原始命名需要做一点转义，我把这类分隔符换成短横线和空格。

cd ideas touch "酣睡的猫 - Just an idea #Oai #Fara #Venus.txt" touch "随手涂鸦 #Oai #idea.png" touch "项目构思 #Fara.md" touch "情绪板 #Oai #Venus.mp3" touch "未命名灵感 001.txt" cd ..

这只是模拟数据，实际使用中你可以把任意图片、视频、PDF、音频文件放入ideas目录。

5.2 触发重扫

由于服务在启动时已经扫描过一次，新添加的文件不会自动进入索引。需要手动触发重扫：

curl -X POST "http://127.0.0.1:8000/api/rescan"

预期输出：

{ "scanned": 5 }

如果返回 5，说明 5 个文件都被正确扫描。这里有 1 个文件没有#标签（未命名灵感 001.txt），它也会被录入索引，只是tags为空数组。这种设计能保证所有文件都能被搜到，不会因为缺标签而丢失。

5.3 按标签搜索

用tag参数过滤：

curl "http://127.0.0.1:8000/api/search?tag=Oai"

预期结果会返回包含#Oai的三个文件：

[ { "path": "ideas/情绪板 #Oai #Venus.mp3", "name": "情绪板 #Oai #Venus.mp3", "tags": ["Oai", "Venus"] }, { "path": "ideas/酣睡的猫 - Just an idea #Oai #Fara #Venus.txt", "name": "酣睡的猫 - Just an idea #Oai #Fara #Venus.txt", "tags": ["Oai", "Fara", "Venus"] }, { "path": "ideas/随手涂鸦 #Oai #idea.png", "name": "随手涂鸦 #Oai #idea.png", "tags": ["Oai", "idea"] } ]

注意，搜索是大小写敏感的，因为 SQLite 的LIKE默认对 ASCII 是大小写不敏感的，但对中文和全角符号没有影响。在这个场景下，Oai和oai都会被匹配到。

5.4 按文件名关键词搜索

如果你不记得标签，只记得文件名里有“情绪”两个字，可以用q参数：

curl "http://127.0.0.1:8000/api/search?q=情绪"

预期返回：

[ { "path": "ideas/情绪板 #Oai #Venus.mp3", "name": "情绪板 #Oai #Venus.mp3", "tags": ["Oai", "Venus"] } ]

这个接口对中文文件名兼容良好，前提是操作系统、终端和 Python 环境都使用 UTF-8 编码。

5.5 查看标签统计

调用统计接口：

curl "http://127.0.0.1:8000/api/stats"

预期输出是一个包含总数和 Top 标签列表的对象：

{ "total": 5, "top_tags": [ ["Oai", 3], ["Venus", 2], ["Fara", 2], ["idea", 1] ] }

统计接口在批量整理时很有用。比如你想知道自己最近收集的素材里哪些标签最多，可以直接用这个接口做数据可视化。

5.6 判断成功的关键标准

一套完整的验证流程是否通过，按下面四点判断：

1. 服务能正常启动，/docs页面能打开。
2. /api/rescan返回的scanned数量与目录实际文件数一致。
3. 按tag搜索时，返回结果包含所有带对应标签的文件。
4. 按q搜索时，中文关键词能正常匹配。

如果这四点都满足，说明核心链路已经跑通。

6. 接口 API 与批量任务

6.1 接口说明

当前项目一共暴露了三个接口：

如果你希望接入自己的自动化流程，Python 里可以直接用requests调用：

import requests base_url = "http://127.0.0.1:8000" # 触发重扫 res = requests.post(f"{base_url}/api/rescan", timeout=20) print(res.json()) # 按标签搜索 res = requests.get( f"{base_url}/api/search", params={"tag": "Oai"}, timeout=5, ) print(res.json()) # 获取统计 res = requests.get(f"{base_url}/api/stats", timeout=5) print(res.json())

6.2 批量任务的常见思路

这个项目的批量任务不是传统意义上的“批处理图片”，而是“批量扫描和索引”。日常使用时，你不需要频繁手动调用 rescan，可以通过三种方式把重扫变成定时任务：

第一种是系统计划任务。在 Linux 下用 crontab：

# 每天凌晨 2 点重扫一次 0 2 * * * cd /home/user/idea-index && curl -X POST http://127.0.0.1:8000/api/rescan

第二种是 Windows 任务计划程序。在 Windows 上创建一个基本任务，启动程序设为cmd.exe，参数填：

/c "curl -X POST http://127.0.0.1:8000/api/rescan"

第三种是自己写一个 Python 定时脚本，放在后台进程里：

import time import requests while True: try: requests.post("http://127.0.0.1:8000/api/rescan", timeout=10) except Exception as e: print("rescan error:", e) time.sleep(3600)

这里要注意，如果多个定时任务同时触发重扫，SQLite 可能会报database is locked。建议只保留一个定时入口，或者把重扫间隔拉到 1 小时以上。

6.3 扩展批量处理

如果后续需求不只是索引，而是要批量重命名文件，也可以在scan_ideas之前加入一个命名清理步骤。比如把文件名里的|替换成-，把/替换成_，再写回文件系统，然后再建立索引。这种做法适合历史文件命名混乱、需要先统一规范的场景。

7. 资源占用与性能观察

7.1 如何观察资源占用

启动服务后，可以用系统自带命令观察进程资源占用。

Linux 下：

ps aux | grep python

Windows 下可以在任务管理器中找到python.exe进程，查看内存占用。

实际占用需要以本机测试为准，但从项目架构看，扫描过程是单线程，只在执行rescan时会有短暂 CPU 消耗；搜索时只是执行一个简单的 SELECT 查询，内存和 CPU 占用都极低。几百个文件、几个子目录的场景，整个索引库也就在几 MB 以内。

7.2 影响性能的关键因素

影响扫描速度的主要变量是文件数量，而不是文件大小。因为scan_ideas只读取文件名和文件元数据，不会打开图片或视频内容。如果你有 10 万个文件在同一个目录下，rglob遍历时间会明显增加，但一般内容创作者的前期素材规模不会到这个量级。

另外，SQLite 的 LIKE 查询使用%tag%时无法命中普通索引，因为这是前缀模糊匹配。如果文件量达到数万级别，建议增加一张 tags 关联表，用标签 ID 精确查询，而不是在文本字段上做 LIKE。这样查询响应时间可以从上百毫秒降到个位数毫秒。

7.3 降低资源占用的建议

• 不要把索引目录放在网络盘映射目录上，本地 SSD 效果最好。
• 在定时重扫任务中增加文件修改时间判断，只更新有变化的文件。
• 如果素材目录里包含非常大的视频文件，扫描过程可以忽略文件大小，只读取文件名，不影响速度。

8. 常见问题与排查方法

8.1 端口冲突处理

如果 8000 端口已被其他服务使用，可以临时换一个端口：

python main.py --port 8001

但上面代码里没有实现命令行参数解析，需要直接改uvicorn.run(app, host="127.0.0.1", port=8000)里的port，或者用环境变量动态读取。更简单的办法是启动后换一个入口：

uvicorn main:app --host 127.0.0.1 --port 8001

这样不用改代码也能换端口，FastAPI 会在启动时自动执行startup事件完成扫描。

8.2 索引数据重置

当你发现索引数据明显不准确时，最省事的做法是删除本地数据库文件，然后重启服务：

rm idea_index.db python main.py

启动时scan_ideas()会重新创建空数据库并全量扫描，这个过程是幂等的，不会对原素材造成任何影响。

9. 最佳实践与使用建议

9.1 统一命名规范

素材管理的效率一半靠工具，一半靠规则。建议从一开始就规定文件名格式，例如：

作者名 - 内容描述 #场景 #角色 #情绪.扩展名

对应到示例：

酣睡的猫 - Just an idea #Oai #Fara #Venus.txt

这里#Oai可以视为来源或风格标签，#Fara是角色或项目名，#Venus是用途标签。统一规范后，标签解析的准确率和后续检索效率都会大幅提升。

9.2 保留最小可运行配置

把main.py、ideas目录和上面的命名规则放进一个 README 文档，至少包括：为什么用这个方案、目录放哪里、如何启动、如何重扫。这样即使半年后机器换人，也能快速恢复。

9.3 定期做增量扫描

不要依赖启动时的自动扫描。建议把/api/rescan挂到系统计划任务里，每天或每小时执行一次。这样新素材放进去后，第二天就能被检索到。

9.4 批量任务加日志和错误处理

如果从单机使用走向自动化脚本，建议在 rescan 调用时增加日志。比如记录每次触发的开始时间、扫描数量、失败任务数和耗时。这些日志能帮你判断是实时触发失败，还是素材目录本身有问题。

import logging import time logging.basicConfig(level=logging.INFO) start = time.time() res = requests.post("http://127.0.0.1:8000/api/rescan", timeout=20) logging.info("rescan result=%s, elapsed=%.2fs", res.json(), time.time() - start)

9.5 涉及版权和肖像的素材必须授权

内容创作场景中，最常见的风险来自外部素材。即使只是在本地建立索引，也建议在文件名中注明来源和授权状态。例如：

Oai_授权截图_可用于灵感参考 #Oai #授权

没有明确授权的视频片段、人物照片、配音素材，不要混入商用素材目录。这是基本的合规意识。

9.6 对外提供接口时限制访问范围

FastAPI 默认绑定的地址是127.0.0.1，只有本机能访问。如果希望内网其他设备访问，需要修改启动参数：

uvicorn main:app --host 0.0.0.0 --port 8000

但此时必须确认内网可信，否则任何人都能读取你的文件路径信息。更稳妥的做法是在前面加一层简单 API Key 校验，或者继续使用本机回环地址，通过局域网共享目录的方式访问素材文件。

10. 总结与下一步

最值得尝试的点在于：这个方案能把本地散乱文件的标签自动结构化，让“灵感创意文件”不再是只能靠人工记忆管理的一堆碎片。首次运行只需要 5 分钟，之后所有带#标签的素材都会进入统一索引。

最先应该验证的是扫描和搜索链路。准备好几个测试文件，先执行/api/rescan，再用curl或浏览器访问/api/search?tag=Oai，确认返回路径和标签全部正确。跑通这条链路，后面加定时任务、接 OCR、做 WebUI 都是顺理成章的事。

最容易踩的坑有三个：一是文件名包含/、|等非法字符，导致 Windows 上创建失败；二是新增文件后忘记重扫，搜索结果缺失；三是把多个定时任务同时指向同一个 SQLite 数据库，导致锁冲突。前两个在本文的排查表格里都可以找到对应方案，第三个只要保留单一定时入口就能解决。

后续如果想继续扩展，可以考虑三个方向：一是把文件名标签之外的内容也纳入索引，比如通过 OCR 识别图片内文字；二是增加缩略图预览，直接在网页里看素材；三是增加反向索引表，把标签拆成关系数据，支持更精确的多标签组合查询。到这一步，这就不再是一个临时小脚本，而是一个完整的本地灵感资产检索系统了。