从零到进阶做 Agent（一）开篇与环境准备

这是一个面向小白到进阶的系列。我们会从「调用一次大模型」一路做到「能查资料、能调工具、能生成报告的智能客服 Agent」。全程给出 Python 和 Node.js 两套代码，你可以用页面顶部的「代码语言」开关一键切换成自己顺手的语言（选择会被记住，下次打开还是它）。

这个系列会讲什么

整条主线由浅入深，大致是三大块：

打基础——搞清楚大模型怎么调用（普通调用、流式输出、多轮对话），以及提示词（Prompt）该怎么写才靠谱。

做 RAG——让模型「带着你的资料回答」。会讲文档加载、切分、向量化、向量库检索，最后手搓一个能上传文件问答的应用。

做 Agent——让模型不只是聊天，而是能自己决定「要不要查知识库、要不要调用天气接口、要不要生成报告」，也就是工具调用与 ReAct，最后收尾一个综合实战项目。

先厘清两个词

大模型（LLM） 你可以先粗暴理解成一个「超强的文字接龙机器」：给它一段话，它按概率续写出最可能的下文。它不联网、不记得你上次说了啥，知识也停在训练那一刻。

RAG（检索增强生成） 就是在提问前，先从你自己的资料库里检索出相关片段，拼进提示词一起喂给模型，让它「看着材料回答」。这样能回答私有知识、也能减少胡编。

Agent（智能体） 则是在大模型外面套了一层「决策循环」：模型先思考需要什么，再选择调用哪个工具（搜索、计算、查数据库……），拿到结果后继续思考，直到能给出最终答案。RAG 往往是 Agent 手里的一件工具。

三者的关系：LLM 是发动机，RAG 是给它喂料的方式之一，Agent 是让它能自己动手的框架。

环境准备

1. 语言运行时

Python 侧建议 3.10 以上；Node.js 侧建议 18 以上（这样自带 fetch，装依赖也省心）。两套环境相互独立，你用哪种就装哪种。

PythonNode.js

bash

# 建一个独立虚拟环境，避免污染全局
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
python --version               # 确认 >= 3.10

bash

# 初始化一个项目
mkdir agent-demo && cd agent-demo
npm init -y
node --version                 # 确认 >= 18

2. 装依赖

本系列 Python 侧用 openai 和 langchain 全家桶，Node 侧用 openai 和 langchain 的 JS 版本。这一篇先把最基础的 SDK 装上，后面用到别的再补。

PythonNode.js

bash

pip install openai

bash

npm install openai

3. 拿一个 API Key

我们全程用阿里云百炼（通义千问）的模型，原因有二：国内访问稳定；而且它提供 OpenAI 兼容接口，意味着 Python/Node 都能直接用大家最熟悉的 openai SDK，只要把请求地址（base URL）指到百炼即可，代码几乎和调用 OpenAI 一模一样。

去阿里云百炼控制台开通并创建一个 API Key。不要把 Key 直接写进代码（容易泄露、也不方便多处复用），而是设成环境变量，代码里再用 os.getenv / process.env 读取。

设置环境变量分「临时」和「永久」两种：临时的只在当前这个终端窗口有效，关掉就没了，适合快速试；永久的写进配置文件，之后每个新开的终端都能用。下面按操作系统分别说明。

macOS / Linux

macOS 现在默认用 zsh，但也有人用 bash，两者的配置文件不一样，先搞清楚你用的是哪个。在终端里执行：

bash

echo $SHELL

如果输出里带 zsh（比如 /bin/zsh），你的配置文件就是 ~/.zshrc；如果带 bash，则是 ~/.bash_profile（macOS 上登录终端读这个，Linux 上通常是 ~/.bashrc）。认准这一个文件改就行，别两个都改，免得混乱。

bash

# 临时：只在当前终端窗口有效（关掉即失效，适合快速测试）
export DASHSCOPE_API_KEY="sk-你的key"

# 永久：写进配置文件，以后每个新终端都生效
# zsh 用户（多数 macOS）：
echo 'export DASHSCOPE_API_KEY="sk-你的key"' >> ~/.zshrc
source ~/.zshrc      # 让改动立即生效，不用重开终端

# bash 用户改成对应文件即可：
# echo 'export DASHSCOPE_API_KEY="sk-你的key"' >> ~/.bash_profile
# source ~/.bash_profile

