# Material Analyzer

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

## 运行

```bash
go run . -limit 10 -workers 4 -verbose
```

CLI 默认读取：

```text
..\FloorVisualizer\data\products
```

并输出到：

```text
MaterialAssets\<safe-sku>\
```

常用参数示例：

```bash
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 参数示例：

```bash
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 仓库或团队对象存储中。

推荐本地目录结构：

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

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

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

模型目录至少需要包含：

```text
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
```

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

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

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

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

## 输出

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

```text
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` 会列出所有文件和资产校验状态。

批量运行会写入：

```text
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 模型服务：

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

然后运行：

```bash
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 语义服务：

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

服务默认监听：

```text
http://127.0.0.1:5300/semantic
```

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

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

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

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

常用环境变量：

```text
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 知识层：

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

该命令会创建：

```text
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
```

每个资产也会收到：

```text
semantic.json
manifest.json
```

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

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

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

## 房间图识别

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

```json
"room_like": true
```

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