Skip to content
soulmaoPublic

About

TagSort 是一个本地优先的图片 / 视频智能标签管理工具,拥有一些额外功能

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

TagSort

TagSort 是一个本地优先的图片 / 视频智能标签管理工具。它会扫描本地媒体目录,把文件信息、缩略图、视频抽帧、LLM 分析结果和标签关系保存到 SQLite 数据库中,并提供可搜索、可审核、可导出的前端界面。

项目目标很简单:让个人媒体库在不移动、不改写原文件的前提下,获得可检索的中文描述、标签、敏感内容提示和跨平台链接导出能力。

当前版本为 0.9.1。发行版本以 backend/pyproject.toml 为唯一来源, 用于 FastAPI、CLI、health 和便携包文件名;frontend/package.json 与 backend/app/version.py 的源码回退值必须保持同步。

项目亮点

  • 本地优先:原始图片和视频只读访问,不移动、不重命名、不写回。
  • 图片 / 视频统一管理:支持图片分析、视频抽帧、视频级标签和片段级信息。
  • OpenAI 兼容视觉模型:通过 OpenAI SDK 调用兼容 /v1/chat/completions 的视觉 LLM 服务。
  • 候选审核工作台:AI 新发现的标签和维度先进入候选中心,可查看样本、相似正式项和重复候选,并支持筛选、编辑后批准、拒绝、合并与批量审核。
  • 轻量语义检索:对描述、视觉摘要、标签元数据和文件名进行本地相关性排序,提供关键词、语义和混合三种搜索模式,无需额外向量数据库。
  • 标签库治理:支持标签 / 维度合并、别名归一化、重复候选识别及安全永久删除;合并会迁移媒体和视频片段关联,并删除已被吸收的源项。
  • 敏感标签保护:sensitivity_level != 'none' 的标签不会自动晋升,避免污染正式标签库。
  • 任务队列:扫描、抽帧、角色识别、常规分析、高级分析、回填和导出都通过 SQLite-backed JobWorker 执行。
  • 实时进度:任务进度通过 SSE 接口 /api/v1/jobs/{id}/events 推送。
  • 角色扮演(Roleplay):基于媒体高级视觉分析结果,与识别出的角色进行沉浸式对话。支持 SSE 流式回复、思考过程(reasoning)展示、消息重新生成与版本切换、消息编辑、图片消息、自定义头像上传和上下文 Token 用量监控。
  • 跨平台本地导出:Windows 使用 .lnk,Linux 使用符号链接,不复制原始媒体。
  • 可追溯分析:每次 LLM 调用都会写入 analysis_runs,保留模型、prompt、原始输出和解析结果。

适合场景

  • 本地图片、视频素材库整理。
  • 个人收藏、灵感图库、参考资料库检索。
  • 基于视觉 LLM 的自动标签实验。
  • 对媒体文件生成中文描述、质量标记和敏感内容提示。
  • 按搜索条件批量导出本地链接,而不是复制原始文件。

技术栈

层级 技术
后端 Python 3.11+、FastAPI、SQLAlchemy 2.0 async、aiosqlite、Pydantic
数据库 SQLite,默认路径 data/db/tagsort.db
任务队列 SQLite jobs 表 + FastAPI lifespan 内置 JobWorker,支持 7 类任务
LLM OpenAI Python SDK,兼容 OpenAI 风格视觉模型接口
图片处理 Pillow、imagehash
视频处理 FFmpeg 命令行,使用 list args 调用,不使用 shell=True
前端 React 18、TypeScript、Vite、TanStack Router、TanStack Query、Tailwind
导出 Windows .lnk(pywin32)/ Linux 符号链接

实现方法概览

TagSort 是一个前后端分离的双包 monorepo:

TagSort
├── backend/      FastAPI API、SQLAlchemy 模型、任务 worker、LLM 调用
├── frontend/     React + Vite 前端应用
├── docs/         API、数据库、任务、LLM、前端等设计文档
├── data/         本地运行时数据,默认不进入 Git
└── launch.py     一键启动脚本

