LocalAI GPT Vision 视觉理解实战OpenAI 兼容 API、视觉模型安装与图片标记注入原理【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAILocalAI 通过集成 LLaVA 系列视觉模型llama-cpp 后端实现了 OpenAI GPT Vision API 的本地兼容版本让你无需 GPU、无需外部服务即可让大模型看懂图片。本文基于仓库中的功能文档 gpt-vision.md 展开完整覆盖从安装视觉模型、调用/v1/chat/completions传图提问到结合 Grammar 约束输出的全部用法并深入到源码层面解释图片是如何被转换为模型可理解的标记的。功能概述LocalAI 的 GPT Vision 实现LocalAI 使用 LLaVA 一类视觉模型来理解图片并在接口层面实现了 OpenAI 的 GPT Vision API。这意味着请求走标准的/v1/chat/completions端点消息体结构与 OpenAI 完全一致image_url内容块 text内容块混排视觉能力由 llama-cpp 后端承载模型为 GGUF 格式的文本模型 视觉投影器mmproj组合视觉请求与文本生成共享同一套能力约束语法grammar、function tools、流式输出等均可叠加使用。安装视觉模型方式一CLI 一键安装运行从模型画廊gallery安装一个具备视觉能力的模型功能文档中的示例使用较小的视觉模型moondream2-20250414local-ai run moondream2-20250414方式二Web UI 的 Models 页面也可以直接打开 Web UI 的Models页面浏览并安装视觉模型。画廊中可用的其他视觉模型包括smolvlm-instruct和smolvlm2-2.2b-instruct等详见 模型画廊文档。视觉模型在画廊中的实际构成从 gallery/index.yaml 中可以看到moondream2-20250414的注册信息它由两个模型文件组成——moondream2-text-model-f16_ct-vicuna.gguf文本主干模型F16 精度moondream2-mmproj-f16-20250414.gguf视觉投影器multimodal projector负责把图片编码结果映射到语言模型空间。对应的行为配置文件为 gallery/moondream.yaml其关键配置如下config_file: | backend: llama-cpp context_size: 2046 f16: true known_usecases: - chat roles: assistant: \nAnswer: system: \nSystem: user: \nQuestion: stopwords: - Question: - template: chat: | {{.Input}} Answer: completion: | Complete the following sentence: {{.Input}}几个要点context_size: 2046限制了该小模型的上下文规模roles/stopwords/template定义了 Vicuna 风格的对话模板f16: true与 gguf 文件的 F16 量化保持一致。smolvlm系列gallery/smolvlm.yaml的配置则额外声明了known_usecases: [chat, vision]并通过一组 stopworddummy32000、/s、end_of_utterance等防止模型输出模板符号聊天模板形如{{ .Input -}} Assistant:而经典的 LLaVA 模型配置见 gallery/llava.yaml采用USER:/ASSISTANT:角色前缀与context_size: 4096。这三份配置展示了 LocalAI 视觉模型接入的通用模式llama-cpp 后端 GGUF 文本模型 mmproj 投影器 对话模板。用 /v1/chat/completions 让模型理解图片安装模型后向/v1/chat/completions发起请求即可让 LocalAI 理解并回复图片内容。messages数组中的content是一个数组混排text与image_url两种内容块curl http://localhost:8080/v1/chat/completions -H Content-Type: application/json -d { model: moondream2-20250414, messages: [{role: user, content: [{type:text, text: What is in the image?}, {type: image_url, image_url: {url: https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg }}], temperature: 0.9}]}请求结构说明字段说明model已安装的视觉模型名如moondream2-20250414messages[].role消息角色视觉内容一般放在user消息中messages[].content内容块数组支持text与image_url两种type混排image_url.url图片的 URL 或 base64 data URI见下文源码解析temperature采样温度视觉问答场景常用 0.9 左右除 OpenAI 风格的image_url外Realtime / Responses 接口还定义了input_image内容块其中image_url字段接受 base64 编码的 data URI如data:image/png;base64,...支持 PNG 和 JPEG 格式并可附带detail精度字段——类型定义见 message_item.go。结合 Grammar 约束视觉输出视觉 API 可以像纯文本 API 一样叠加约束语法grammar与 function tools。例如用root :: (yes | no)强制模型只回答 yes 或 no从而把视觉理解变成一个二分类判断curl http://localhost:8080/v1/chat/completions -H Content-Type: application/json -d { model: moondream2-20250414, grammar: root :: (\yes\ | \no\), messages: [{role: user, content: [{type:text, text: Is there some grass in the image?}, {type: image_url, image_url: {url: https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg }}], temperature: 0.9}]}这一组合非常适合把视觉理解接入自动化流程用 grammar 锁定输出词表后响应可以直接作为程序判断条件使用无需再解析自由文本。源码解析图片如何变成模型能看懂的标记从源码结构看一张图片进入模型要走三段处理内容块解析、模板渲染标记、后端标记对齐。1. 中间件解析内容块middleware所有请求先经过 request.go 中的内容解析循环。对于image_url及别名image类型的内容块case image_url, image: // Decode content as base64 either if its a URL or base64 text base64, err : utils.GetContentURIAsBase64(pp.ImageURL.URL) if err ! nil { xlog.Error(Failed encoding image, error, err) continue CONTENT } input.Messages[i].StringImages append(input.Messages[i].StringImages, base64) imgIndex nrOfImgsInMessage这里GetContentURIAsBase64会同时处理两种输入远端 URL下载后编码与已经是 base64 的内容统一存入StringImages并累计本条消息的图片数量。视频video_url、音频audio_url/input_audio在同一个循环中按相同模式处理因此该管道天然支持多模态混排。2. 多模态模板渲染templates解析得到的纯文本部分随后交由 multimodal.go 的TemplateMultiModal渲染为带占位标记的提示词。LocalAI 使用一个哨兵标记// DefaultMultiMediaMarker is the sentinel marker LocalAI emits in the rendered // prompt for each image/audio item. It matches llama.cpps historical // mtmd_default_marker() (__media__). ... const DefaultMultiMediaMarker __media__ const DefaultMultiModalTemplate {{ range .Audio }}__media__{{end}}{{ range .Images }}__media__{{end}}{{ range .Video }}[vid-{{.ID}}]{{end}}{{.Text}}也就是说一条消息里有 2 张图渲染结果就是__media____media__What is in the image?。模板本身是可通过配置覆盖的模型配置的multimodal模板字段默认模板会为每张图片/音频输出一个标记、为每个视频输出[vid-N]。单元测试 multimodal_test.go 覆盖了 0 张图、多图以及自定义模板的各种渲染场景。中间件处的调用见 request.goTemplateMultiModal收到TotalImages全局图片序号与ImagesInMessage本消息内图片数据此生成正确数量的标记。3. 后端标记对齐与图片传递backend哨兵标记是先渲染、后对齐的中间件执行时后端尚未加载不知道具体后端期望的真实标记。待模型加载完成后llm.go 完成两件事// The prompt was rendered with the sentinel __media__ marker because // middleware templating runs before the backend is loaded and probed. // Once we know the backends actual media marker, substitute so marker // count matches the bitmap count passed through opts.Images/Videos/Audios. prompt : s if c.MediaMarker ! c.MediaMarker ! templates.DefaultMultiMediaMarker { prompt strings.ReplaceAll(prompt, templates.DefaultMultiMediaMarker, c.MediaMarker) } opts.Prompt prompt opts.Images imagesMediaMarker来自对后端元数据的探测llama.cpp 服务端会为每个服务进程随机生成一个多模态标记并通过ModelMetadataResponse.media_marker上报见 gguf.go 的探测逻辑以及 llm.go 中仅当MediaMarker为空才探测的按需探测条件探测结果会持久化回模型配置persistProbedReasoning后续请求无需重复探测。MediaMarker字段定义在 model_config.go。替换确保提示词中标记的个数与通过opts.Images传递的图片张数严格一致——这是多模态模型正确对齐图文位置的关键。另外有一个重要分支若模型配置了UseTokenizerTemplate即由后端自己完成 tokenize 与模板渲染llama.cpp 服务端会自行注入媒体标记中间件就只传递纯文本、不再重复输出标记避免双重标记——源码注释见 request.go。适用前提与限制视觉模型必须是画廊中的视觉模型llama-cpp 后端 mmproj 投影器组合纯文本模型无法处理image_url内容块文档示例所用moondream2-20250414是小型视觉模型context_size仅 2046适合快速验证与低资源部署更高质量的视觉理解可选smolvlm-instruct、smolvlm2-2.2b-instruct等更大规格image_url支持远端 URL 与 base64 两种形式远端 URL 会在服务端下载并编码需保证网络可达视觉请求与 grammar、function tools 的组合受所用模型能力限制约束效果以模型实际表现为准。小结LocalAI 的 GPT Vision 能力把传图给模型标准化为三件事从画廊安装视觉模型local-ai run model、用 OpenAI 兼容的image_url内容块发起/v1/chat/completions请求、按需叠加 grammar 约束输出。底层由中间件内容解析、__media__哨兵标记模板渲染与后端标记探测对齐三个环节协作完成整条链路对调用方透明——这也是现有 OpenAI 客户端可以几乎不改代码地切换到 LocalAI 本地视觉服务的原因。【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考