Anomalib VLM-AD基于视觉语言模型的图像异常检测实现详解【免费下载链接】anomalibAn anomaly detection library comprising state-of-the-art algorithms and features such as experiment management, hyper-parameter optimization, and edge inference.项目地址: https://gitcode.com/GitHub_Trending/an/anomalib本文围绕 Anomalib 的vlm_ad模型模块anomalib.models.image.vlm_ad展开系统讲解VlmAd类如何通过 GPT-4o-mini、Ollama 上的 LLaVA、Hugging Face 上的 LLaVA 等视觉语言模型VLM以自然语言提示完成零样本zero-shot与少样本few-shot图像异常检测并给出可复制的构造参数、调用流程、后端接口定义与评估配置帮助你在无需训练的情况下快速接入 VLM 做缺陷/异常判断。一、模块定位用 VLM 做异常检测vlm_ad 模块的模块文档将自身定位为 Vision Language Model (VLM) based Anomaly Detection其核心思想是不训练专用异常检测网络而是利用具备视觉与语言理解能力的 VLM如 GPT-4V、LLaVA通过自然语言提示将待检测图像与参考正常图像进行比较从而判断图像是否异常。从源码结构看该模块由三层组成lightning_model.pyVlmAd主模型类继承自AnomalibModule负责对接 Anomalib 的 Engine/Trainer 生命周期backends/Backend抽象基类与三个具体实现ChatGPT、Huggingface、Ollama封装与不同 VLM 服务的通信细节utils.pyPrompt提示词数据类与ModelName模型名称枚举。该模型支持两种工作模式见 lightning_model.py 的模块文档Zero-shot零样本不需要参考图像Few-shot少样本使用k张参考正常图像为模型提供上下文。learning_type属性正是据此动态返回LearningType.ZERO_SHOT或LearningType.FEW_SHOTlightning_model.py#L212-L219即学习类型完全由k_shot参数决定而不需要训练阶段介入。二、支持的 VLM 模型ModelName 枚举模型名称由 utils.py 中的 ModelName 枚举统一定义构造VlmAd时传入字符串即可内部会通过ModelName(model)转换并校验枚举成员实际模型标识后端实现运行位置LLAMA_OLLAMAllavaOllama本地 Ollama 服务默认GPT_4O_MINIgpt-4o-miniChatGPTOpenAI APIVICUNA_7B_HFllava-hf/llava-v1.6-vicuna-7b-hfHuggingface本地推理VICUNA_13B_HFllava-hf/llava-v1.6-vicuna-13b-hfHuggingface本地推理MISTRAL_7B_HFllava-hf/llava-v1.6-mistral-7b-hfHuggingface本地推理其中三个 Hugging Face 模型被收录在 lightning_model.py#L52-L56 的ALLOWED_HF_MODELS白名单中——hf_model_revision参数只对这些模型生效对其它模型传入时仅记录警告并忽略。三、构造参数与使用示例VlmAd的构造函数签名lightning_model.py#L104-L114如下def __init__( self, model: ModelName | str ModelName.LLAMA_OLLAMA, api_key: str | None None, k_shot: int 0, hf_model_revision: str | None None, ) - None:各参数说明依据源码 docstring 与实现逻辑参数类型 / 默认值说明modelModelName \| str默认ModelName.LLAMA_OLLAMAVLM 模型名必须为上表中的枚举之一传入不支持的模型会抛出ValueError见 _setup_vlm_backend 的raise ValueError分支api_keystr \| None默认None需要鉴权的模型OpenAI所用 API keyk_shotint默认0参考正常图像数量为0时使用零样本模式hf_model_revisionstr \| None默认NoneHugging Face 模型的 revision/分支/提交哈希未指定时默认main并提示固定 commit 以保证可复现L133-L141模块官方示例vlm_ad/init.py#L10-L24展示了最小调用流程from anomalib.models.image import VlmAd from anomalib.data import MVTecAD from anomalib.engine import Engine # Initialize model and data datamodule MVTecAD() model VlmAd( modelgpt-4o-mini, api_keyYOUR_API_KEY ) # Predict using the Engine engine Engine() engine.predict(modelmodel, datamoduledatamodule) # doctest: SKIP类文档中另给出两类变体lightning_model.py#L80-L98# Few-shot approach with 3 reference images model VlmAd( modelgpt-4-vision-preview, # 文档示例写法当前枚举为 gpt-4o-mini api_keyYOUR_API_KEY, k_shot3 ) # Using a HuggingFace model with specific revision model VlmAd( modelllava-hf/llava-v1.6-vicuna-7b-hf, k_shot5, hf_model_revisionc916e6cdcd760b4cecd1dd4907f84ac649f93b23 )注意model的实际取值需以ModelName枚举为准OpenAI 后端固定使用gpt-4o-mini这个值发起请求chat_gpt.py#L156 中chat.completions.create(messagesmessages, modelself.model_name)。四、后端架构Backend 抽象与三个实现4.1 Backend 接口backends/base.py 定义了所有后端必须实现的接口__init__(model_name: str)初始化后端add_reference_images(image)为少样本学习添加参考图像predict(image, prompt) - str对单张图像执行预测返回 VLM 的文本响应num_reference_imagesproperty当前已存储的参考图像数量。VlmAd在初始化时通过静态方法 _setup_vlm_backend 按ModelName分派到对应后端LLAMA_OLLAMA → Ollama、GPT_4O_MINI → ChatGPT、白名单内的 HF 模型 →Huggingface其余情况抛出ValueError。4.2 ChatGPT 后端API key 解析与图像编码backends/chat_gpt.py 实现了对 OpenAI 的封装几个值得注意的实现细节API key 解析顺序_get_api_key1) 构造函数参数 → 2) 环境变量OPENAI_API_KEY→ 3).env文件需python-dotenv。三者均缺失时抛出ValueError并给出提示图像编码_encode_image_to_url将图像文件读取后做 base64 编码拼成data:image/ext;base64,...形式的数据 URLL179-L204直接随多模态消息发送无需上传文件预测消息结构predict若有参考图像先发一条包含全部参考图 few_shot 提示词的消息再发一条待测图 predict 提示词的消息最后取response.choices[0].message.content作为结果。4.3 Hugging Face 后端本地 LLaVA 推理backends/huggingface.py 面向本地部署的 LLaVA v1.6 系列延迟加载processor与model均为 property首次访问时才调用transformers.LlavaNextProcessor.from_pretrained与transformers.LlavaNextForConditionalGeneration.from_pretrained且都带上revisionself.model_revision以支持固定版本L116-L160参考图像以PIL.Image对象保存在self._ref_images中预测时用processor.apply_chat_template(messages, add_generation_promptTrue)组装对话把参考图与待测图一起送入model.generate(**inputs, max_new_tokens100)限制最长生成 100 个 tokenL197-L219未安装transformers时抛出ValueError并提示安装anomalib[vlm]。4.4 Ollama 后端本地服务调用backends/ollama.py 面向本地 Ollama 服务默认模型为llava运行前提模块文档说明Linux 下执行ollama serveMac/Windows 下启动 Ollama 应用add_reference_images与待测图均通过ollama.Image(valueimage)编码后放入消息的images字段最后调用ollama.chat(model..., messages...)并取response[message][content]L146-L178未安装ollamaPython 包时导入处定义的桩类会在实际调用时抛出ImportError提示uv pip install ollama或uv pip install anomalib[vlm]。五、提示词设计与 few-shot 参考图收集5.1 Prompt 数据类utils.py 中的 Prompt 是一个仅含两个字段的 dataclassfew_shotfew-shot 场景下描述参考正常图像的上下文提示词predict针对单张待测图像的判别提示词。VlmAd通过prompt属性lightning_model.py#L165-L184注入默认提示词predict 提示词要求模型先回答 YES异常或 NO正常然后给出理由例如YES: The image has a crack on the wall.few-shot 提示词声明参考图为 a few examples of normal picture without any anomalies要求模型用它们判断下一轮对话中的图像。5.2 参考图像的自动收集few-shot 模式下参考图像不是手工指定的而是在_setup钩子中从数据模块的训练集自动收集lightning_model.py#L146-L163触发条件k_shot 0且后端当前参考图数量不足k_shot收集方式遍历datamodule.train_dataloader()的每个 batch将batch.image_path逐张传给vlm_backend.add_reference_images凑满k_shot张即停止。这一设计意味着使用k_shot 0时必须提供带训练集正常图像的 datamodule参考图即取自该数据集。5.3 预测与标签解析validation_step/test_step/predict_step三个阶段统一委托给validation_stepL186-L210其逻辑非常直接对 batch 中每张图像调用vlm_backend.predict(img_path, self.prompt)原始文本写入batch.explanation将响应写入batch.pred_label文本以Y开头记为1.0异常否则0.0正常——即把 VLM 的 YES/NO 首字母作为硬分类依据。从源码结构看这是文本启发式解析若 VLM 未严格按要求以 YES/NO 开头会被默认判为正常0.0实际使用中需要留意模型响应格式的一致性。六、评估、导出限制与依赖6.1 评估器配置configure_evaluator返回只包含图像级F1Score字段pred_label/gt_label前缀image_的Evaluatorlightning_model.py#L250-L258。由于 VLM 输出的是文本判定而非连续异常分数该模型不参与像素级/区域级指标评估。6.2 其它约定无训练trainer_arguments返回空字典configure_transforms会忽略image_size每个后端有自己的图像处理并记录警告configure_post_processor返回NoneL220-L248不可导出to_torch/to_onnx/to_openvino三个导出入口统一打印 Exporting the model is not supported for VLM-AD model 警告后跳过L260-L273即该模型只能在线调用 VLM 完成推理不能像 PatchCore 那样导出为边缘可部署的静态模型。6.3 依赖与测试可选依赖vlmpyproject.toml#L73ollama0.4.0、openai、python-dotenv、transformers即pip install anomalib[vlm]/uv pip install anomalib[vlm]即可获得全部三个后端的 Python 依赖Ollama 服务本身需另行部署集成测试 tests/integration/model/test_models.py#L237-L239 对vlm_ad做了特殊处理将model.vlm_backend替换为MagicMock并让其predict返回YES: Because reasons...从而在离线环境下验证模型在 Anomalib 通用测试流程中的行为标签解析走 YES 开头 → 异常 的路径。七、小结与适用前提VlmAd的价值在于把异常检测转化为一次带视觉输入的大模型问答零样本模式下无需任何参考数据少样本模式下从训练集自动取k_shot张正常图作为上下文。使用前的关键前提按所选后端满足运行条件——OpenAI 需 API key参数 /OPENAI_API_KEY/.env三选一、Ollama 需本地服务、Hugging Face 需transformers与本地显存model取值必须是ModelName枚举中的五个标识之一否则构造即失败该模型输出为图像级 YES/NO 判定与文本理由无异常分数、无掩码、不可导出部署适合快速验证、解释性诊断或与规则系统结合的轻量检测场景对精度与延迟有严格要求的产线部署仍应考虑 PatchCore 等可导出的专用模型。【免费下载链接】anomalibAn anomaly detection library comprising state-of-the-art algorithms and features such as experiment management, hyper-parameter optimization, and edge inference.项目地址: https://gitcode.com/GitHub_Trending/an/anomalib创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考