# InternVL3-8B 在 Material Analyzer 中的使用说明

本目录存放 `InternVL3-8B` 模型文件。它是 Material Analyzer 的外部模型依赖，不应该提交到 `Material Analyzer` 项目仓库。

## 主要功能

`InternVL3-8B` 是视觉语言模型。在本项目中，它用于查看地板或瓷砖图片，并结合产品元数据生成结构化语义结果。

本项目使用它完成以下字段：

```json
{
  "description": "",
  "material_type": "",
  "surface_finish": "",
  "grain_type": "",
  "color_family": "",
  "visual_style": "",
  "variation": "",
  "gloss_level": "",
  "tags": [],
  "confidence": 0.0,
  "field_confidence": {}
}
```

这些结果会写入每个资产目录中的：

```text
semantic.json
material.json
```

## 本项目没有使用的能力

当前 Material Analyzer 只使用 InternVL3 做语义分析，不使用它生成图像 embedding。

图像 embedding 仍由以下 provider 负责：

- `local`：本地确定性颜色/纹理指纹
- `http`：可选 DINOv2/CLIP 模型服务

## 推荐仓库管理方式

建议将本目录作为独立模型仓库或 Hugging Face 模型仓库管理。不要把模型权重放进业务代码仓库。

如果使用 Git 管理该模型目录，需要启用 Git LFS，并跟踪大文件：

```bash
git lfs install
git lfs track "*.safetensors"
git lfs track "*.bin"
git add .gitattributes
```

## 本地放置路径

Material Analyzer 默认读取：

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

如果模型放在其他位置，需要在启动语义服务前设置：

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

## 启动语义服务

在 Material Analyzer 项目中运行：

```bash
cd D:\go-demo\Material Analyzer\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
```

## 在 Material Analyzer 中调用

回到 Material Analyzer 项目根目录：

```bash
cd D:\go-demo\Material Analyzer
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
```

## 注意事项

- 模型权重体积很大，普通 Git 不适合直接管理。
- 首次启动会加载多个 `.safetensors` 分片，耗时和显存占用都较高。
- 如果显存不足，可以尝试 `INTERNVL3_LOAD_IN_8BIT=true` 或 `INTERNVL3_LOAD_IN_4BIT=true`，但需要环境支持 bitsandbytes。
- 本项目语义服务接口只要求 `/semantic` 可用；业务代码不直接读取模型目录。