From 6ee8a6d6f44b191d9ed1516f1d83636623862433 Mon Sep 17 00:00:00 2001
From: dindang <dindang@example.local>
Date: Mon, 27 Jul 2026 11:04:15 +0800
Subject: [PATCH] Add Material Analyzer model usage notes

---
 README_MaterialAnalyzer.md | 123 +++++++++++++++++++++++++++++++++++++
 1 file changed, 123 insertions(+)
 create mode 100644 README_MaterialAnalyzer.md

diff --git a/README_MaterialAnalyzer.md b/README_MaterialAnalyzer.md
new file mode 100644
index 0000000..700a571
--- /dev/null
+++ b/README_MaterialAnalyzer.md
@@ -0,0 +1,123 @@
+# 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` 可用；业务代码不直接读取模型目录。