> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 运行 LLM/VLM 容器

> 部署 Qualcomm 提供的与 OpenAI 兼容的 LLM/VLM 容器，在 NPU 上运行大语言模型和视觉语言模型。

Qualcomm 创建了一个容器化服务，暴露与 OpenAI 兼容的 API，便于轻松部署并与任何兼容 OpenAI API 的框架集成，例如 [LangChain](https://docs.langchain.com/) 和 [OpenWeb](https://github.com/open-webui/open-webui)。

## 主要特性

* 兼容 OpenAI 的 API：可直接替代 OpenAI Chat Completions API
* 模型完全在 NPU 上运行，提供快速性能，同时释放 CPU/GPU 以处理其他任务。
* 多模型支持：支持 qwen3-4b-instruct、llama3.1-8b 等 LLM，以及 qwen3-4b-VL 等 VLM。可轻松从 [AI Hub](http://aihub.qualcomm.com) 添加其他 LLM/VLM。
* 自动上下文管理：会话过长时进行智能摘要
* 基于线程的会话：跨请求维持对话上下文，允许您在同一容器实例中的 LLM 和 VLM 调用之间切换。

## 设置

以下步骤假设您已完成设备设置（[IQ-9075 EVK](https://dragonwingdocs.qualcomm.com/Ubuntu/devices/iq9075-evk/set-up-the-device) 或 [IQ-8275 EVK](https://dragonwingdocs.qualcomm.com/Ubuntu/devices/iq8275-evk/set-up-the-device)）。设备设置完成后，按照以下步骤安装并运行 LLM/VLM 微服务容器。在此示例中，我们会将一个 LLM 和一个 VLM 模型复制到设备上，并使用容器的单一实例同时运行这两个模型。

<Steps>
  <Step title="安装所需的软件包">
    ```bash theme={null}
    sudo apt update
    sudo apt install docker-compose unzip
    ```
  </Step>

  <Step title="设置 Docker">
    ```bash theme={null}
    # Configure Docker group
    sudo groupadd docker
    sudo usermod -aG docker $USER
    newgrp docker
    ```
  </Step>

  <Step title="下载 LLM/VLM 模型">
    我们先从 [Hugging Face](https://huggingface.co/qualcomm/Qwen3-4B-Instruct-2507) 下载针对 QCS9075 优化的 qwen3-4b-instruct 模型作为入门。您可以在 [Qualcomm AI Hub 页面](https://aihub.qualcomm.com/iot/models?domain=Generative+AI\&useCase=Text+Generation\&chipsets=qualcomm-qcs9075)上找到可用的 LLM 和 VLM 模型列表——可使用左侧的筛选器选择您感兴趣的芯片组和模型类型。<br />
    **直接下载：**<br />

    <AccordionGroup>
      <Accordion title="IQ-8275 EVK">
        **LLM：**[Qwen3-4b-instruct for QCS8275 直接下载链接。](https://qaihub-public-assets.s3.us-west-2.amazonaws.com/qai-hub-models/models/qwen3_4b_instruct_2507/releases/v0.53.1/qwen3_4b_instruct_2507-genie-w4a16-qualcomm_qcs8275.zip)<br />
        **VLM：**[Qwen2.5-VL-7B-Instruct for QCS8275 直接下载链接。](https://qaihub-public-assets.s3.us-west-2.amazonaws.com/qai-hub-models/models/qwen2_5_vl_7b_instruct/releases/v0.53.1/qwen2_5_vl_7b_instruct-genie-w4a16-qualcomm_qcs8275.zip)<br />
      </Accordion>

      <Accordion title="IQ-9075 EVK">
        **LLM：**[Qwen3-4b-instruct for QCS9075 直接下载链接。](https://qaihub-public-assets.s3.us-west-2.amazonaws.com/qai-hub-models/models/qwen3_4b_instruct_2507/releases/v0.53.1/qwen3_4b_instruct_2507-genie-w4a16-qualcomm_qcs9075.zip)<br />
        **VLM：**[Qwen2.5-VL-7B-Instruct for QCS9075 直接下载链接。](https://qaihub-public-assets.s3.us-west-2.amazonaws.com/qai-hub-models/models/qwen2_5_vl_7b_instruct/releases/v0.53.1/qwen2_5_vl_7b_instruct-genie-w4a16-qualcomm_qcs9075.zip)<br />
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="安装 LLM/VLM 模型">
    在下载了 zip 文件后，将其复制到设备并解压。此示例假设您在 `~/models` 创建了一个模型目录。<br />

    <AccordionGroup>
      <Accordion title="IQ-9075 EVK">
        ```bash theme={null}
        # Copy model(s) from host to device
        scp -r qwen3_4b_instruct_2507-genie-w4a16-qualcomm_qcs9075.zip ubuntu@<device-ip>:~/models
        scp -r qwen2_5_vl_7b_instruct-genie-w4a16-qualcomm_qcs9075.zip ubuntu@<device-ip>:~/models

        # SSH into device and unzip
        ssh ubuntu@<device-ip>
        cd ~/models
        unzip qwen3_4b_instruct_2507-genie-w4a16-qualcomm_qcs9075.zip
        unzip qwen2_5_vl_7b_instruct-genie-w4a16-qualcomm_qcs9075.zip
        ```

        您的模型目录现在应类似于：<br />
        `~/models/qwen3_4b_instruct_2507-genie-w4a16-qualcomm_qcs9075/`<br />
        `~/models/qwen2_5_vl_7b_instruct-genie-w4a16-qualcomm_qcs9075/`
      </Accordion>

      <Accordion title="IQ-8275 EVK">
        ```bash theme={null}
        # Copy model(s) from host to device
        scp -r qwen3_4b_instruct_2507-genie-w4a16-qualcomm_qcs8275.zip ubuntu@<device-ip>:~/models
        scp -r qwen2_5_vl_7b_instruct-genie-w4a16-qualcomm_qcs8275.zip ubuntu@<device-ip>:~/models

        # SSH into device and unzip
        ssh ubuntu@<device-ip>
        cd ~/models
        unzip qwen3_4b_instruct_2507-genie-w4a16-qualcomm_qcs8275.zip
        unzip qwen2_5_vl_7b_instruct-genie-w4a16-qualcomm_qcs8275.zip
        ```

        您的模型目录现在应类似于：<br />
        `~/models/qwen3_4b_instruct_2507-genie-w4a16-qualcomm_qcs8275/`<br />
        `~/models/qwen2_5_vl_7b_instruct-genie-w4a16-qualcomm_qcs8275/`
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="将 docker compose 文件安装到您的设备上">
    从 [CodeLinaro 部署目录](https://git.codelinaro.org/clo/le/solutions-microservices/-/tree/iot-solutions.lnx.1.0/microservices/llm-vlm/chatcompletions/deploy)下载适用于您设备的 Docker Compose 文件。

    <AccordionGroup>
      <Accordion title="IQ-9075 EVK">
        ```bash theme={null}
        scp docker-compose-qcs9100-ubuntu.yaml ubuntu@<device-ip>:~/
        ```
      </Accordion>

      <Accordion title="IQ-8275 EVK">
        ```bash theme={null}
        scp docker-compose-qcs8300-ubuntu.yaml ubuntu@<device-ip>:~/
        ```
      </Accordion>
    </AccordionGroup>

    <Note>后续步骤使用 `docker-compose-qcs9100-ubuntu.yaml`。如果您使用的是 IQ-8275，请在每个命令中替换为 `docker-compose-qcs8300-ubuntu.yaml`。</Note>
  </Step>

  <Step title="配置您的 LLM/VLM 容器">
    编辑您复制到设备上的 Docker Compose 文件以进行配置：<br />
    在 `environment:` 下：

    * **GENAI\_PORT**：更改要暴露服务的端口号（默认值：9001）<br />
    * **MAX\_ACTIVE\_MODELS**：服务同时保持加载的不同模型的最大数量。当请求新模型且已达到上限时，最近最少使用的模型将被卸载以腾出空间。每个加载的模型都会占用 DSP/NPU 资源和内存。（默认值：2）<br />
    * **GENAI\_CONTEXT\_CAPPING**：每个模型允许使用的上下文窗口的安全上限。设置后，每个模型的原生上下文大小会被降低到 min(original\_size, cap)。这限制了内存使用，有助于避免资源受限设备上出现内存不足的情况。（默认值：2048）<br />

    在 `volumes:` 下：

    * **GENAI\_MODEL\_DIR**：更改为指向您的模型目录。在此示例中，我们使用 \~/models，因此更改为：<br /> `${GENAI_MODEL_DIR:-~/models}:/mnt/work/models/`
      <Warning>请务必将其设置为您的模型目录，否则容器将无法找到您的模型。</Warning>
  </Step>

  <Step title="启动容器">
    如果容器不存在，docker compose 文件会自动将其下载到您的设备，并使用您配置的设置运行。

    ```bash theme={null}
    # Start the container (add -d at the end to run detached)
    docker-compose -f docker-compose-qcs9100-ubuntu.yaml up
    ```
  </Step>

  <Step title="验证 LLM 是否正常工作">
    打开浏览器并访问 `http://<Device IP address>:<port>/docs` 以打开 API 浏览器。
    在 `/v1/chat/completions/` API 中：

    <Steps>
      <Step title="选择 'Try it out'" />

      <Step title="将请求正文替换为">
        ```json theme={null}
        {
        "messages": [
            {
            "content": "You are a helpful assistant",
            "role": "system"
            },
            {
            "content": "What is the capital of Italy?",
            "role": "user"
            }
        ],
        "model": "qwen3_4b_instruct_2507",
        "stream": false
        }
        ```
      </Step>

      <Step title="点击 'Execute' 发送请求">
        您应该会在下方页面看到响应。

        <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/AI-Developer-Workflow-Ubuntu/_images/container-llm-response.png" alt="LLM 响应示意图" />
      </Step>
    </Steps>
  </Step>

  <Step title="验证 VLM 是否正常工作">
    打开浏览器并访问 `http://<Device IP address>:<port>/docs` 以打开 API 浏览器。
    在 `/v1/chat/completions/` API 中：

    <Steps>
      <Step title="选择 'Try it out'" />

      <Step title="将请求正文替换为">
        ```json theme={null}
        {
            "model": "qwen2_5_vl_7b_instruct",
            "messages": [
            {
                "role": "user",
                "content": [
                {
                    "type": "text",
                    "text": "What is in this image?"
                },
                {
                    "type": "image_url",
                    "image_url": {
                    "url": "https://images.pexels.com/photos/210186/pexels-photo-210186.jpeg?cs=srgb&dl=cascade-clouds-cool-wallpaper-210186.jpg&fm=jpg"
                    }
                }
                ]
            }
            ]
        }    
        ```
      </Step>

      <Step title="点击 'Execute' 发送请求">
        您应该会在下方页面看到响应。请注意，VLM 可能需要几秒钟才能运行。

        <img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/AI-Developer-Workflow-Ubuntu/_images/container-vlm-response.png" alt="VLM 响应示意图" />
      </Step>
    </Steps>

    <Note>在此前调用 LLM 之后首次调用 VLM（或反之），响应会有轻微延迟，因为容器需要卸载之前的 LLM 并加载 VLM。后续调用将执行得快得多。</Note>
  </Step>

  <Step title="停止容器">
    完成后，您可以使用以下命令停止容器：

    ```bash theme={null}
    docker-compose -f docker-compose-qcs9100-ubuntu.yaml down
    ```
  </Step>
</Steps>