Agile Deliberation面向主观视觉分类的概念界定 边界反思人机协同框架实践指南【免费下载链接】google-researchGoogle Research项目地址: https://gitcode.com/gh_mirrors/go/google-research本文是 Google Research 开源项目 agile_deliberation 的实战技术指南。该仓库是论文《Agile Deliberation: Concept Deliberation for Subjective Visual Classification》的配套代码库与数据集提供了一个 human-in-the-loop人在回路的框架通过引导用户进行结构化概念界定concept scoping并迭代性地浮现边界案例borderline examples供用户反思帮助用户澄清模糊的心理模型从而完成对主观且持续演变的视觉概念的分类。读完本文你将掌握如何搭建环境、如何用 LAION400M 构建 FAISS 最近邻索引、如何通过 Jupyter / Colab 端到端运行Demo.ipynb以及理解框架内部的核心组件结构化定义、反思 Agent、LLM 分类器与检索客户端的源码实现原理。一、核心思想为什么主观视觉分类需要敏捷斟酌传统图像分类任务通常假设标签是客观、固定、可以被少数人一次性定义的。但现实中有大量主观且随语境演变的视觉概念例如令人反感的广告、符合平台规范的内容、有欺骗性的网页其定义往往取决于概念所有者的个人标准并且会在标注过程中不断变化。Agile Deliberation 的核心洞察是与其让用户一次性给出完整定义不如让系统与用户共同斟酌deliberate。整个流程包含两个关键环节概念界定Concept Scoping系统将 LLM 与结构化定义树结合协助用户把模糊概念分解为必要信号necessary signals、正信号positive signals与负信号negative signals逐层明确判定边界边界反思Reflection系统从大规模图像库中检索与当前定义相关的图像主动浮现那些暴露定义歧义的边界案例请用户标注并给出反馈再据此自动精炼定义形成检索 → 反思 → 精炼 → 再检索的迭代闭环。仓库以 Jupyter notebookDemo.ipynb形式发布了该原型系统的端到端实现并提供了逐步引导用户走完整个流程的说明。二、仓库结构一览在深入实践之前先了解仓库的目录组织以下路径均以仓库根目录为起点agile_deliberation/ ├── README.md # 官方使用说明本文主体依据 ├── Demo.ipynb # 端到端原型 Notebook ├── setup.sh # LAION400M 数据下载脚本 ├── build_index.py # 构建 FAISS 索引的替代入口 ├── indices_train.json # 检索索引配置CLIP 模型、索引路径 ├── requirements.txt # Python 依赖 └── agile_deliberation_lib/ # 框架核心库 ├── definitions.py # Definition 结构化概念定义 ├── reflection.py # Reflection 反思 Agent分解/头脑风暴/边界浮现 ├── classifier.py # ImageClassifier LLM 图像分类器 ├── interaction.py # DeliberationInteraction Colab 交互 UI ├── deliberators.py # ConceptDeliberator 流程总控 ├── search_images.py # ImageCurator 图像策展检索 ├── retrieval.py # RetrievalClient 检索客户端FAISS KNN ├── llm.py # AgentAPI LLM 客户端多端点容错 ├── image.py / utils.py 等 # 辅助模块 └── nearest_neighbor/ # CLIP-KNN 服务load_clip / clip_knn_service核心流程由 deliberators.py 中的ConceptDeliberator统筹内部组装了ImageCurator检索、Reflection反思、ImageClassifier分类、DefinitionRefiner精炼与DeliberationInteraction交互 UI五大组件。三、环境搭建3.1 创建工作目录与虚拟环境按照 README 的指引先进入项目目录并可选创建虚拟环境cd /path/to/agile_deliberation python3 -m venv venv source venv/bin/activate3.2 安装依赖pip install -r requirements.txtrequirements.txt 中声明的依赖包括LLM 调用google-genaiGoogle Gemini 官方 SDK视觉编码torch、open_clip_torch、clipOpenAI CLIP从 GitHub 源码安装检索与数据scikit-learn、numpy、pandas、h5py、tqdm图像与网络Pillow、requestsNotebook 交互ipywidgets、ipython、notebook此外根据是否需要对最近邻索引做 GPU 加速二选一安装 FAISSpip install faiss-gpu # GPU 加速版 # 或 pip install faiss-cpu # CPU 版从源码看build_index.py 直接import faiss并使用faiss.IndexFlatIP扁平内积索引FAISS 是构建与查询索引的必需组件。四、构建最近邻检索索引Agile Deliberation 方法依赖**最近邻索引nearest neighbor index**从图像数据集中检索相关图像示例。你可以对任意图像数据集构建索引README 以 LAION400M 数据集为例Demo.ipynb也使用该数据集。4.1 一键脚本setup.sh运行bash setup.shsetup.sh 会从 LAION 官方 embedding 服务下载元数据parquet与图像嵌入npy分片并在训练集上构建 FAISS 索引。脚本默认参数NUM_SHARDS${1:-2}即默认只下载前 2 个分片用于快速验证流水线。下载完成后会生成如下文件结构laion400m/ |- metadata |- metadata_0.parquet |- ... |- metadata_99.parquet |- npy |- img_emb_0.npy |- ... |- img_emb_99.npy |- image.index脚本还支持传入分片数量以控制数据规模详见 setup.sh 头部的 Usage 注释bash setup.sh 2 # 只下载前 2 个分片~260 MB推荐用于测试 bash setup.sh 10 # 下载前 10 个分片~1.3 GB性价比较高的选择 bash setup.sh 20 # 完整实验时加大分片数检索池更丰富、效果更好存储警告每个分片约 130 MB嵌入 元数据100 个分片总计约13 GB。默认只下载 2 个分片约 260 MB足够端到端验证流水线准备跑完整实验时用更大数量重跑即可——分片越多检索池越丰富结果越好。4.2 构建索引setup.sh的最后一步提示用autofaiss构建索引pip install autofaiss pyarrow cd laion400m autofaiss build_index \ --embeddingsnpy --index_pathimage.index \ --index_infos_pathimage_infos.json --metric_typeip仓库同时提供了纯 Python 的替代实现 build_index.py其工作方式与索引配置可以从源码确认从data_dir/npy/读取所有img_emb_*.npy嵌入分片按文件名排序后拼接为一个矩阵对全部嵌入执行L2 归一化faiss.normalize_L2再添加到faiss.IndexFlatIP(dim)中——由于归一化后内积等价于余弦相似度因此metric_typeip实际度量的是余弦相似度将索引写入image.index并把索引元信息index_keyFlat、nb examples、dimension等写入image_infos.json。用法示例python build_index.py # 索引全部分片 python build_index.py --max_shards 1 # 只索引 shard 0约 1 GB python build_index.py --data_dir laion400m --max_shards 1若npy/下找不到img_emb_*.npy文件build_index.py会抛出FileNotFoundError明确提示。4.3 索引配置文件indices_train.jsonagile_deliberation/indices_train.json 声明了检索索引的注册信息{ laion_400m: { indice_folder: ./laion400m, enable_faiss_memory_mapping: false, clip_model: ViT-B/32 } }其中clip_model: ViT-B/32指定了用于编码文本查询与图像嵌入的 CLIP 模型规格该配置会被 retrieval.py 中的RetrievalClient加载进而初始化 nearest_neighbor/clip_knn_service.py 提供的 CLIP-KNN 服务。值得注意的是RetrievalClient初始化时以enable_faiss_memory_mappingTrue、enable_hdf5True开启索引与元数据的内存映射把检索阶段的显存/内存占用降到接近零首次运行创建 hdf5 缓存会稍耗时。五、运行端到端 Demo5.1 性能与缓存须知在运行 Notebook 之前请先了解两条来自 README 的重要提示性能提示该原型将大规模向量索引上的图像检索、从外部 URL 下载图像与LLM 调用三者交错执行因此单个步骤可能耗时数秒到数分钟。若只使用单个 API keyLLM 还可能触发速率限制rate-limited请耐心等待 Notebook 中的响应。如果你有多个模型端点可以用ModelClient注册它们以分散负载。缓存机制流水线的多个阶段支持将结果缓存到磁盘避免跨会话重复昂贵的计算。详见 Demo.ipynb 内联注释中对应的单元格与选项——特别是可以一次性预收集反思阶段的候选图像池在后续每次运行中复用。5.2 方式一使用 Jupyter Notebook 运行在环境内先安装并启动 Jupyterpip install notebook jupyter notebook浏览器打开后进入Demo.ipynb它会自动挂载到当前环境内的 Python 3 内核然后**逐单元格cell by cell**运行即可。5.3 方式二使用 Google Colab 运行在 Colab 中上传Demo.ipynb或直接从你的 GitHub 仓库打开后注意Colab 是托管云环境每次连接都必须在 Notebook 会话内重新执行下述设置步骤即使你已在本地配置过项目。在 Notebook 最顶部新增一个代码单元格下载库文件并安装依赖!git clone YOUR_REPOSITORY_URL %cd REPOSITORY_FOLDER/third_party/google_research/google_research/agile_deliberation # 安装依赖 !pip install -r requirements.txt !pip install faiss-cpu # 或 faiss-gpu # 构建索引默认下载 2 个分片参数见 setup.sh !bash setup.sh之后即可逐单元格继续运行 Notebook。5.4 LLM 客户端与 API Key原型中的反思、分类与精炼环节依赖 Gemini 系列模型。从 llm.py 的AgentAPI源码可以确认以下运行前提与容错机制默认模型为gemini-2.5-proDEFAULT_MODEL_NAME便宜/轻量模型为gemini-2.5-flashDEFAULT_CHEAP_MODEL_NAME分类等高频调用默认走便宜模型classifier.py 中ImageClassifier(..., cheap_modelTrue)API key 优先取构造参数否则读取环境变量GEMINI_API_KEY未提供时会抛出ValueError: API key not provided内置多端点容错FAILURE_THRESHOLD3连续失败阈值、PAUSE_DURATION60触发暂停的秒数、REQUEST_TIMEOUT45.0单次请求超时、MAX_ATTEMPTS3每次请求最多尝试的客户端数并会记录各端点的延迟与成功率动态调整权重——这正是 README 中用ModelClient注册多个端点分散负载的底层实现。六、框架源码纵深解析本节以源码为准绳梳理Demo.ipynb背后各核心组件的工作原理帮助你理解每一步交互在做什么、为什么这样做。6.1 结构化概念定义Definitiondefinitions.py 中的Definition类是整个框架的数据结构中枢。一个概念定义是一棵树根节点是概念本身concept名称 description描述子节点按类型分为三类信号signalnecessary signals必要信号概念可由一组必要信号合取定义——图像满足全部必要信号即属于概念范围内positive signals正信号图像不满足任何负信号且至少满足一个正信号则属于概念范围内negative signals负信号图像只要强满足任一负信号即超出范围无论满足多少正信号。每个信号自身也是一个Definition可以继续挂载子信号从而形成多层结构如必要信号 → 再定义其正/负信号。Definition还维护了反思过程中的状态字段previous_signals丰富阶段已探索过的信号、previous_borderline_descriptions反思阶段已探索的边界描述、conditions用于浮现条件性歧义的待反思条件清单、groundtruth用户标注过的图像及评分、dataset已检索但尚未反思的图像。定义支持多种序列化形式print_definition()输出 XML 格式concept/necessary-signals/positive-signals/negative-signals嵌套结构readable_string()输出给人读的自然语言摘要serialize()/deserialize()用于磁盘持久化——ConceptDeliverator每轮都会把定义以 pickle 形式存档见下文。6.2 反思 AgentReflectionreflection.py 中的Reflection类实现了几个关键 LLM 驱动能力decompose_concept概念分解把复合视觉概念分解为至多若干个必要条件要求这些必要条件的合取在逻辑上等价于原概念且各条件互不冗余、互不重叠。分解后还会调用determine_whether_composite评估分解是否真的让标注者更容易判定若分解无益则放弃分解brainstorm_golden_category/brainstorm_borderline_category类别头脑风暴前者推理概念所有者可能希望纳入范围的金标准子概念如水果→柑橘类水果后者站在用户最初定义可能过窄的假设上推测用户真正想要的更宽泛概念并给出与已探索类别不重叠的边界子概念。Prompt 中明确要求子概念可分类、广为人知、不过窄、视觉上可辨识且描述格式遵循Images show [通用子概念术语]such as [至多三个具体示例]以降低标注者判定难度whether_borderline_images边界图像判定把定义与单张图像交给多模态 LLM先按当前定义分类再假设概念所有者给出相反结论反推定义中未能捕捉的重要歧义输出一句不超过 30 词的歧义摘要无歧义则输出空串surface_borderline_images边界图像浮现对一批图像批量计算歧义摘要后用文本嵌入把它们编码再以DBSCAN 聚类自适应尝试eps从 0.2 起、步长 0.01上限 0.8 避免过度聚类min_samples默认 5找出最大的有效边界歧义簇返回该簇图像供用户反思——这正是迭代浮现边界案例的核心机制。6.3 LLM 图像分类器ImageClassifierclassifier.py 中的ImageClassifier以建模副驾驶modeling copilot的方式依据结构化定义对图像做 LLM 判定返回decision评分与summary理由评分以3 分为阈值rating_to_label中rating 3记为 In-scope否则 Out-of-scopedetermine_correct_rating用于比对用户标注与分类器输出是否一致——若存在不一致mismatch交互 UI 会高亮这些图像并触发定义精炼evaluate_performance用 sklearn 计算 accuracy / precision / recall / f1zero_division1.0避免除零可用于评估当前定义下的分类效果。6.4 交互层DeliberationInteractioninteraction.py 中的DeliberationInteraction基于 ipywidgets 实现 Colab 内逐轮交互主要环节包括decompose_concept展示 LLM 分解出的必要信号编辑框用户可修改/重试红色 Retry 按钮或确认绿色 Confirm 按钮sufficient_signal_feedback交替展示金标准类别与边界类别的头脑风暴结果附Review Relevant Images按钮触发图像检索画廊异步预取120 秒超时用户判定该类别应作为In-scope正信号/ Out-of-scope负信号并入定义并可进一步编辑信号措辞image_reflections批量展示待标注图像用户用 RadioButtons 逐张标注 In/Out of Scope系统在后端并行调用分类器标注完成后切换为用户决策 vs 分类器决策对比视图MATCH ✅ / MISMATCH ❌附分类器理由用户可补充文本反馈一旦存在分类错误则调用DefinitionRefiner精炼定义并进入examine_improvements——以HTML diff 视图旧定义 vs 新定义可切换交互式编辑视图供用户审阅、接受或编辑。交互中还有一个值得注意的细节test_signal_times 3表示每个信号会在图像上测试 3 次以确保其真实有效。6.5 流程总控ConceptDeliberatordeliberators.py 中的ConceptDeliberator负责编排全局流程其默认超参数从源码可见包括参数默认值含义active_learning_batch5每轮反思的图像数search_images_per_query10每个查询检索的图像数 active_learning_batch × 2min_images_to_reflect25每轮浮现边界图像所需的最小候选池规模 active_learning_batch × 5max_image_clustering_distance0.8图像到簇中心可容忍的最大距离iteration_rounds15整个斟酌流程的运行轮数上限definition_folder可配置每轮定义存档目录其公开流程入口包括prepare_images_for_reflection循环用定义描述及其多样性改写generate_diverse_descriptions交替 in-scope / ambiguous 两类做文本→图像检索单次 250 或 75 张累积到目标数量默认 3000 张反思阶段默认取 200 张并去重image_reflection基于DiverseImageSampler从候选池按聚类挑选边界图像批次驱动interaction.image_reflections的标注 → 反馈 → 精炼 → 下一簇循环enrich_definitions在概念界定scoping阶段为每个必要信号逐一执行分解必要时→ 头脑风暴充分信号 → 用户反馈并入正/负信号的丰富流程每轮探索 3 个信号每轮将definition、now_definition、visited_logs、round_count等以 pickle 存档到logs_scoping_round_{round}.pkl最终定义保存在definition_scoping.pkl——这也是 README 所述多阶段支持磁盘缓存的实现之一。七、引用与声明如果你发现该代码库对你有用README 建议引用论文inproceedings{agile_modeling, title{Agile Deliberation: Concept Deliberation for Subjective Visual Classification}, author{Wang, Leijie and Stretcu, Otilia and Qiao, Wei and Denby, Thomas and Viswanathan, Krishnamurthy and Luo, Enming and Lu, Chun-Ta and Dogra, Tushar and Krishna, Ranjay and Fuxman, Ariel}, booktitle{Proceedings of the the IEEE/CVF Conference on Computer Vision and Pattern Recognition, Denver, Colorado, USA}, year{2026} }需要特别说明的是本项目不是 Google 官方支持的产品README Disclaimer 明确注明 This is not an officially supported Google product.它是一份研究原型。在实际使用时请根据你的数据规模、API 配额与硬件条件合理设置分片数量与运行轮数并留意多模态 LLM 调用与大规模检索带来的成本与延迟。【免费下载链接】google-researchGoogle Research项目地址: https://gitcode.com/gh_mirrors/go/google-research创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考