核心流程:

  1. 用户配置扫描目录和 LLM 连接信息。
  2. 后端扫描图片 / 视频文件,计算文件哈希、感知哈希、媒体信息。
  3. 视频文件通过 FFmpeg 抽取代表帧,帧缓存保存在 data/cache/。
  4. 后台任务调用视觉 LLM,生成描述、标签、属性、质量信息和敏感内容判断。
  5. 结果写入 SQLite;新标签和新维度先进入候选机制,敏感标签保持人工审核优先。
  6. 用户在候选中心查看证据样本、相似项和重复候选,再进行批准、拒绝、合并或批量审核。
  7. 媒体库可按结构化条件筛选,也可对描述、视觉摘要、标签和文件名进行关键词或轻量语义检索。
  8. 可选:对媒体执行高级分析(Advanced Analysis),识别画面中的角色、场景、关系,并进入角色扮演会话。
  9. 用户可以保存搜索条件,并按条件导出 Windows 快捷方式或 Linux 符号链接。

后台 Worker 支持的任务类型:

job_type 用途
scan 扫描本地媒体目录
frame_extract 为视频抽取分析帧
character_recognize 用本地 ONNX/imgutils 识别图片或视频帧中的角色
analyze 执行常规图片 / 视频视觉分析
advanced_analyze 执行角色、场景和关系的高级分析
backfill 按当前 taxonomy 回填历史媒体
export 按保存搜索生成平台链接

依赖要求

  • Python 3.11+;完整角色识别和发行构建固定使用 Python 3.12.13
  • Node.js 22
  • pnpm 11.9.0
  • uv(源码后端依赖与锁文件)
  • FFmpeg,可在 PATH 中访问或通过 FFMPEG_DIR 指定
  • 一个 OpenAI 兼容视觉 LLM 服务

后端 Python 依赖见 backend/pyproject.toml 与 backend/uv.lock,前端依赖见 frontend/package.json 与 frontend/pnpm-lock.yaml。 角色识别依赖 dghs-imgutils 0.19 当前要求 numpy<2,建议为该功能使用 Python 3.11 或 3.12;Python 3.13 可运行主项目,但启动器不会自动安装角色识别依赖。

快速启动

先创建可复现的源码环境:

uv sync --project backend --locked --extra dev
cd frontend
pnpm install --frozen-lockfile
cd ..

从项目根目录、通过 uv 管理的后端环境运行:

uv run --project backend python launch.py dev

启动成功后访问:

  • 前端:http://localhost:5173
  • 后端:http://localhost:8000
  • API 文档:http://localhost:8000/docs

其他启动方式:

uv run --project backend python launch.py all
uv run --project backend python launch.py dev
uv run --project backend python launch.py backend
uv run --project backend python launch.py preview
uv run --project backend python launch.py --skip-install

不传模式时默认使用 all;all 与 dev 都会启动后端和 Vite 开发服务器。 backend 只启动 API,preview 构建前端并由 FastAPI 在 8000 端口提供同源预览。 如果已经激活 backend/.venv,可以把上述 uv run --project backend 省略。 启动器不会安装后端依赖、修改全局 Python 环境,也不会结束占用端口的其他进程。

便携发行包

Windows 10/11 x64 与 Ubuntu 22.04+ x64 可以使用 GitHub Release 中的 one-folder 压缩包,目标机器无需安装 Python、Node.js 或 FFmpeg:

# Windows
.\TagSort.exe
.\TagSort.exe doctor --json
.\TagSort.exe --data-dir D:\TagSortData

# Linux
./TagSort
./TagSort doctor --json
./TagSort --data-dir /srv/tagsort-data

发行构建、数据目录、FFmpeg 许可证和限制见 docs/deployment.md。

手动开发

后端:

cd backend
uv run python -m uvicorn app.main:app --reload --port 8000

前端:

cd frontend
pnpm dev

Vite 会把 /api 代理到 http://localhost:8000。

配置说明

TagSort 有两类配置来源:

  1. 启动配置:按 CLI > 环境变量 > 应用根目录 .env > 默认值读取。
  2. 运行时配置:存储在 SQLite 的 settings 表中,通过设置页面和 Settings API 读写。

