> ## 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.

# 开发生成式 AI(GenAI)应用:GenAI Studio

> 在 Qualcomm Dragonwing IoT 平台上设置并运行 GenAI Studio,用于文本生成、文本转语音、图像生成、图像转文本(VLM)和语音转文本应用。

GenAI Studio 是一个容器化解决方案,通过简化在 Qualcomm Linux 系统上创建和部署生成式 AI
应用的过程,来加速原型设计和定制化开发。GenAI Studio 为以下核心服务提供
与 OpenAI 兼容的 API:文本生成、文本转语音、图像生成、图像转文本(VLM)和语音转文本。

所有服务都可以通过 Web 界面和与 OpenAI 兼容的 API 端点进行访问。

<Note>
  * GenAI Studio 不包含模型文件或容器镜像。
  * 您必须自行生成模型并构建容器镜像。
  * 请确保您的主机满足[要求](https://github.com/qualcomm/ai-hub-apps/tree/main/tutorials/llm_on_genie)。
  * 使用主机生成模型。
  * 使用目标设备构建 docker 容器。
</Note>

| 用例                | 描述                                           | 支持的平台  | 模型                          |
| ----------------- | -------------------------------------------- | ------ | --------------------------- |
| 文本转文本             | 使用 LLM 针对输入提示生成类似人类的响应。适用于自动创建文章、摘要、报告或创意内容。 | Ubuntu | LLaMA 3.2-3B<br />Qwen 3-4B |
| 文本转语音             | 将文本转换为清晰、自然的音频。非常适合语音助手、有声读物和无障碍解决方案。        | Ubuntu | Melo-TTS                    |
| 文本转图像             | 从文本描述生成图像。无需手动设计,即可创建图形、插画或视觉内容。             | Ubuntu | Stable Diffusion 2.1        |
| 语音转文本             | 将口语转换为文字。有助于转录、语音命令和免提应用。                    | Ubuntu | Whisper Tiny                |
| 图像转文本             | 使用自然语言描述图像,用于视觉理解和内容审核。                      | Ubuntu | Qwen 2.5-VL-7B              |
| Orchestrator(编排器) | 提供易于使用的 Web 界面,可在一个地方访问所有这些功能,方便开发者和用户使用。    | Ubuntu | 上述列出的所有模型                   |

## 高层架构

下图显示了 GenAI Studio 的高层架构。每个功能模块都作为独立的容器运行,提供隔离性、可扩展性和可扩展性。这样便可将新的模态作为额外容器添加,而不会中断现有服务。

<Note>
  每个端点都有特定的端口。请在[端点端口号](#tbl-endpoint-ports)中查看端口号。
</Note>

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/AI-Developer-Workflow-Ubuntu/_images/genai-studio-architecture.png" alt="GenAI Studio 的高层架构,展示了容器化用例和后端交互" />

下表列出了每个端点及其关联的端口号。

**端点端口号** <a id="tbl-endpoint-ports" />

| 服务           | 端口   | 与 OpenAI 兼容的端点                  |
| ------------ | ---- | ------------------------------- |
| 文本转语音        | 8083 | `POST /v1/audio/speech`         |
| 文本转图像        | 8084 | `POST /v1/images/generations`   |
| 图像转文本        | 8080 | `POST /v1/responses`            |
| 文本转文本        | 8088 | `POST /v1/chat/completions`     |
| 语音转文本        | 8081 | `POST /v1/audio/transcriptions` |
| Orchestrator | 8090 | 统一网关                            |

### 用户交互

用户通过主机上托管的网页访问 GenAI Studio,或者通过带有与 OpenAI 兼容端点的第三方应用的 API 调用访问 GenAI Studio。

### 请求路由到目标

网页或 API 调用与运行在目标设备(例如 Qualcomm Dragonwing™ IQ9)上的
Orchestrator 服务通信,并将 UI 上的每个用户操作转换为对后端服务的相应
REST API 调用。

### 编排层

Orchestrator 容器充当中央枢纽。它接收请求,管理会话历史,
处理多轮对话连续性(KV-cache),并聚合来自各个模态
容器的响应,向用户呈现统一的体验。

容器化架构和可扩展性:
每个功能模块(orchestrator、text-to-text、text-to-speech、text-to-image、image-to-text、speech-to-text)都作为独立的容器运行。
这提供了以下优势:

* 服务之间的隔离。
* 可扩展性,因为每个服务可以根据用例独立扩展。
* 可扩展性,因为您可以将新的模态或模型作为额外的容器添加。

请参阅各个用例的文档以获得更详细的信息。

### 文本转文本

此应用使用 Genie API 运行文本转文本的大语言模型(LLM)。
它提供了一个持久化(始终开启)的 LLM 服务器,支持以下功能:

* 根据用户提示生成 LLM 响应(文本转文本)。
* 预加载的模型可复用,避免每次请求都重新加载。
* 用于模型/会话重置和模型重新加载的控制端点。
* 直接从 UI 更新系统提示。
* 会话历史,允许 UI 获取之前的消息。

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/AI-Developer-Workflow-Ubuntu/_images/genai-studio-text-generation-call-flow.png" alt="GenAI Studio 组件在文本生成用例中的调用流程及组件间交互方式。" />

有关更多信息,请参阅 [text-to-text README](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/blob/main/GenAI-Solutions/GenAI-Studio/core-services/text-to-text/README.md)
和[代码流程文件](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/blob/main/GenAI-Solutions/GenAI-Studio/core-services/text-to-text/CODE_FLOW.md)。

### 文本转图像

下图显示了文本转图像容器中的示例调用流程序列。

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/AI-Developer-Workflow-Ubuntu/_images/genai-studio-text-to-image-call-flow.png" alt="GenAI Studio 组件在应用中的调用流程及组件间交互方式。" />

有关更多信息,请参阅 [text-to-image README](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/blob/main/GenAI-Solutions/GenAI-Studio/core-services/text-to-image/README.md)
和[代码流程文件](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/blob/main/GenAI-Solutions/GenAI-Studio/core-services/text-to-image/CODE_FLOW.md)。

### 图像转文本

图像转文本容器使用视觉语言模型(VLM)以自然语言描述图像,支持视觉理解和内容审核用例。

有关更多信息,请参阅 [image-to-text README](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/blob/main/GenAI-Solutions/GenAI-Studio/core-services/image-to-text/README.md)
和[代码流程文件](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/blob/main/GenAI-Solutions/GenAI-Studio/core-services/image-to-text/CODE_FLOW.md)。

### 文本转语音

下图显示了文本转语音容器中的示例调用流程序列。

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/AI-Developer-Workflow-Ubuntu/_images/genai-studio-text-to-speech-call-flow.png" alt="GenAI Studio 组件在应用中的调用流程及组件间交互方式。" />

有关更多信息,请参阅 [text-to-speech README](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/blob/main/GenAI-Solutions/GenAI-Studio/core-services/text-to-speech/meloTTS/README.md)。

### 语音转文本

下图显示了语音转文本容器中的示例调用流程序列。

<img src="https://mintlify.s3.us-west-1.amazonaws.com/qualcomm-prod/zh/AI-Developer-Workflow-Ubuntu/_images/genai-studio-speech-to-text-call-flow.png" alt="GenAI Studio 组件在应用中的调用流程及组件间交互方式。" />

有关更多信息,请参阅 [speech-to-text README](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/blob/main/GenAI-Solutions/GenAI-Studio/core-services/speech-to-text/README.md)
和[代码流程文件](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/blob/main/GenAI-Solutions/GenAI-Studio/core-services/speech-to-text/CODE_FLOW.md)。

## 设置 GenAI Studio

Qualcomm IoT 平台上搭载 Ubuntu 发行版的 IQ9 和 IQ8 支持 GenAI Studio。

<Note>
  语言模型不随 GenAI Studio 一起提供。您必须[使用 AI Hub 生成模型](/zh/AI-Developer-Workflow-Ubuntu/topic/genai-prepare-ai-hub)。
</Note>

<Steps>
  <Step title="根据构建指南下载并烧录适用于 ubuntu 的构建">
    根据构建指南下载并烧录适用于 ubuntu 的构建。
  </Step>

  <Step title="将存储库克隆到目标设备并进入本地目录">
    ```shell theme={null}
    ssh ubuntu@<ip-address>
    ```

    ```shell theme={null}
    git clone https://github.com/qualcomm/sample-apps-for-qualcomm-linux.git
    ```

    ```shell theme={null}
    cd sample-apps-for-qualcomm-linux/GenAI-Solutions/GenAI-Studio
    ```
  </Step>

  <Step title="在主机上准备 SDK(可选)">
    <Note>
      仅当您要启动完整技术栈或私有 STT 或 TTS 服务时才需要此操作。
    </Note>

    ```shell theme={null}
    qpm-cli --login
    ```

    ```shell theme={null}
    qpm-cli --install VoiceAI_ASR -v 2.6.0.0 --path /opt/qcom/qpm/VoiceAI_ASR/2.6.0.0 --silent
    ```

    ```shell theme={null}
    qpm-cli --install VoiceAI_TTS -v 1.1.1.0 --path /opt/qcom/qpm/VoiceAI_TTS/1.1.1.0 --silent
    ```

    ```shell theme={null}
    export TARGET_REPO=/path/to/genai-studio-on-target
    ```

    ```shell theme={null}
    rsync -av /opt/qcom/qpm/VoiceAI_ASR/2.6.0.0/whisper_sdk/ \
      ubuntu@<target-host>:${TARGET_REPO}/core-services/speech-to-text/whisper_sdk/
    ```

    ```shell theme={null}
    rsync -av /opt/qcom/qpm/VoiceAI_TTS/1.1.1.0/melo_sdk/ \
      ubuntu@<target-host>:${TARGET_REPO}/core-services/text-to-speech/meloTTS/melo_sdk/
    ```
  </Step>

  <Step title="在目标设备上的示例应用存储库根目录中,完成飞行前检查">
    <Note>
      在运行飞行前检查之前,请确保设备已正确置备。
      有关初始设备置备,请参阅
      [设备设置](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/blob/main/GenAI-Solutions/GenAI-Studio/docs/setup/DEVICE_SETUP.md)。
    </Note>

    ```shell theme={null}
    docker --version
    ```

    ```shell theme={null}
    docker-compose version
    ```

    ```shell theme={null}
    python3 --version
    ```

    ```shell theme={null}
    ls -l /dev/fastrpc-cdsp
    ```

    ```shell theme={null}
    ls /etc/cdi/
    ```
  </Step>

  <Step title="为目标准备模型">
    有关更多信息,请参阅每个服务的模型生成和设置文档。

    <Tip>
      在 `/opt/genai-studio-models` 下准备模型文件夹。
    </Tip>

    | 服务    | 目标路径                                                                                                     | 文档                                                                                                                                                                                |
    | ----- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | 文本转文本 | `/opt/genai-studio-models/text-to-text/...`                                                              | [MODEL\_SETUP.md](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/blob/main/GenAI-Solutions/GenAI-Studio/core-services/text-to-text/MODEL_SETUP.md)                    |
    | 图像转文本 | `/opt/genai-studio-models/image-to-text/Lemans_LE_Gen2_QNN2_41_qwen25_vl_7B/files`                       | [MODEL\_SETUP.md](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/blob/main/GenAI-Solutions/GenAI-Studio/core-services/image-to-text/MODEL_SETUP.md)                   |
    | 文本转图像 | `/opt/genai-studio-models/text-to-image/stable_diffusion_v2_1-qnn_context_binary-w8a16-qualcomm_qcs9075` | [MODEL\_SETUP.md](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/blob/main/GenAI-Solutions/GenAI-Studio/core-services/text-to-image/MODEL_SETUP.md)                   |
    | 语音转文本 | `/opt/genai-studio-models/speech-to-text/whisper_tiny-qnn_context_binary-float-qualcomm_qcs9075`         | [MODEL\_SETUP.md](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/blob/main/GenAI-Solutions/GenAI-Studio/core-services/speech-to-text/MODEL_SETUP.md)                  |
    | 文本转语音 | `/opt/genai-studio-models/text-to-speech/melo-tts-v73/files`                                             | [Model-Generation.md](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/blob/main/GenAI-Solutions/GenAI-Studio/core-services/text-to-speech/meloTTS/Model-Generation.md) |
  </Step>

  <Step title="构建基础镜像(一次性设置)">
    导航到 GenAI-Studio 文件夹并运行以下命令:

    ```shell theme={null}
    bash scripts/download-qairt-sdk.sh --service base
    ```

    ```shell theme={null}
    bash scripts/pull-ubuntu-arm64.sh
    ```

    ```shell theme={null}
    DOCKER_BUILDKIT=1 docker build --progress=plain -f Dockerfile.runtime -t ubuntu-runtime:24.04 .
    ```

    ```shell theme={null}
    DOCKER_BUILDKIT=1 docker build --progress=plain -f Dockerfile.build-base -t genai-build-base:latest .
    ```
  </Step>

  <Step title="构建服务镜像">
    请参阅服务的 README 文件(例如 [core-services/README.md](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/blob/main/GenAI-Solutions/GenAI-Studio/core-services/README.md)),
    以确保所有必需文件都已就位。

    ```shell theme={null}
    DOCKER_BUILDKIT=1 docker build --progress=plain -t text-to-text:latest core-services/text-to-text/
    ```

    ```shell theme={null}
    DOCKER_BUILDKIT=1 docker build --progress=plain -t image-to-text:responses-v1 core-services/image-to-text/
    ```

    ```shell theme={null}
    DOCKER_BUILDKIT=1 docker build --progress=plain -t text-to-image:latest core-services/text-to-image/
    ```

    ```shell theme={null}
    DOCKER_BUILDKIT=1 docker build --progress=plain -t speech-to-text:latest core-services/speech-to-text/
    ```

    ```shell theme={null}
    DOCKER_BUILDKIT=1 docker build --progress=plain -t text-to-speech:latest core-services/text-to-speech/meloTTS/
    ```

    ```shell theme={null}
    DOCKER_BUILDKIT=1 docker build --progress=plain -t orchestrator:latest core-services/orchestrator/
    ```
  </Step>

  <Step title="使用 docker-compose 启动服务">
    请参阅 [README](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/tree/main/GenAI-Solutions/GenAI-Studio#7-start-services-with-docker-compose),
    了解在运行 `docker-compose` 之前建议设置的环境变量。

    ```shell theme={null}
    docker-compose up -d
    ```

    ```shell theme={null}
    docker ps
    ```
  </Step>

  <Step title="运行服务健康检查和功能检查以验证所有服务是否正在运行">
    ```shell theme={null}
    curl -sf http://127.0.0.1:8080/health >/dev/null && echo "Image-to-Text (8080) OK"
    ```

    ```shell theme={null}
    curl -sf http://127.0.0.1:8081/health >/dev/null && echo "Speech-to-Text (8081) OK"
    ```

    ```shell theme={null}
    curl -sf http://127.0.0.1:8083/health >/dev/null && echo "Text-to-Speech (8083) OK"
    ```

    ```shell theme={null}
    curl -sf http://127.0.0.1:8084/health >/dev/null && echo "Text-to-Image (8084) OK"
    ```

    ```shell theme={null}
    curl -sf http://127.0.0.1:8088/health >/dev/null && echo "Text-to-Text (8088) OK"
    ```

    ```shell theme={null}
    curl -sf http://127.0.0.1:8090/api/status >/dev/null && echo "Orchestrator (8090) OK"
    ```
  </Step>

  <Step title="在主机上运行统一测试套件">
    ```shell theme={null}
    python3 -m pip install --user -r tests/unified/requirements.txt
    ```

    ```shell theme={null}
    python3 tests/unified/run_manifest.py --target-host <TARGET_DEVICE_IP>
    ```

    有关功能端点检查和测试,请参阅
    [功能端点测试](https://github.com/qualcomm/sample-apps-for-qualcomm-linux/tree/main/GenAI-Solutions/GenAI-Studio#3-functional-endpoint-tests)
    以及各个服务的 README 文件。
  </Step>

  <Step title="通过 Orchestrator 访问">
    打开浏览器并访问以下 URL:

    ```shell theme={null}
    http://<device-ip>:8090
    ```
  </Step>
</Steps>

如果任何服务无法收集日志,请参阅该服务 `docs` 文件夹中的故障排除和痛点文档。

要检查服务日志,请运行以下命令:

```shell theme={null}
docker compose ps
```

```shell theme={null}
docker logs --tail 200 text-to-text
```

```shell theme={null}
docker logs --tail 200 image-to-text
```

```shell theme={null}
docker logs --tail 200 text-to-image
```

```shell theme={null}
docker logs --tail 200 speech-to-text
```

```shell theme={null}
docker logs --tail 200 text-to-speech
```

```shell theme={null}
docker logs --tail 200 orchestrator
```