小贴士：>> 是「追加一行」到文件末尾，不会覆盖原内容；source 是「重新加载」配置文件，让新加的变量在当前窗口立刻可用（否则要新开一个终端才生效）。

Windows

Windows 推荐用 PowerShell。同样分临时和永久：

powershell

# 临时：只在当前 PowerShell 窗口有效
$env:DASHSCOPE_API_KEY = "sk-你的key"

# 永久：写入用户级环境变量（对以后所有新窗口生效，当前窗口需重开）
setx DASHSCOPE_API_KEY "sk-你的key"

setx 写的是持久化的用户环境变量，但不会影响当前已打开的窗口——设完请新开一个 PowerShell 再用。你也可以用图形界面设置：设置 → 系统 → 关于 → 高级系统设置 → 环境变量，在「用户变量」里新建 DASHSCOPE_API_KEY。

验证是否设置成功

设完后，在新终端里打印一下，能回显出你的 Key 就说明成功了：

macOS / LinuxWindows

bash

echo $DASHSCOPE_API_KEY

powershell

echo $env:DASHSCOPE_API_KEY

通义千问的 OpenAI 兼容地址是 https://dashscope.aliyuncs.com/compatible-mode/v1，聊天模型可用 qwen-plus / qwen-turbo，后面讲向量化时会用到嵌入模型 text-embedding-v3。整个系列的示例默认用这套配置。

跑通第一个「Hello 大模型」

理论说再多不如亲手跑一次。下面这段代码给模型发一句话，把回复打印出来。注意两边的写法有多像——这正是选用 OpenAI 兼容接口的好处。切换顶部的语言开关，对照着看：

PythonNode.js

python

import os
from openai import OpenAI

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

resp = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "你是一个乐于助人的助手。"},
        {"role": "user", "content": "用一句话解释什么是大模型。"},
    ],
)

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

javascript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
});

const resp = await client.chat.completions.create({
  model: "qwen-plus",
  messages: [
    { role: "system", content: "你是一个乐于助人的助手。" },
    { role: "user", content: "用一句话解释什么是大模型。" },
  ],
});

console.log(resp.choices[0].message.content);

代码里最关键的是 messages 这个数组——它是你和模型对话的载体。数组里每条消息都带一个 role（角色），常见的有三种：

system（系统）：给模型定「人设」和规则，比如「你是一个乐于助人的助手」「回答要简洁」。通常放在最前面、只写一次，它会影响模型接下来所有的回答风格。
user（用户）：用户说的话，也就是你的提问。
assistant（助手）：模型自己之前的回复。单轮对话用不到它；但要做多轮对话时，需要把模型上一轮的回答用这个角色放回数组里，模型才「记得」聊过什么。

换句话说，模型接口本身是「无记忆」的——它不会自动记得上一句，是我们每次把带角色的完整对话历史发过去，它才能接上下文。这一篇先用 system + user 打个招呼就够了，assistant 角色和多轮记忆下一篇《大模型调用基础》会专门讲。

运行它：

PythonNode.js

bash

python hello.py

bash

node hello.mjs      # 用 .mjs 后缀或在 package.json 里设 "type": "module"

如果终端里打印出了模型的一句话回答，恭喜，环境全部就位。

小结与预告

这一篇我们厘清了 LLM / RAG / Agent 的关系，搭好了 Python 和 Node 两套环境，并用一段几乎对称的代码跑通了第一次模型调用。你也顺手体验了本系列的「双语言切换」阅读方式。

三个关键词记住即可：兼容接口（一套 openai SDK 通吃）、环境变量存 Key（安全）、messages 数组（对话的基本载体，下一篇细讲）。

下一篇《大模型调用基础》，我们把这段调用拆开揉碎：messages 里的角色到底是什么、如何做流式输出（打字机效果）、以及如何让模型记住多轮对话。

从零到进阶做 Agent（一）开篇与环境准备

这个系列会讲什么 ​

先厘清两个词 ​

环境准备 ​

1. 语言运行时 ​

2. 装依赖 ​

3. 拿一个 API Key ​

macOS / Linux ​

Windows ​

验证是否设置成功 ​

跑通第一个「Hello 大模型」 ​

小结与预告 ​

这个系列会讲什么

先厘清两个词

环境准备

1. 语言运行时

2. 装依赖

3. 拿一个 API Key

macOS / Linux

Windows

验证是否设置成功

跑通第一个「Hello 大模型」

小结与预告