常见 .env 示例:

TAGSORT_DATA_DIR=./data
TAGSORT_HOST=127.0.0.1
TAGSORT_PORT=8000
# DATABASE_URL=sqlite+aiosqlite:///D:/TagSortData/db/tagsort.db
# FFMPEG_DIR=C:/Tools/ffmpeg/bin

LLM Provider、模型和密钥属于运行时配置,优先通过设置页面或 Settings API 管理, 并保存在 SQLite settings / llm_providers 表中。db_path 不是可写设置;有效数据 目录和数据库路径可从 /api/v1/system/capabilities 只读查询。

检查命令

后端检查从项目根目录运行:

uv run --project backend pytest backend/tests
uv run --project backend ruff check --config backend/pyproject.toml backend/app backend/tests packaging
uv run --project backend mypy --config-file backend/pyproject.toml backend/app

前端检查从 frontend/ 运行:

pnpm build
pnpm lint

当前基线检查包括:

  • uv run --project backend pytest backend/tests
  • uv run --project backend ruff check --config backend/pyproject.toml backend/app backend/tests packaging
  • uv run --project backend mypy --config-file backend/pyproject.toml backend/app
  • pnpm build
  • pnpm lint

pnpm build 目前会提示主 chunk 超过 500 kB,这是体积优化提醒,不是构建失败。

数据安全与 Git 忽略

以下内容不会提交到 Git:

  • data/ 下的数据库、缓存、抽帧、日志和临时文件。
  • .env、.env.local、本地密钥和 secret 文件。
  • 本地媒体样例,如 .mp4、.jpg、.png 等。
  • 导出的 .lnk / 符号链接和本地导出目录。
  • Python / Node 缓存和构建产物。

data/.gitkeep 是唯一应提交的数据目录占位文件。若运行时文件曾被加入 Git 索引, 应先用 git status 和 git ls-files data 精确确认目标,再只移除对应文件;不要对 整个 data/ 执行会同时删除占位文件的批量命令。

主要目录

路径 说明
backend/app/main.py FastAPI 入口和 lifespan worker
backend/app/api/ REST API 路由
backend/app/models/ SQLAlchemy 数据模型
backend/app/schemas/ Pydantic schema
backend/app/tasks/ 扫描、抽帧、常规 / 高级分析、回填、导出任务
backend/app/llm/ LLM 客户端、prompt、解析和输出 schema
frontend/src/pages/ 前端页面装配层
frontend/src/features/ 按业务能力组织的前端模块、Hooks 和页面专用组件
frontend/src/api/ 前端 API 客户端
docs/ 项目设计和接口文档

媒体库前端采用 feature 模块组织,MediaLibraryPage.tsx 只负责路由同步、列表查询和组件装配:

frontend/src/features/media-library/
├── mediaFilterCodec.ts            路由参数 → API filters → savedQuery
├── useMediaLibraryActions.ts      扫描、分析、暂停、预处理和批量 mutation
├── useMediaLibrarySelection.ts    跨页媒体选择状态
├── useMediaLibraryPagination.ts   分页与滚动位置恢复
├── MediaActionToolbar.tsx         页面操作和视图切换
├── MediaFilterPanel.tsx           URL 驱动的组合筛选
├── MediaResults.tsx               网格、宽卡片和列表结果
├── ScanMediaDialog.tsx            扫描目录弹窗
├── SaveMediaSearchDialog.tsx      保存搜索弹窗
└── BatchMediaStatusDialog.tsx     批量状态弹窗

列表查询和保存搜索都通过同一个 mediaFilterCodec 生成条件,避免新增筛选字段时出现查询、保存和导出语义漂移。

前端路由

路由 页面
/ 仪表盘
/media 媒体库
/media/:id 媒体详情与高级分析
/tags 标签库
/dimensions 维度管理
/candidates 候选中心
/characters 角色库与角色候选审核
/characters/:id 角色详情与关联媒体
/jobs 任务队列
/exports 平台链接导出管理
/settings 系统与 LLM Provider 设置
/roleplay 角色扮演会话列表
/roleplay/new 创建角色扮演会话
/roleplay/:sessionId 角色扮演会话详情

