企业官网建设流程全解析

• 人工智能
• 计算机视觉
• GIS
• 图像处理
• 微调

GeoAI 项目在 geoai/vllm_geo.py 中提供了geoai.vllm_geo模块，用于把 vLLM 托管的开源视觉语言模型（VLM）接入地理空间影像分析流程，支持图像描述（captioning）、视觉问答（VQA）与基于提示词的目标检测，并针对大尺寸栅格提供滑窗（sliding window）处理能力。读完本文，你将掌握如何在本地或远程 vLLM 服务上部署 VLM、用VLLMGeo类完成带地理参考（georeferenced）的推理与矢量输出，并了解其底层实现与测试验证方式。

模块定位：vLLM 为什么能补齐 GeoAI 的推理短板

vllm_geo模块解决的是一个非常实际的取舍问题：Ollama 这类本地推理工具部署简单但吞吐慢，云 API 速度快但成本高且数据需要外传。vLLM 通过 PagedAttention 等优化实现高吞吐的自托管推理，正好填补这一空白——模型权重和影像数据都留在自己的 GPU 服务器上，同时获得接近云 API 的并发能力。

从模块源码看，vllm_geo.py提供两类运行方式：

• Server 模式（默认）：连接一个正在运行的vllm serve <model>OpenAI 兼容端点，影像瓦片以 base64 编码的 data URI 发送，本地仅需requests依赖，不需要安装 vLLM；
• In-process 模式（offline=True）：直接通过vllm.LLM在进程内加载模型，要求本机安装 vLLM（pip install geoai-py[vllm]）。

模块顶部建议的开源 VLM 包括：

• Qwen/Qwen2-VL-7B-Instruct——图像描述 + 视觉问答，质量最佳；
• llava-hf/llava-v1.6-mistral-7b-hf——通用视觉问答；
• OpenGVLab/InternVL2-8B——场景理解。

这些模型 ID 也是模块中DEFAULT_MODEL = "Qwen/Qwen2-VL-7B-Instruct"的默认值来源。

安装与环境准备

Server 模式下，geoai的常规安装即可满足使用，因为请求只依赖requests、rasterio、geopandas、PIL与numpy。若要在进程内加载模型，则需要 vLLM 本身，项目在 pyproject.toml 中声明了可选依赖组：

vllm = ["vllm"]

对应安装命令：

pip install geoai-py[vllm]

是否安装成功可用模块提供的探测函数验证：

import geoai print(geoai.check_vllm_available()) # True 表示可导入 vllm

该函数在 geoai/vllm_geo.py 中通过尝试import vllm实现，VLLMGeo(offline=True)在 vLLM 缺失时会抛出ImportError并提示安装命令。同时，geoai/__init__.py以 PEP 562 惰性导入的方式导出VLLMGeo、vllm_caption、vllm_query、vllm_detect、check_vllm_available，因此import geoai本身很轻量，不会强制拉入 torch/transformers 等重依赖。

启动 vLLM 服务

Server 模式需要先有一个 vLLM 服务在运行。典型启动方式（以默认模型为例）：

vllm serve Qwen/Qwen2-VL-7B-Instruct

vLLM 默认监听http://localhost:8000，其/v1路径暴露 OpenAI 兼容的 chat completions API，这正是DEFAULT_BASE_URL = "http://localhost:8000/v1"的由来。vLLM 默认不启用鉴权，因此 API key 使用占位符"EMPTY"；如果服务以--api-key启动，则需要传入对应的 key。

VLLMGeo 核心类与初始化参数

VLLMGeo是模块的核心入口（geoai/vllm_geo.py），构造参数如下：

基础用法：

from geoai import VLLMGeo # Server 模式（默认） vlm = VLLMGeo() # 自定义服务地址与模型 vlm = VLLMGeo( model_id="Qwen/Qwen2-VL-7B-Instruct", base_url="http://gpu-server:8000/v1", api_key="EMPTY", ) # In-process 模式（需已安装 vllm） vlm = VLLMGeo(offline=True, max_model_len=8192)

影像加载：GeoTIFF 的读取、波段选择与归一化

地理空间影像与普通图片最大的区别在于多波段与地理参考。load_image/load_geotiff（geoai/vllm_geo.py）统一处理多种输入源：

• 文件路径：支持 GeoTIFF（.tif/.tiff）、PNG、JPG，也支持http(s)://远程地址（内部调用utils.download_file下载后处理）；
• PIL Image：直接透传；
• numpy 数组：二维灰度数组自动堆叠为 3 通道，三维数组自动转置为 HWC 布局。

GeoTIFF 的波段处理规则：

