菜鸟AI
菜鸟AI AI提示词 · 教程 · 资讯
首页>进阶教程

手把手LocalAI本地部署图文教程：Windows GPU多模态模型

2026-06-02阅读 0热度 0
windows

在部署LocalAI多模态大模型之前，先梳理两个基础概念，这对后续操作至关重要。

第一部分：核心概念

Docker镜像相当于软件的“安装包”或“模板”。比如 localai/localai:latest-gpu-nvidia-cuda-12 这个镜像，里面包含了LocalAI的所有运行环境。而Docker容器则是镜像运行起来的实例，可以看作一个轻量级、独立的虚拟机，LocalAI服务就在容器里运行。

简单来说，流程就是：下载镜像 → 创建并运行容器 → 访问容器内的服务。

第二部分：Windows实战部署LocalAI

请按照以下步骤操作。

步骤1：安装Docker Desktop for Windows

首先安装Docker Desktop for Windows，官方下载安装即可。

步骤2：拉取并运行LocalAI容器

这是最关键的一步。在Windows PowerShell中，命令不需要加 sudo。

  1. 打开PowerShell：以管理员身份运行Windows PowerShell。
  2. 运行GPU容器：若持有NVIDIA GPU且需要GPU推理，运行以下命令。注意挂载路径是 /build/models，这是很多教程中未提及的关键点。 
    docker run -d --name local-ai -p 8080:8080 --gpus all -v D:LocalAIModels:/build/models localai/localai:latest-aio-gpu-nvidia-cuda-12
    命令解读：
    • -d：后台运行容器。
    • --name local-ai：给容器起名，便于管理。
    • -p 8080:8080：将本机的8080端口映射到容器的8080端口。
    • --gpus all：将主机的所有GPU分配给容器使用（需要NVIDIA显卡及驱动）。
    • -v D:LocalAIModels:/build/models：将本地目录 D:LocalAIModels 挂载到容器内的 /build/models 路径。这是存放模型文件的地方。
    • localai/localai:latest-aio-gpu-nvidia-cuda-12：使用的GPU版本镜像。
  3. 验证运行：运行 docker ps，如果看到名为 local-ai 的容器状态为 Up，说明启动成功。

步骤3：下载并配置多模态大模型

第三部分：下载并配置多模态大模型

在Docker容器成功运行后，可以在本机浏览器访问LocalAI的Web界面，来下载并加载多模态大模型（比如视觉语言模型）。下面详细说明操作步骤和可能遇到的问题。

3.1 访问LocalAI Web界面

  1. 打开浏览器，访问 http://localhost:8080/
  2. 或者点击容器中的PORT：8080/8080：

就会看到如下界面：

首次进入时，你会看到模型选择区，提示 Select a model to chat with…，右侧有文件、麦克风、图片、发送等图标。界面下方有Installed Models and Backends、Import Model、Browse Gallery三个入口。点击👉 Browse Gallery，去里面找模型。

3.2 在Gallery中搜索并下载模型

  1. 进入模型浏览界面：
    • 顶部搜索框输入模型名称 qwen3-vl-4b-instruct 或者其他模型。
    • 下方有按类型过滤的按钮，确保Vision按钮为红色选中状态（因为这是一个视觉语言多模态模型）。

  • 列表中会显示模型信息：
    • Model Name: qwen3-vl-4b-instruct
    • Description: Qwen3-VL-4B-Instruct is the 4B parameter …
    • Repository: localai
    • License: apache-2.0
    • Status: Not Installed
    • Actions: 提供下载/安装按钮
  • 点击 Install/Download 按钮开始安装模型。

3.3 处理安装失败的情况

需要科学上网，就会看到：

如果在下载过程中间出现错误提示：

Error installing model "qwen3-vl-4b-instruct": Get "https://raw.githubusercontent.com/mudler/LocalAI/master/gallery/qwen3.yaml": unexpected EOF

  • 原因分析：
    unexpected EOF 表示在读取远程YAML配置文件时，网络连接中断或文件未完整下载，常见于GitHub原始文件链接在某些地区无法直接访问（需“科学上网”或稳定国际网络）。
  • 解决方法：
    1. 开启可稳定访问GitHub的网络环境。
    2. 重新点击安装，等待模型下载完成。

下载成功后，模型状态会从 Not Installed 变为已安装，可在Installed Models and Backends中看到。

3.4 关于容器重启后访问延迟的解释

如果不小心关闭或重启了LocalAI容器：

再次访问 http://localhost:8080/ 时可能会暂时出现无法加载页面的情况：

  • 原因：
    • 容器启动后，LocalAI服务需要时间初始化（加载依赖、检查模型文件、启动后端服务等），通常需几分钟。
    • 在初始化完成前，Web服务端口虽已映射，但应用本身并未完全就绪，因此浏览器会显示连接失败或超时。
  • 建议：
    启动容器后，先通过 docker ps 确认容器状态为Up，再等待约1–3分钟，然后刷新页面即可正常访问。

第四部分：首页测试大模型

返回首页，刷新，就可以选择刚才下载好的这个模型。上传一张图像，附上文字描述，就会看到已经在调用本地的GPU开始预测了。不一会儿，就得到了文本输出。

第五部分：Python 调用多模态模型

下面给出在PyCharm中调用本地LocalAI多模态模型（如qwen3-vl-4b-instruct）的完整示例，支持传入图像+文本并获取模型输出。

一、前置检查

  • 确保LocalAI容器已启动并可在浏览器打开 http://localhost:8080/，且模型qwen3-vl-4b-instruct处于Installed状态。
  • 在PowerShell中确认容器运行正常： 
    docker ps
  • 如需GPU加速，确认本机NVIDIA驱动 + Docker GPU支持正常；容器内执行 nvidia-smi 可验证（进入容器：docker exec -it local-ai bash）。

