Art Center Server

面向画师参考图集的文本向量检索服务。

本项目是 Art Center 工作流中的“获取参考”阶段：接收整理后的文本需求，将文本转换为 SigLIP2 向量，并从 PostgreSQL/pgvector 向量库中检索最相近的参考图片路径。它配合预处理项目和 Blender 插件使用，可以把画师自己长期收集的大量参考图变成可搜索、可复用、可追溯的个人参考库。

整体工作流

Art Center 分为三个阶段：

1. 预处理：art_center-client

   • 将 bat 文件中的文件夹路径改为参考图集路径后运行。
   • 自动为图片生成向量、完成图片分类。
   • 对分类为动作的图片提取动作数据，生成动作库。
   • 目标是让消费级显卡也能完成本地处理，经测试 RTX 3060 可用。

2. 获取参考：本项目

   • 输入画师的需求文本。
   • 推荐在调用本服务前，先用 Gemini 等大模型把抽象需求改写为各类别下的英文短检索词，并控制在 64 tokens 以内。
   • 使用 google/siglip2-base-patch16-naflex 将文本转换为向量。
   • 在 pgvector 数据库中匹配相似图片，返回图片路径列表。
   • 当前代码接口返回路径列表；动作 JSON 可通过预处理阶段的路径约定关联，或在数据库中增加动作 JSON 字段后扩展接口返回。

3. 动作处理：art_center-plugin

   • 在 Blender 中启用插件。
   • 准备 A-POSE、带骨骼的模型，骨骼名称最好与插件约定一致。
   • 上传上一步关联到的动作 JSON，将动作应用到模型骨架。
   • 画师仍可在 Blender 中调整摄像机角度、构图、动作细节和模型姿态。

最终目标是：画师上传自己的图集后，用消费级显卡生成专属参考集与动作库；之后只需要用自然语言描述需求，就可以获取相关参考图和可应用到 3D 模型的参考动作。

项目特点

• 低门槛：工作流面向本地消费级显卡，不依赖高端训练服务器。
• 高定制：检索结果完全来自画师自己的参考图集。
• 可控可回溯：不是直接生成一张不可控的 AI 图片，而是找到已有参考图，并把动作转移到可微调的 3D 模型中。
• 检索精度稳定：文本和图片使用同一类向量空间匹配，适合在大规模参考图集中做语义搜索。

当前仓库职责

本仓库提供一个 FastAPI 服务：

• POST /search：输入文本和返回数量，输出匹配到的图片路径列表。
• vector.py：加载 SigLIP2 文本模型，并把文本转换为归一化向量。
• db.py：连接 PostgreSQL，使用 pgvector 的向量距离查询最相近图片。
• main.py：定义 API 入口，并在 8300 端口启动服务。

环境要求

• Python 3.10 或更新版本。
• PostgreSQL，并启用 pgvector 扩展。
• 已由预处理阶段写入的图片向量数据。
• PyTorch。请根据本机 CUDA/CPU 环境安装对应版本。
• 首次启动需要能访问或已缓存 Hugging Face 模型 google/siglip2-base-patch16-naflex。

db.py 使用 psycopg.connect() 的默认连接方式，因此会读取标准 PostgreSQL 环境变量：

export PGHOST=127.0.0.1
export PGPORT=5432
export PGDATABASE=art_center
export PGUSER=postgres
export PGPASSWORD=your_password

安装

python -m venv venv
source venv/bin/activate

# 先按本机环境安装 PyTorch，再安装项目依赖
pip install -r requirements.txt

Windows PowerShell 可使用：

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

数据库约定

当前查询代码默认存在 art_center 表，并至少包含以下字段：

• path：图片路径。
• vector：图片向量，类型为 pgvector 的 vector。

示例表结构如下。向量维度需要与预处理阶段生成的图片向量维度保持一致；SigLIP2 base 常见维度为 768，请以实际预处理输出为准。

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE IF NOT EXISTS art_center (
    id bigserial PRIMARY KEY,
    path text NOT NULL,
    vector vector(768) NOT NULL
);

CREATE INDEX IF NOT EXISTS art_center_vector_idx
ON art_center USING hnsw (vector vector_cosine_ops);

检索使用：

ORDER BY vector <=> query_vector

也就是按 cosine distance 从近到远排序。

启动服务

python main.py

默认监听：

http://127.0.0.1:8300

FastAPI 文档地址：

http://127.0.0.1:8300/docs

也可以直接使用 Uvicorn：

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

接口使用

搜索参考图

POST /search?prompt=dynamic%20running%20pose%20side%20view&limit=10

参数：

• prompt：检索文本。建议使用英文，并控制在 64 tokens 以内。
• limit：返回数量，默认 20。

示例：

curl -X POST "http://127.0.0.1:8300/search?prompt=dynamic%20running%20pose%20side%20view&limit=10"

返回：

[
  "D:/art_refs/action/run_001.png",
  "D:/art_refs/action/run_017.png"
]

推荐检索流程

直接把很长、很抽象的中文需求交给向量模型，效果通常不如先做一次结构化改写。推荐调用方先把画师需求整理成类别明确、语义集中的英文短文本，再调用本服务。

示例：

原始需求：
一个角色从低角度冲向镜头，身体前倾，动作有速度感，适合少年漫画分镜参考。

可用于检索的英文 prompt：
low angle dynamic running pose, leaning forward, strong motion, manga action reference

对于动作类参考，预处理阶段生成的动作 JSON 应与图片路径建立稳定关联，例如同名文件、相邻目录，或数据库中的 pose_json_path 字段。当前接口只返回图片路径；如需直接返回动作 JSON 路径，可以扩展 art_center 表和 db.py 的查询结果。

常见问题

启动时模型下载很慢

首次启动会加载 Hugging Face 模型。可以提前下载模型，或在离线环境中配置本地模型缓存。

数据库连接失败

检查 PGHOST、PGPORT、PGDATABASE、PGUSER、PGPASSWORD 是否正确，并确认 PostgreSQL 已启动、pgvector 扩展已安装。

搜索结果和需求无关

优先检查以下几项：

• 预处理阶段和本服务使用的 SigLIP2 模型是否一致。
• 图片向量和文本向量维度是否一致。
• 数据库中是否确实写入了参考图向量。
• prompt 是否过长、过抽象，或包含过多互相冲突的描述。
• 查询文本是否控制在 64 tokens 以内。

动作 JSON 没有直接返回

当前实现返回 path 列表。动作 JSON 可以由调用方根据图片路径关联，也可以在数据库中加入动作 JSON 路径字段，并把接口返回类型从 list[str] 扩展为包含图片路径和动作路径的结构。

目录结构

.
├── main.py           # FastAPI 服务入口
├── vector.py         # SigLIP2 文本向量生成
├── db.py             # PostgreSQL/pgvector 查询
├── requirements.txt  # Python 依赖
└── README.md

相关项目

• 预处理项目：nar-oah/art_center-client
• Blender 插件：nar-oah/art_center-plugin