• bands=None时，若影像 ≥3 波段则读取前 3 个波段（通常为 RGB），否则读取第 1 波段并复制为灰度 RGB；
• 显式传入bands=[4,3,2]（1 起始索引）可自定义波段组合，便于按需选择近红外等波段参与推理。

多波段遥感数据往往是 uint16/float32 的高动态范围，直接送入 VLM 会失真。_normalize_image（geoai/vllm_geo.py）按 2%–98% 百分位拉伸将数据映射到 0–255 的 uint8 范围，避免极值主导对比度；已有 uint8 数据则原样返回。加载后返回(PIL Image, metadata)，metadata 携带profile、crs、transform、bounds、width、height，是后续地理参考化的基础。对应行为在 tests/test_vllm_geo.py 中有覆盖（灰度转 RGB、uint16 归一化、缺失文件抛FileNotFoundError、非法类型抛TypeError）。

三大推理任务：描述、问答、检测

图像描述（caption）

result = vlm.caption("naip.tif", length="normal") print(result["caption"])

length参数控制描述粒度，对应模块内置的三档提示模板（CAPTION_PROMPTS，见 geoai/vllm_geo.py）：

• "short"：一句话概述；
• "normal"（默认）：包含土地覆盖、结构物与显著特征；
• "long"：详细描述土地覆盖类型、结构、植被、水体、基础设施与空间格局。

也可以直接用prompt参数覆盖模板，传入任意自定义描述指令。

视觉问答（query）

# 带影像的问答 result = vlm.query("这片区域的主要土地覆盖类型是什么？", source="scene.tif") print(result["answer"]) # 纯文本问答（不带影像，直接透传服务） result = vlm.query("vLLM 的 PagedAttention 有什么作用？")

query的source是可选的：传入则构建图文混合消息，不传则仅发送文本，这在把VLLMGeo当普通 LLM 使用或做服务连通性测试时很方便。

提示词目标检测（detect）

模块没有训练检测头，而是利用 VLM 的视觉定位能力，通过固定格式的 JSON 提示让模型输出归一化边界框（geoai/vllm_geo.py）：

Detect all instances of '{object_type}' in this image. Respond ONLY with a JSON array of bounding boxes with coordinates normalized to the 0-1 range, in this exact format: [{"x_min": 0.1, "y_min": 0.2, "x_max": 0.3, "y_max": 0.4}]. If no objects are found, respond with [].

调用方式：

result = vlm.detect("aerial.tif", object_type="car", output_path="cars.geojson") print(result["objects"]) print(result["gdf"]) # GeoDataFrame，带 CRS

返回的objects为归一化坐标列表；若输入是带地理参考的 GeoTIFF，还会额外返回gdf（GeoDataFrame）、crs与bounds，从而实现"从像素框到地理框"的转换（_georef_detections，geoai/vllm_geo.py）。

响应解析（_parse_detections）做了多层容错：用正则提取首个 JSON 数组、容忍模型在 JSON 前后附加的闲聊文本、丢弃缺键或退化框（x_max <= x_min）、把越界坐标钳制回 0–1 区间。这些异常路径在 tests/test_vllm_geo.py 中被逐一验证，包括无 JSON、非法 JSON、部分非法条目等情形。

地理参考化与矢量输出

_georef_detections先把归一化坐标还原为像素坐标（乘以宽高），再用 GeoTIFF 的transform将像素坐标映射到地理坐标（注意像素 y 轴与地理 y 轴方向的翻转处理），最后用shapely.geometry.box构造矩形并组装成带 CRS 的 GeoDataFrame。output_path根据扩展名自动选择输出驱动：

• .geojson→ GeoJSON
• .shp→ ESRI Shapefile
• .gpkg→ GeoPackage

输出目录不存在时会自动创建（_save_vector，geoai/vllm_geo.py）。

大影像滑窗处理

VLM 的输入分辨率有限，大面积遥感影像必须切块处理。模块为描述、问答、检测三套任务各提供了滑窗版本，核心参数一致：

• window_size（默认 512）：瓦片边长，应匹配 VLM 的训练分辨率；
• overlap（默认 64）：相邻瓦片重叠像素，避免目标被切边界截断；
• show_progress（默认True）：显示进度条。

# 大图目标检测：滑窗 + NMS 合并 result = vlm.detect_sliding_window( "large_scene.tif", object_type="building", window_size=512, overlap=64, iou_threshold=0.5, output_path="buildings.gpkg", ) # 大图问答：逐瓦片回答后拼接或总结 result = vlm.query_sliding_window( "这片区域的水体分布如何？", source="large_scene.tif", combine_strategy="summarize", # 或 "concatenate" ) # 大图描述 result = vlm.caption_sliding_window("large_scene.tif", length="long")