二、安装依赖

在PyCharm新建项目后，安装所需Python包（建议使用虚拟环境）：

uv pip install -U openai requests pillow

说明：

  • openai：使用与OpenAI兼容的接口调用LocalAI。
  • requests：兜底用，直接调用REST接口。
  • pillow：读取本地图片并转为Base64。

三、方案一 OpenAI兼容客户端调用（推荐）

新建文件：client_openai.py

import base64
import time
from pathlib import Path
import openai

# 1) 配置指向本地 LocalAI（与 OpenAI 兼容）
client = openai.OpenAI(
    base_url="http://127.0.0.1:8080/v1",  # LocalAI 默认 OpenAI 兼容端口
    api_key="EMPTY",                      # 本地无需密钥
)

def image_to_base64(image_path: str) -> str:
    data = Path(image_path).read_bytes()
    return base64.b64encode(data).decode("utf-8")

def chat_with_vision(
    model: str,
    image_path: str,
    prompt: str,
    temperature: float = 0.2,
    max_tokens: int = 1024,
):
    b64_img = image_to_base64(image_path)
    messages = [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": prompt},
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/jpeg;base64,{b64_img}"},
                },
            ],
        }
    ]

    start = time.time()
    resp = client.chat.completions.create(
        model=model,
        messages=messages,
        temperature=temperature,
        max_tokens=max_tokens,
    )
    elapsed = time.time() - start

    print(f"【Prompt tokens】{resp.usage.prompt_tokens}")
    print(f"【Completion tokens】{resp.usage.completion_tokens}")
    print(f"【Elapsed】{elapsed:.2f}s")
    print("【Response】", resp.choices[0].message.content.strip())

if __name__ == "__main__":
    # 注意：这里填写你在 Gallery 中安装后的实际模型名称
    MODEL_NAME = "qwen3-vl-4b-instruct"
    chat_with_vision(
        model=MODEL_NAME,
        image_path="assets/demo.jpg",  # 请替换为你的图片路径
        prompt="请用中文详细描述这张图片，并指出图中主要物体的位置、颜色和动作。",
        temperature=0.2,
        max_tokens=1024,
    )

使用要点：

  • 将MODEL_NAME替换为你Gallery中已安装的模型名（可在页面Installed Models and Backends查看）。
  • 图片支持JPEG/PNG等常见格式；大图可先压缩以提升上传与推理速度。
  • 若显存较小，可适当降低max_tokens或改用更轻量模型。

四、方案二 直接REST调用（requests）

新建文件：client_rest.py

import base64
import time
from pathlib import Path
import requests

API_BASE = "http://127.0.0.1:8080/v1"
API_KEY = "EMPTY"  # 本地通常为 EMPTY

def image_to_base64(image_path: str) -> str:
    data = Path(image_path).read_bytes()
    return base64.b64encode(data).decode("utf-8")

def chat_with_vision_rest(
    model: str,
    image_path: str,
    prompt: str,
    temperature: float = 0.2,
    max_tokens: int = 1024,
):
    b64_img = image_to_base64(image_path)
    payload = {
        "model": model,
        "messages": [
            {
                "role": "user",
                "content": [
                    {"type": "text", "text": prompt},
                    {
                        "type": "image_url",
                        "image_url": {"url": f"data:image/jpeg;base64,{b64_img}"},
                    },
                ],
            }
        ],
        "temperature": temperature,
        "max_tokens": max_tokens,
    }
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}",
    }

    start = time.time()
    r = requests.post(f"{API_BASE}/chat/completions", json=payload, headers=headers, timeout=120)
    r.raise_for_status()
    data = r.json()
    elapsed = time.time() - start

    print(f"【Elapsed】{elapsed:.2f}s")
    print("【Response】", data["choices"][0]["message"]["content"].strip())

if __name__ == "__main__":
    MODEL_NAME = "qwen3-vl-4b-instruct"
    chat_with_vision_rest(
        model=MODEL_NAME,
        image_path="assets/demo.jpg",
        prompt="请用中文详细描述这张图片。",
        temperature=0.2,
        max_tokens=1024,
    )

运行后，就会看到如下输出：

上一篇GPT Image 2 2026年营销工作流程革新测评 下一篇AI新名词精选榜单：大模型、提示词、智能体全解析
免责声明

本网站新闻资讯均来自公开渠道，力求准确但不保证绝对无误，内容观点仅代表作者本人，与本站无关。若涉及侵权，请联系我们处理。本站保留对声明的修改权，最终解释权归本站所有。

相关阅读

更多

最新教程

BAUHAUS框架的安装与环境配置详细步骤AI 驱动的 video enhancer 工具安装与基础配置指南使用AI拜年黑科技工具的具体步骤与配置方法AI 驱动的 video enhancer 工具安装与基础配置指南使用AI拜年黑科技工具的具体步骤与配置方法DEEPSEEK 本地部署常见问题与解决方案

最新资讯

2026年AI Agent必备命令行工具TOP10资深工程师慢学指南：为什么放慢节奏更高效React技术周刊 2026年第14周 精选榜单Python技术周刊2026年第14周精选2026渗透工程：黑客信息收集实战指南2026年第15周Node.js技术周刊权威精选榜单芒果灵创AI影视创作平台评测：湖南卫视专业工具揭秘QiLink时间戳评测：创作者原创保护首选
欢迎回来 登录或注册后，可保存提示词和历史记录
登录后可同步收藏、历史记录和常用模板
注册即表示同意服务条款与隐私政策