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

# 安装

> 从 PyPI 或源码安装 QitOS，并按需启用模型与基准测试扩展组件。

<Warning>
  QitOS 当前处于 **Alpha** 阶段。核心 `AgentModule + Engine` 执行内核（kernel）、追踪（tracing）与规范化示例相对稳定；更高层 API 仍可能在版本间演进。用于生产环境时请固定版本号。
</Warning>

## 环境要求

QitOS 需要 **Python 3.10 及以上**。当前测试覆盖 Python 3.10、3.11 和 3.12。

<Note>
  如果你还没有远程模型 API，可以先看 [前置准备](/zh/prerequisites)，其中整理了推荐平台、API 密钥获取方式和最小连通性验证。
</Note>

## 标准安装

从 PyPI 安装核心框架：

```bash theme={null}
pip install qitos
```

核心安装包含：

* `AgentModule + Engine` 执行内核
* `qita` 可观测性工具
* `kit` 工具箱模块

它默认不包含 OpenAI 客户端，也不包含基准测试（benchmark）数据集加载器。

<Tip>
  如果你想马上运行最小编程智能体（coding agent）快速入门，直接安装 `pip install "qitos[models]"` 即可。
</Tip>

## 可选扩展组件（extras）

通过扩展组件按需加入模型支持、基准测试依赖，或一次性安装全部组件。

<CodeGroup>
  ```bash 模型支持 theme={null}
  pip install "qitos[models]"
  ```

  ```bash 基准测试适配器 theme={null}
  pip install "qitos[benchmarks]"
  ```

  ```bash 全部安装 theme={null}
  pip install "qitos[all]"
  ```
</CodeGroup>

| 扩展组件         | 增加的内容                                   |
| ------------ | --------------------------------------- |
| `models`     | `openai>=1.0.0`，用于兼容 OpenAI 的模型接口       |
| `benchmarks` | `datasets`、`huggingface_hub` 等基准测试适配器依赖 |
| `all`        | 以上全部                                    |

<Tip>
  如果你刚开始接触 QitOS，最推荐 `pip install "qitos[models]"`。这足以跑通最小编程智能体快速入门和大部分示例。
</Tip>

## 从源码安装

克隆仓库后，以可编辑模式安装，并带上开发依赖：

```bash theme={null}
git clone https://github.com/Qitor/qitos.git
cd qitos
pip install -e ".[dev,models,benchmarks]"
```

`dev` 扩展组件会安装 `pytest`、`black`、`flake8`、`mypy` 以及 QitOS 团队使用的打包工具。

## 验证安装

确认包是否安装成功，并查看版本：

```bash theme={null}
python -c "import qitos; print(qitos.__version__)"
```

你应该能看到：

```
0.3.0
```

也可以顺便验证最小编程智能体和两个命令行工具（CLI）是否已进入 PATH：

```bash theme={null}
qit demo minimal
qit --help
qita --help
```

## 接下来推荐

<CardGroup cols={2}>
  <Card title="快速开始" icon="rocket" href="/zh/quickstart">
    2 分钟内运行你的第一个智能体（agent）
  </Card>

  <Card title="核心概念" icon="book" href="/zh/concepts/agent-module">
    理解 AgentModule、Engine、State 和 Tools
  </Card>
</CardGroup>