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

# 前置准备

> 注册远程模型服务、获取 API 密钥，并在运行 QitOS 前完成基础连通性验证。

在运行任何依赖大语言模型（LLM）的 QitOS 示例之前，你需要先准备一个远程模型 API。

QitOS 对兼容 OpenAI 的服务商（provider）适配最为直接。只要你能拿到以下信息，通常就能开始使用：

* 账号
* API 密钥
* 基础地址（Base URL）
* 可调用的模型名称

## 推荐的远程模型平台

如果你刚开始使用 QitOS，下面两个平台是比较实用的起点：

* [SiliconFlow](https://www.siliconflow.cn/)
* [阿里云百炼 / Model Studio](https://bailian.console.aliyun.com/)

这两个平台都提供兼容 OpenAI 的接口。注册流程、价格与试用额度会随时间调整，请以控制台和官方计费页的最新信息为准。

## 方案一：SiliconFlow

根据 SiliconFlow 官方快速上手文档，基本流程是：

1. 登录 [SiliconFlow 官网](https://www.siliconflow.cn/)
2. 打开 [API 密钥页面](https://cloud.siliconflow.cn/)
3. 新建 API 密钥
4. 在模型广场选择你要调用的模型
5. 使用其兼容 OpenAI 的基础地址：

```text theme={null}
https://api.siliconflow.cn/v1
```

官方快速上手页面还给出了使用 OpenAI Python SDK 直接调用的示例。

## 方案二：阿里云百炼 / Model Studio

根据阿里云百炼官方文档，基本流程是：

1. 登录 [百炼控制台](https://bailian.console.aliyun.com/)
2. 在目标地域打开 API 密钥页面
3. 创建 API 密钥
4. 复制并妥善保管 API 密钥
5. 使用对应地域的兼容 OpenAI 的基础地址

以北京地域为例，官方兼容地址是：

```text theme={null}
https://dashscope.aliyuncs.com/compatible-mode/v1
```

阿里云百炼的官方计费说明也提到，控制台可能会提供面向符合条件用户的试用额度或免费试用入口。具体额度和有效期请以你账号下看到的最新活动为准。

## 设置环境变量

拿到 API 密钥和基础地址后，先设置环境变量：

```bash theme={null}
export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://api.siliconflow.cn/v1"
```

如果使用百炼：

```bash theme={null}
export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
```

## 先做一次最小连通性验证

在正式运行 QitOS 之前，建议先用 OpenAI SDK 做一次最小测试：

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="YOUR_BASE_URL",
)

response = client.chat.completions.create(
    model="YOUR_MODEL_NAME",
    messages=[{"role": "user", "content": "Say hello from QitOS."}],
)

print(response.choices[0].message.content)
```

如果这段代码能正常返回内容，通常就说明你的服务商配置已经可以用于 QitOS。

## 在 QitOS 里需要填什么

在最简单的兼容 OpenAI 的场景下，你通常只需要这三项：

* `api_key`
* `base_url`
* `model`

例如：

```python theme={null}
from qitos.models import OpenAICompatibleModel

llm = OpenAICompatibleModel(
    model="Qwen/Qwen2.5-72B-Instruct",
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ["OPENAI_BASE_URL"],
)
```

## 安全提醒

<Warning>
  不要把 API 密钥提交到仓库、截图、示例代码或共享的追踪产物（trace artifacts）中。优先使用环境变量、密钥管理服务或服务商提供的临时凭证。
</Warning>

## 下一步

准备好远程模型后，继续阅读 [快速开始](/zh/quickstart) 或 [构建第一个智能体](/zh/guides/build-your-first-agent)。