安装

本指南将帮助您安装QLLVM项目，包括从插件进行安装和从源码进行安装两种方式。

从插件进行安装

我们提供了两个VSCode插件，让您可以直接使用QLLVM编译器，无需本地安装：

  1. qcoder-chat：量子编程小助手，提供AI对话编程、智能代码补全与自主Agent任务执行。

  2. qcoder-compiler：量子编译工具，支持多编译器并行编译、QIR模拟器运行等功能。

从VSCode插件商店安装

_images/007.png

VSCode插件商店检索

通过云端 VSCode 一键安装插件，操作简单快捷：

  1. 打开云端 VSCode 左侧的 **扩展面板**（快捷键：Ctrl+Shift+X）；

  2. 在扩展搜索框中输入 qcflow-publisher.qcoder-chat 并搜索；

  3. 点击 安装 按钮，系统将自动安装以下两个插件：

    • qcflow-publisher.qcoder-chat

    • qcflow-publisher.qcoder-compiler

  4. 安装完成后，插件自动生效，即可使用智能编程、编译及运行服务。

从VSIX文件安装

1. 获取插件安装包

下载仓库中的插件安装包：

  • ./plugin/qcflow-publisher.qcoder-compiler-0.1.0.vsix

  • ./plugin/qcflow-publisher.qcoder-chat-0.1.1.vsix

2. 安装 VSIX 文件

① 打开命令面板

使用快捷键 Ctrl+Shift+P (Windows/Linux) 或 Cmd+Shift+P (macOS)
② 输入并选择命令

Extensions: Install from VSIX...
③ 选择文件

依次选择已下载的 .vsix 文件完成安装

基本配置

Quantum Compiler配置

  1. 打开编译器设置：在命令面板中输入 Open Quantum Compiler Settings

  2. 启用编译器：在配置界面中勾选需要的编译器（如QLLVM、Qiskit、QPanda）

  3. 配置编译器参数：

    • QLLVM：设置设备类型（NISQ/FTQC）、后端类型（qasm-backend/benyuan/tianyan/zheda）、优化等级（O0/O1）等

    • Python环境：支持自动检测系统Python、虚拟环境（venv/conda），或手动指定解释器路径

qcoder-chat配置

_images/018.png

  1. 通过 模型管理 添加模型信息

    _images/019.png

  1. 可选配置：

    • Ask/Agent模式：Ask模式仅提供聊天交互功能；Agent模式提供写入文件、查询报错信息、调用QLLVM编译、调用QLLVM运行等工具。

    • 深度思考模式：用于选择大模型是否进行深度思考。部分模型因自身限制只能深度思考，无法取消。

    • 在线服务：用于启用量子领域专用知识库，通过RAG技术增强量子编程能力。

从源码进行安装

如果您需要直接在本地环境中使用QLLVM命令行工具或进行自定义开发，可以选择从源码编译安装。

环境要求

依赖项

版本要求

LLVM 预编译版本

12.0.0

Ubuntu 版本

20.04+

Python 版本

3.10+

通用依赖

在系统中执行以下命令，安装系统基础依赖

# 系统基础依赖
sudo apt-get update
sudo apt-get install -y build-essential cmake ninja-build \
  libcurl4-openssl-dev libssl-dev liblapack-dev libblas-dev \
  lsb-release git
# 额外依赖
sudo apt-get install -y libantlr4-runtime-dev libeigen3-dev

LLVM/MLIR：QLLVM 需要带 MLIR 的 LLVM。推荐使用预编译包，或从 llvm-project-csp 源码编译（启用 clang;mlir）。

下载并安装 LLVM 12.0.0 预编译包

下载并解压到 $HOME/.llvm：

# 使用 wget 直接下载并解压
wget https://github.com/llvm/llvm-project/releases/download/llvmorg-12.0.0/clang+llvm-12.0.0-x86_64-linux-gnu-ubuntu-20.04.tar.xz
tar -xf clang+llvm-12.0.0-x86_64-linux-gnu-ubuntu-20.04.tar.xz
mv clang+llvm-12.0.0-x86_64-linux-gnu-ubuntu-20.04 ~/.llvm

# 将 LLVM 添加到环境变量：

echo 'export PATH="$HOME/.llvm/bin:$PATH"' >> ~/.bashrc
echo 'export LLVM_HOME="$HOME/.llvm"' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH="$HOME/.llvm/lib:$LD_LIBRARY_PATH"' >> ~/.bashrc
source ~/.bashrc

# 安装依赖包：
sudo apt install zlib1g-dev libtinfo-dev

QLLVM构建

# 克隆仓库
git clone https://github.com/QCFlow/QLLVM.git
cd QLLVM

# 构建和安装
mkdir build && cd build
cmake .. -G Ninja \
  -DQLLVM_QASM_ONLY_BUILD=ON \
  -DLLVM_ROOT=$HOME/.llvm
ninja
ninja install

安装路径：默认安装到 ~/.qllvm。在 ninja install 过程中，会自动将 ~/.qllvm/bin 添加到当前用户的 shell 配置（.bashrc/.profile）。打开新终端后即可使用。也可以手动添加：

export PATH=$PATH:$HOME/.qllvm/bin

验证和测试

# 运行测试脚本
./scripts/test_openqasm_only.sh

# 手动验证
qllvm test/test_bell.qasm -qrt nisq -qpu qasm-backend -O1
cat test/test_bell_compiled.qasm

可选依赖（按需安装）

功能

依赖

安装方法

QIR Runner 模拟器

qir-runner, Python 3.9+

pip install qirrunner

C++ + CUDA + QASM 混合程序编译

CUDA Toolkit, nvcc, qir-runner

见下文 CUDA 环境

CUDA环境（仅C+++CUDA+QASM混合需要）

如果需要编译 examples/hybrid_cuda 等 C++ + CUDA + QASM 混合程序，需要安装 CUDA Toolkit。

方法一：Ubuntu apt 安装（推荐）

# 在 qllvm 仓库根目录执行
bash scripts/install_cuda_apt.sh

该脚本会安装 nvidia-cuda-toolkit 并创建 Clang 兼容目录 ~/.qllvm/cuda-apt-compat。安装后，当 nvcc 可用时，qllvm 会自动使用 nvcc 编译 .cu 文件。

方法二：NVIDIA 官方 runfile

从 [NVIDIA CUDA 下载页面](https://developer.nvidia.com/cuda-downloads) 下载 runfile，执行 --toolkit 仅安装工具链。安装后设置：

export CUDA_PATH=/usr/local/cuda
export PATH=$CUDA_PATH/bin:$PATH

注意：编译混合程序不需要物理 GPU；运行生成的 hybrid_app 需要 NVIDIA 显卡和驱动。

故障排除

如果您在安装过程中遇到问题，请尝试以下解决方法：

  1. 依赖问题：确保所有依赖项都已正确安装

  2. LLVM版本：确保使用的LLVM版本与QLLVM兼容

  3. 权限问题：使用管理员权限或sudo安装

  4. 网络问题：确保网络连接正常，尤其是在从GitHub克隆代码时

如果问题仍然存在，请在GitHub上提交 Issue。