> ## 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 的 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](/zh/devices/iq9075-evk/set-up-the-device) 或 [IQ-8275 EVK](/zh/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:** [面向 QCS8275 的 Qwen3-4b-instruct 直接下载链接。](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:** [面向 QCS8275 的 Qwen2.5-VL-7B-Instruct 直接下载链接。](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:** [面向 QCS9075 的 Qwen3-4b-instruct 直接下载链接。](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:** [面向 QCS9075 的 Qwen2.5-VL-7B-Instruct 直接下载链接。](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 deploy 目录](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 中:

    1. 选择 'Try it out'
    2. 将请求体替换为:

    ```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
    }
    ```

    3. 点击 'Execute' 发送请求。您应该会在下方页面上看到响应。
           <img src="https://mintcdn.com/qualcomm-prod/kAKe9NmJg3DGZBpB/Ubuntu/images/running-building-ai-models/container-llm-response.png?fit=max&auto=format&n=kAKe9NmJg3DGZBpB&q=85&s=e7c83511f0625dd5485938cef6dbca5d" alt="LLM 响应图片" width="1397" height="482" data-path="Ubuntu/images/running-building-ai-models/container-llm-response.png" />
  </Step>

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

    1. 选择 'Try it out'
    2. 将请求体替换为:

    ```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"
                }
            }
            ]
        }
        ]
    }    
    ```

    3. 点击 'Execute' 发送请求。您应该会在下方页面上看到响应。请注意,VLM 可能需要几秒钟才能运行完成。
           <img src="https://mintcdn.com/qualcomm-prod/kAKe9NmJg3DGZBpB/Ubuntu/images/running-building-ai-models/container-vlm-response.png?fit=max&auto=format&n=kAKe9NmJg3DGZBpB&q=85&s=85c62da7c8f6a357ef61bab301d1b888" alt="VLM 响应图片" width="1398" height="482" data-path="Ubuntu/images/running-building-ai-models/container-vlm-response.png" />
       <Note>当您在之前调用过 LLM 之后首次调用 VLM(或反之)时,响应会有轻微延迟,因为容器正在卸载之前的 LLM 并加载 VLM。后续调用的执行速度会快得多。</Note>
  </Step>

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

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