Material Analyzer

用于将 FloorVisualizer 的地板 SKU 离线预处理为可复现 MaterialAssets 的流水线。

运行

go run . -limit 10 -workers 4 -verbose

CLI 默认读取：

..\FloorVisualizer\data\products

并输出到：

MaterialAssets\<safe-sku>\

常用参数示例：

go run . -data-dir "D:\go-demo\FloorVisualizer\data\products" -output-dir MaterialAssets
go run . -sku "I966106LP" -force -verbose
go run . -limit 100 -workers 8
go run . -retry 2 -strict

Provider 参数示例：

go run . -embedding-provider local -semantic-provider local
go run . -embedding-provider http -embedding-url http://127.0.0.1:5200
go run . -semantic-provider http -semantic-url http://127.0.0.1:5300 -semantic-model gemini-3-pro-image
go run . -semantic-provider local,internvl3 -semantic-url http://127.0.0.1:5300

当配置多个 semantic provider 时，分析器会按字段做语义融合，并根据置信度加权。

模型依赖

本项目代码仓库不包含大模型权重。InternVL3-8B 应作为外部模型单独管理，例如放在独立 Git LFS 仓库、Hugging Face 仓库或团队对象存储中。

推荐本地目录结构：

D:\go-demo\
  Material Analyzer\        # 本项目代码仓库
  data\
    InternVL3-8B\           # 外部模型目录，不提交到本项目仓库

导入模型时，将模型仓库或下载后的权重放到：

D:\go-demo\data\InternVL3-8B

模型目录至少需要包含：

config.json
generation_config.json
model.safetensors.index.json
model-00001-of-00004.safetensors
model-00002-of-00004.safetensors
model-00003-of-00004.safetensors
model-00004-of-00004.safetensors
tokenizer.json
tokenizer_config.json
vocab.json
merges.txt

如果模型放在其他位置，通过环境变量指定：

set INTERNVL3_MODEL_PATH=D:\path\to\InternVL3-8B

模型目录中有本项目专用说明：

D:\go-demo\data\InternVL3-8B\README_MaterialAnalyzer.md

输出

每个处理完成的 SKU 会生成：

preview.jpg
thumbnail.jpg
material.json
histogram.json
embedding.bin
manifest.json

material.json 包含：

• 分析器版本信息：analyzer_version、feature_schema、generator、generated_at
• 通用颜色特征：主/次 RGB、LAB、HSV、亮度、对比度、饱和度
• 纹理特征：熵、Sobel 频率、边缘密度、方向方差、LBP 均匀度、GLCM 统计
• 规范化统计：平均/中位 RGB、颜色方差、纹理方差、亮度分布、梯度直方图
• 语义特征：描述、材质类型、表面处理、纹理类型、颜色族、风格、变化程度、光泽等级、标签
• 材质适配器输出，以及木材、瓷砖、仿石瓷砖、乙烯基地板和通用材质的字段置信度
• 校验状态
• 二进制向量的 embedding manifest

manifest.json 会列出所有文件和资产校验状态。

批量运行会写入：

MaterialAssets/benchmark.json
MaterialAssets/failures.json

embedding.bin 存储两个拼接的 float32 向量。默认 local provider 会生成确定性的 fallback 向量：

• dino_v2_texture_local：颜色与纹理指纹
• clip_semantic_local：元数据与语义哈希指纹

如果使用可选模型服务，则会生成：

• dinov2_texture：facebook/dinov2-large，1024 维，已归一化
• clip_visual：ViT-L/14，768 维，已归一化

可选模型服务

Go CLI 可以调用本地 DINOv2/CLIP 模型服务：

cd tools/model_server
python -m pip install -r requirements.txt
python server.py

然后运行：

go run . -sku I966106LP -force -embedding-provider http -embedding-url http://127.0.0.1:5200

第一次请求会通过 Hugging Face 下载模型权重，可能需要一些时间。

InternVL3 语义服务

InternVL3-8B 用于本项目的视觉语义分析。它不会生成 embedding，而是读取 preview.jpg 和产品元数据，输出结构化材质语义字段。

启动本地 InternVL3 语义服务：

cd tools/vision_server
python -m pip install -r requirements.txt
set INTERNVL3_MODEL_PATH=D:\go-demo\data\InternVL3-8B
python server.py

服务默认监听：

http://127.0.0.1:5300/semantic

然后让分析器连接该服务：

go run . -sku I966106LP -semantic-provider internvl3 -semantic-url http://127.0.0.1:5300

也可以和本地规则 provider 组合使用：

go run . -semantic-provider local,internvl3 -semantic-url http://127.0.0.1:5300

常用环境变量：

INTERNVL3_MODEL_PATH        模型目录，默认 D:\go-demo\data\InternVL3-8B
INTERNVL3_PORT              服务端口，默认 5300
INTERNVL3_IMAGE_SIZE        输入图块尺寸，默认 448
INTERNVL3_MAX_TILES         最大图块数，默认 4
INTERNVL3_MAX_NEW_TOKENS    最大生成 token 数，默认 512
INTERNVL3_TEMPERATURE       生成温度，默认 0.0
INTERNVL3_LOAD_IN_8BIT      是否 8bit 量化加载
INTERNVL3_LOAD_IN_4BIT      是否 4bit 量化加载
INTERNVL3_USE_FLASH_ATTN    是否启用 flash attention

Material Intelligence

基于已有 MaterialAssets 构建 v3 知识层：

go run . intelligence -assets-dir MaterialAssets -output-root . -k 5

该命令会创建：

KnowledgeBase/knowledge.db
KnowledgeBase/similarity.json
PromptDataset/prompt_dataset.json
Statistics/statistics.json
Embeddings/embeddings.json
Fingerprints/fingerprints.json
GroundTruth/ground_truth.json
Regression/regression_report.json
Benchmarks/benchmark_vision.json
material_intelligence_summary.json

每个资产也会收到：

semantic.json
manifest.json

manifest.json 包含 SHA256、文件大小和文件时间戳，用于资产完整性校验。

使用基线资产库做回归对比：

go run . intelligence -assets-dir MaterialAssets -baseline-dir OldMaterialAssets

房间图识别

如果产品主材质图看起来像房间场景，分析器会标记：

"room_like": true

并使用图像下方的地面区域裁剪做特征提取。这样可以让流水线继续运行，同时也便于后续审计和清理这些资产。