数据库说明

当前项目使用 SQLite。数据库表在启动时由 app/database.py:init_db() 通过 Base.metadata.create_all() 创建。

backend/alembic/ 目录存在,但当前没有迁移文件。除非明确需要,不要新增 Alembic migration。

主要表包括:

  • media_files
  • dimensions
  • tags
  • media_tags
  • analysis_runs
  • tag_candidates
  • dimension_candidates
  • characters
  • character_embeddings
  • character_profiles
  • character_candidates
  • media_characters
  • video_frames
  • video_segments
  • jobs
  • job_logs
  • settings
  • llm_providers
  • saved_searches
  • shortcut_exports
  • advanced_analyses
  • roleplay_sessions
  • roleplay_messages
  • roleplay_avatars

当前进度

当前开发范围内的核心审核、检索和标签库治理能力已经落地:

  • 候选标签 / 候选维度的搜索、筛选、排序、批量批准和批量拒绝。
  • 候选标签展示证据样本、相似正式标签、相似候选及推荐操作。
  • 候选批准前可修改名称、维度、描述、别名和敏感等级。
  • 候选可合并到正式标签或其他待审候选,并自动迁移、去重媒体关联。
  • 标签改名保留旧身份为别名;标签合并迁移媒体 / 视频片段关联并删除源标签。
  • 维度合并移动标签、合并同名标签并删除源维度;历史空禁用项可安全永久删除。
  • 修复维度自动判定产生重复括号后缀的问题,并在启动时清理已有异常显示名。
  • 媒体库提供关键词、语义、混合三种模式,返回相关度及命中来源。
  • 媒体库完成 feature 化拆分,统一筛选转换,并隔离服务端动作、选择、分页和弹窗状态。
  • 标签库导入导出、taxonomy diff 和更完整的批量维护工具。
  • 搜索与审核流程的前端端到端测试。

尚未实现或仍不稳定的功能

Pre-release 还有一些明确边界:

  • 尚未提供完整 Alembic 迁移流程。
  • 尚未支持多用户、登录、权限和远程部署安全加固。
  • 尚未支持 PostgreSQL 和生产数据库迁移工具。
  • 尚未支持多进程或分布式 worker。
  • 当前“语义搜索”是本地加权 token / 中文 n-gram 相关性检索,尚未接入 embedding 模型或向量索引。
  • 标签导入导出、taxonomy diff、批量维护工具还不完整。
  • 视频时间轴的精确片段编辑和人工审核流程还需增强。
  • 失败任务的重试策略和错误恢复仍需要完善。
  • 缩略图 / 缓存管理 UI 还不完整。
  • Windows/Linux 已提供便携压缩包,但尚未提供桌面安装器和自动更新。
  • 前端端到端测试覆盖仍不足。

后续路线

0.9.x:工作流收尾与稳定性

  • 增强失败任务重试和错误展示。
  • 增强视频时间轴标签和 review 状态。
  • 增加缓存清理和临时文件生命周期检查。
  • 增加标签库导入导出、taxonomy diff 和批量编辑。
  • 改进保存搜索管理。
  • 为搜索与审核流程增加前端集成 / 端到端测试。
  • 评估 embedding + 向量索引方案,作为大型媒体库的可选检索后端。

1.0.0:稳定本地版本

  • 冻结 SQLite schema,或引入正式迁移方案。
  • 提供更完整的本地安装 / 打包流程。
  • 编写备份、恢复和升级文档。
  • 完成隐私与数据安全检查清单。
  • 整理稳定版用户文档和 release notes。

文档

  • docs/spec.md:系统规格
  • docs/database.md:数据库 schema
  • docs/api.md:REST API 合约
  • docs/llm.md:LLM prompt 与输出 schema
  • docs/tasks.md:任务队列和 worker
  • docs/frontend.md:前端页面和组件说明
  • docs/deployment.md:源码环境、便携构建和发布流程
  • docs/agent-prompts.md:按难度拆分的 agent 任务描述

About

TagSort 是一个本地优先的图片 / 视频智能标签管理工具,拥有一些额外功能

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages