阿里云百炼API + Ollama本地部署：大模型开发环境配置全攻略（含PyCharm环境变量避坑指南）

引言

在AI应用开发中，大模型API和本地模型的灵活切换是一项实用技能。本文将带你从零开始，完成阿里云百炼平台 的API配置，并备选Ollama本地部署方案，实现云+本地的开发环境搭建。特别是针对PyCharm中环境变量配置的常见问题，我将提供两种有效方案，帮助你彻底解决"终端设置了Key但IDE读不到"的烦恼。同时，我们还会展示如何调用阿里云百炼的深度思考模型，并正确处理思考过程与最终回复的流式输出。

一、准备工作

1. 注册阿里云百炼账号

访问阿里云官网，开通百炼平台服务。
获取API Key：在控制台中找到API Key管理，创建并复制你的密钥（格式通常为sk-xxxx）。
示例：sk-69acb7bd3feb4112a3e0f464bb14651b（请替换为你自己的Key）

⚠️ 安全提醒：API Key是重要凭证，切勿上传至公开代码仓库或泄露给他人。

2. 安装Python开发环境

推荐使用PyCharm作为IDE。
确保已安装Python 3.8+。

二、配置Python环境与国内镜像

使用清华镜像源加速openai库的安装：

bash

复制代码

pip3 install openai -i https://pypi.tuna.tsinghua.edu.cn/simple

若使用PyCharm，可在Settings > Project: xxx > Python Interpreter中添加镜像源。

三、配置环境变量（存储API Key）

环境变量配置是很多新手容易踩坑的地方，尤其是PyCharm无法读取终端已设置的变量。下面提供两种方法，推荐使用方法二（PyCharm直接配置），避免终端与IDE环境不一致的问题。

方法一：终端配置（适用于命令行运行）

以macOS/Linux的zsh为例：

打开终端，输入：

bash
复制代码
```
open ~/.zshrc
```

在文件末尾添加：

bash

复制代码

export DASHSCOPE_API_KEY="sk-your-api-key"

保存并生效：

bash
复制代码
```
source ~/.zshrc
```
验证：echo $DASHSCOPE_API_KEY 应显示你的Key。

⚠️ 如果PyCharm中运行脚本无法读取该变量，说明IDE没有继承终端的环境变量。此时需要用方法二。

方法二：PyCharm运行配置直接设置（推荐）

这是最可靠的方法，可以确保你的Python脚本在PyCharm中运行时能获取到正确的环境变量。

在PyCharm中打开你的项目，点击右上角的"当前文件"运行配置下拉框，选择 "编辑配置..." （或 Run > Edit Configurations）。
在左侧找到你的Python脚本（如01测试apikey的使用），如果没有，点击+号添加一个Python配置。
在右侧的 "环境变量" 一栏，点击文件夹图标，打开编辑窗口。
点击+号，添加一行：
- 变量名 ：DASHSCOPE_API_KEY
- 变量值 ：sk-69acb7bd3feb4112a3e0f464bb14651b（你的实际API Key）
点击确定，保存配置。
再次运行脚本，Python代码中通过os.getenv("DASHSCOPE_API_KEY")即可获取。

💡 提示：如果同时存在终端配置和PyCharm配置，PyCharm配置优先级更高，方便你为不同项目使用不同Key。

常见问题与解决

配置后仍然无效 ：尝试 File > Invalidate Caches... 清除缓存并重启PyCharm。
关机重启仍不行：大概率是PyCharm未正确加载配置，请重复方法二并确认保存。也可以检查PyCharm右下角是否选对了Python解释器。

四、调用阿里云百炼API（云平台方式）

阿里云百炼兼容OpenAI SDK，以下为调用示例（注意使用上面配置的环境变量，并处理深度思考模型的思考过程）：

python

复制代码

import os
from openai import OpenAI

# 从环境变量读取API Key
api_key = os.getenv("DASHSCOPE_API_KEY")
if not api_key:
    raise ValueError("请在环境变量中设置 DASHSCOPE_API_KEY")

client = OpenAI(
    api_key=api_key,
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)

messages = [{"role": "user", "content": "你能做什么"}]

# 发送请求，启用深度思考（enable_thinking=True），并开启流式输出
completion = client.chat.completions.create(
    model="gpt-oss:120b-cloud",      # 深度思考模型示例
    messages=messages,
    extra_body={"enable_thinking": True},
    stream=True
)

# 流式输出：区分思考过程和最终回复
is_answering = False
print("\n" + "=" * 20 + "思考过程" + "=" * 20)
for chunk in completion:
    delta = chunk.choices[0].delta
    # 思考内容（reasoning_content）
    if hasattr(delta, "reasoning_content") and delta.reasoning_content is not None:
        if not is_answering:
            print(delta.reasoning_content, end="", flush=True)
    # 最终回复内容（content）
    if hasattr(delta, "content") and delta.content:
        if not is_answering:
            print("\n" + "=" * 20 + "完整回复" + "=" * 20)
            is_answering = True
        print(delta.content, end="", flush=True)

阿里云百炼提供了丰富的模型选择，包括qwen3-max、gpt-oss:120b-cloud等。你可以根据需求更换model参数。

五、Ollama本地部署（备用方案）

当云平台额度用尽或需要离线使用时，可选择本地部署轻量化模型。

1. 安装Ollama

访问Ollama官网，下载对应操作系统安装包并安装。

2. 理解"蒸馏"大模型

"蒸馏"模型可以理解为瘦身版的大模型，参数量更小、推理更快，适合资源有限的本地环境。

3. 硬件选型建议

根据显卡配置选择合适的模型规模：

硬件配置	推荐参数量
集成显卡	≤1.5B
4GB 独显	≤8B
8GB 独显	≤14B

参数量越大，对硬件要求越高，推理速度也会相应变慢。

4. 下载并运行模型

bash

复制代码

# 示例：运行一个7B模型
ollama run llama2:7b

5. Python调用Ollama

python

复制代码

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"  # 任意占位符
)

response = client.chat.completions.create(
    model="llama2:7b",
    messages=[{"role": "user", "content": "你好"}]
)

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

六、云+本地切换策略（优先使用阿里云）

在实际开发中，可设置一个配置开关，优先使用阿里云，当出现异常或需要节省额度时再切换到本地Ollama。以下代码演示了如何优雅地实现切换：

python

复制代码

import os
from openai import OpenAI

# 配置项
PREFER_CLOUD = True  # 优先使用阿里云，额度用完后改为 False

def get_client_and_model():
    if PREFER_CLOUD:
        api_key = os.getenv("DASHSCOPE_API_KEY")
        if not api_key:
            raise ValueError("请在环境变量中设置 DASHSCOPE_API_KEY")
        client = OpenAI(
            api_key=api_key,
            base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
        )
        model = "gpt-oss:120b-cloud"  # 阿里云深度思考模型
        use_stream = True
    else:
        client = OpenAI(
            base_url="http://localhost:11434/v1",
            api_key="ollama"
        )
        model = "llama2:7b"  # 本地模型
        use_stream = False
    return client, model, use_stream

# 调用
client, model, use_stream = get_client_and_model()

messages = [{"role": "user", "content": "你能做什么"}]

if use_stream:
    completion = client.chat.completions.create(
        model=model,
        messages=messages,
        extra_body={"enable_thinking": True} if PREFER_CLOUD else None,
        stream=True
    )
    # 流式处理（同上）
    is_answering = False
    print("\n" + "=" * 20 + "思考过程" + "=" * 20)
    for chunk in completion:
        delta = chunk.choices[0].delta
        if hasattr(delta, "reasoning_content") and delta.reasoning_content is not None:
            if not is_answering:
                print(delta.reasoning_content, end="", flush=True)
        if hasattr(delta, "content") and delta.content:
            if not is_answering:
                print("\n" + "=" * 20 + "完整回复" + "=" * 20)
                is_answering = True
            print(delta.content, end="", flush=True)
else:
    completion = client.chat.completions.create(
        model=model,
        messages=messages
    )
    print(completion.choices[0].message.content)

七、完整代码示例（阿里云版本，含思考过程）

python

复制代码

import os
from openai import OpenAI

api_key = os.getenv("DASHSCOPE_API_KEY")
if not api_key:
    raise ValueError("请在环境变量中设置 DASHSCOPE_API_KEY")

client = OpenAI(
    api_key=api_key,
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)

messages = [{"role": "user", "content": "你能做什么"}]

completion = client.chat.completions.create(
    model="gpt-oss:120b-cloud",
    messages=messages,
    extra_body={"enable_thinking": True},
    stream=True
)

is_answering = False
print("\n" + "=" * 20 + "思考过程" + "=" * 20)
for chunk in completion:
    delta = chunk.choices[0].delta
    if hasattr(delta, "reasoning_content") and delta.reasoning_content is not None:
        if not is_answering:
            print(delta.reasoning_content, end="", flush=True)
    if hasattr(delta, "content") and delta.content:
        if not is_answering:
            print("\n" + "=" * 20 + "完整回复" + "=" * 20)
            is_answering = True
        print(delta.content, end="", flush=True)

八、总结与避坑指南

问题	解决方案
终端配置的环境变量PyCharm读不到	改用PyCharm运行配置中的环境变量设置
修改配置后不生效	清理缓存（File > Invalidate Caches）并重启
云平台API调用超时	检查网络，或切换本地Ollama测试
本地Ollama模型下载慢	可手动下载模型文件放入`~/.ollama/models`
`openai`库导入失败	确认已用清华镜像安装，或检查Python解释器
深度思考模型没有输出思考过程	确认`extra_body={"enable_thinking": True}`已设置，并正确处理`reasoning_content`字段

通过以上配置，你可以轻松在云平台和本地模型间切换，既享受云端的强大算力，又能在离线时继续开发。希望本文能帮助你少走弯路，快速搭建起大模型开发环境。