实现要点（geoai/vllm_geo.py）：

1. _create_sliding_windows以stride = window_size - overlap步进生成窗口，丢弃边缘不足半个窗口的碎块；
2. 若影像本身小于窗口，则直接走单次推理分支，避免无谓切块；
3. 检测场景下，各瓦片输出的归一化坐标先换算回整图坐标，再经_apply_nms（基于 y 轴排序 + IoU 阈值 0.5 的经典 NMS 实现）去重合并；
4. 问答/描述场景下，combine_strategy="concatenate"会把每个瓦片结果按Tile N (region (x0,y0,x1,y1)): ...拼接；"summarize"则让模型基于各区域观察生成一份综合总结，总结失败时自动回退为拼接；
5. 单瓦片推理失败（RuntimeError/ValueError/KeyError）只记录 warning，不影响整体流程。

滑窗与 NMS 行为在 tests/test_vllm_geo.py 中有对应测试：小图只产生一个窗口、大图产生多窗口、NMS 去除重复框、1024×1024 影像滑窗后合并出跨瓦片检测结果等。

便捷函数：一行调用

不需要实例化VLLMGeo时，模块底部提供三个便捷函数（geoai/vllm_geo.py）：

from geoai import vllm_caption, vllm_query, vllm_detect # 描述 caption = vllm_caption("scene.tif", length="short") # 问答 answer = vllm_query("图中有几栋建筑？", source="scene.tif") # 检测并落盘 result = vllm_detect("scene.tif", "car", output_path="cars.shp")

三者均接受model_id、base_url等可选参数，内部创建VLLMGeo后调用对应方法并直接返回文本或结果字典，适合脚本化与批量处理场景。

与 Agent 体系的集成：create_vllm_model

vllm 的能力不只服务影像推理，也可作为 Agent 的底层模型。在 geoai/agents/geo_agents.py 中，create_vllm_model把 vLLM 的 OpenAI 兼容端点包装成OpenAIModel：

from geoai.agents.geo_agents import create_vllm_model model = create_vllm_model( base_url="http://localhost:8000/v1", model_id="meta-llama/Llama-3.1-8B-Instruct", api_key="EMPTY", )

其默认模型为meta-llama/Llama-3.1-8B-Instruct，并遵循"显式client_args优先于顶层参数"的合并规则（client_args中已存在的api_key/base_url不会被覆盖）。这意味着一个 vLLM 服务可以同时承担两类角色：既为VLLMGeo提供视觉推理，也为GeoAgent提供文本对话底座。相关默认值与优先级逻辑在 tests/test_vllm_geo.py 中有专门用例。

使用注意事项与适用边界

1. 检测质量依赖模型的空间定位能力：detect属于提示词式检测，模型需具备较强的 grounding 能力，输出框可能存在漏检或偏移，生产使用前建议先在目标区域数据上抽样验证；
2. 模型与服务的版本一致性：model_id必须与vllm serve实际加载的模型一致，否则服务端会报错；base_url需要包含/v1路径段；
3. Server 模式不要求本地 vLLM：客户端只发 HTTP 请求，vLLM 可部署在独立 GPU 服务器上，通过base_url指向内网地址即可；
4. 大影像推理成本可控：滑窗模式把请求拆分为多次小推理，可通过调整window_size与overlap在细节保留与推理次数之间权衡；
5. 影像预处理内置：高动态范围的多波段 GeoTIFF 无需手工归一化，模块会执行百分位拉伸，但波段组合（如是否引入近红外）需要按任务自行选择。

小结

geoai.vllm_geo把 vLLM 的高吞吐自托管推理与 GeoAI 的地理空间处理能力结合起来：VLLMGeo统一封装了影像加载、归一化、图文消息构造、结果解析与地理参考化，覆盖描述、问答、检测三大任务，并用滑窗 + NMS 突破 VLM 的输入分辨率限制，最终可直接产出带 CRS 的 GeoJSON/Shapefile/GeoPackage。无论是希望完全本地化处理遥感数据、规避云 API 成本，还是构建基于开源 VLM 的 GeoAI Agent 流水线，这个模块都提供了开箱即用的实现路径。

如需进一步研究实现细节，可深入阅读 geoai/vllm_geo.py、tests/test_vllm_geo.py 以及 geoai/agents/geo_agents.py 中的 Agent 集成部分。

• 人工智能
• 计算机视觉
• GIS
• 图像处理
• 微调