01 基础大模型调用

字数: (11370)

阅读: (478)

0

1 背景

本节课只解决一个问题：怎么用最简单的代码调用一次大模型。
先不要急着学 CoT、ReAct、工具调用、记忆、多 Agent。因为这些能力最后都会回到同一个基础动作：

把问题发给大模型
→ 大模型返回答案
→ 程序拿到答案继续处理

如果这一步都不能稳定运行，后面写 Agent 时会很痛苦。

1.1 本节课要做什么

本节课只做四件事：

说明现在常见的大模型调用方式
说明为什么本节先使用 OpenAI 兼容接口
写一个简单的 llm.py
写一个简单的 main.py，运行后能看到模型输出
本节课不追求封装得很完整，也不做太多抽象。代码要做到：高中生看得懂，复制下来能运行，后面课程能继续复用。

2 当前有几种大模型调用方式

2.1 第一种：官方原生接口

每个大模型厂商一般都有自己的官方接口。
例如：

厂商	常见接口方式	说明
OpenAI	OpenAI SDK、Responses API、Chat Completions API	OpenAI 自己的官方接口
Anthropic Claude	Anthropic SDK、Messages API	Claude 原生接口
Google Gemini	Google Gen AI SDK、Gemini API	Gemini 原生接口

这种方式的好处是能力最完整，坏处是每家写法不完全一样。你刚开始学习时，如果一上来同时适配 OpenAI、Claude、Gemini，很容易被 SDK 差异打断思路。

2.2 第二种：OpenAI 兼容接口

很多模型厂商支持 OpenAI 兼容接口。
简单说，就是它们让你继续使用 OpenAI SDK，只需要改三样东西：

API Key
Base URL
Model Name

常见支持 OpenAI 兼容接口的平台包括：

平台	说明
OpenAI	原始 OpenAI 接口
DeepSeek	支持 OpenAI 兼容格式
阿里云百炼 Qwen	支持 OpenAI 兼容模式
Moonshot Kimi	支持 OpenAI 兼容格式
智谱 GLM	支持 OpenAI 兼容格式

这就是本节课选择 OpenAI 兼容接口的原因：代码最少，迁移最简单，适合入门。

2.3 第三种：统一网关

还有一种方式是使用 LiteLLM、One API、公司内部网关这类统一代理。
它的作用是把多个模型包装成一个统一入口：

业务代码
→ 模型网关
→ OpenAI / DeepSeek / Qwen / Claude / Gemini

这种方式适合团队使用，但不适合第一节课。因为它又多引入了一层系统，初学者很容易不知道问题出在代码、网关还是模型服务。

2.4 本节课的推荐做法

本节课推荐：

先用 OpenAI SDK
→ 连接一个 OpenAI 兼容模型
→ 跑通最小调用
→ 后面课程全部复用这个 LLM 客户端

这样后面写 CoT 时，只需要关注 prompt 怎么写；写 ReAct 时，只需要关注模型怎么推理和行动；写工具调用时，再扩展工具参数即可。

3 一次大模型调用需要哪些信息

3.1 最少需要三个配置

一次大模型调用最少需要三个配置：

配置	含义	示例
`LLM_MODEL_ID`	要调用哪个模型	`deepseek-chat`、`qwen-plus`、`kimi-k2.5`
`LLM_API_KEY`	你的 API 密钥	`sk-xxxx`
`LLM_BASE_URL`	模型服务地址	`https://api.deepseek.com`

可以把它理解成点外卖：

LLM_MODEL_ID：你要点哪道菜
LLM_API_KEY：证明这是你的账号
LLM_BASE_URL：外卖平台地址

3.2 为什么配置放到 .env

不要把 API Key 写死在 Python 代码里。
不推荐：

api_key = "sk-xxxx"

4 项目结构

4.1 最终目录

创建一个目录：

agent-course-01-llm-call/
├── .env
├── llm.py
├── main.py
└── requirements.txt

每个文件的作用如下：

文件	作用
`.env`	放模型配置和 API Key
`llm.py`	封装大模型调用
`main.py`	写一个最小运行示例
`requirements.txt`	放 Python 依赖

5 安装依赖

5.1 创建 requirements.txt

创建 requirements.txt：

openai
python-dotenv

这里只安装两个包：

openai：用来调用 OpenAI 兼容接口
python-dotenv：用来读取 .env 配置

5.2 安装依赖

执行：

pip install -r requirements.txt

如果你的电脑需要使用 pip3，就执行：

pip3 install -r requirements.txt

5.3 验证安装

执行：

python -c "from openai import OpenAI; from dotenv import load_dotenv; print('ok')"

预期输出：

ok

如果这里都不能运行，先不要继续写代码，先解决 Python 环境和依赖安装问题。

6 配置 .env

6.1 创建 .env 文件

创建 .env：

LLM_MODEL_ID=deepseek-chat
LLM_API_KEY=你的API_KEY
LLM_BASE_URL=https://api.deepseek.com
LLM_TIMEOUT=60

把 你的API_KEY 换成真实的 API Key。

6.2 不同平台的配置示例

如果你使用 DeepSeek：

LLM_MODEL_ID=deepseek-chat
LLM_API_KEY=你的DeepSeek_API_KEY
LLM_BASE_URL=https://api.deepseek.com
LLM_TIMEOUT=60

如果你使用阿里云百炼 Qwen：

LLM_MODEL_ID=qwen-plus
LLM_API_KEY=你的DASHSCOPE_API_KEY
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_TIMEOUT=60

如果你使用OpenAI：

如果你使用 OpenAI：
```bash
LLM_MODEL_ID=gpt-5-mini
LLM_API_KEY=你的OPENAI_API_KEY
LLM_BASE_URL=https://api.openai.com/v1
LLM_TIMEOUT=60

注意：模型名称可能会变化，最终以对应平台控制台和官方文档为准。如果报 model not found，优先检查 LLM_MODEL_ID。

7 编写 llm.py

7.1 代码目标

llm.py 只做一件事：把 messages 发给大模型，然后返回文本结果。
这里保留流式输出。因为流式输出体验更好，运行时能看到模型一个字一个字返回，不会一直卡着没反应。

7.2 完整代码

创建 llm.py：

import os
from typing import List, Dict, Optional
from dotenv import load_dotenv
from openai import OpenAI
load_dotenv()
class HelloAgentsLLM:
    """
    一个最小可用的 LLM 客户端。
    只支持 OpenAI 兼容接口。
    """
    def __init__(
        self,
        model: Optional[str] = None,
        api_key: Optional[str] = None,
        base_url: Optional[str] = None,
        timeout: Optional[int] = None,
    ):
        self.model = model or os.getenv("LLM_MODEL_ID")
        self.api_key = api_key or os.getenv("LLM_API_KEY")
        self.base_url = base_url or os.getenv("LLM_BASE_URL")
        self.timeout = timeout or int(os.getenv("LLM_TIMEOUT", "60"))
        if not self.model:
            raise ValueError("缺少模型名称，请在 .env 中配置 LLM_MODEL_ID")
        if not self.api_key:
            raise ValueError("缺少 API Key，请在 .env 中配置 LLM_API_KEY")
        if not self.base_url:
            raise ValueError("缺少服务地址，请在 .env 中配置 LLM_BASE_URL")
        self.client = OpenAI(
            api_key=self.api_key,
            base_url=self.base_url,
            timeout=self.timeout,
        )
    def think(self, messages: List[Dict[str, str]], temperature: float = 0) -> str:
        """
        调用大模型，并返回完整文本。
        messages 是对话列表，例如：
        [
            {"role": "system", "content": "你是一个有帮助的助手"},
            {"role": "user", "content": "你好"}
        ]
        """
        print(f"🧠 正在调用模型：{self.model}")
        try:
            response = self.client.chat.completions.create(
                model=self.model,
                messages=messages,
                temperature=temperature,
                stream=True,
            )
            print("✅ 模型返回：")
            result = []
            for chunk in response:
                if not chunk.choices:
                    continue
                content = chunk.choices[0].delta.content
                if not content:
                    continue
                print(content, end="", flush=True)
                result.append(content)
            print()
            return "".join(result)
        except Exception as e:
            print(f"❌ 调用大模型失败：{e}")
            return ""

7.3 这段代码怎么理解

这段代码里最重要的只有三部分。
第一，读取配置：

self.model = model or os.getenv("LLM_MODEL_ID")
self.api_key = api_key or os.getenv("LLM_API_KEY")
self.base_url = base_url or os.getenv("LLM_BASE_URL")

意思是：如果代码里传了参数，就用代码里的；如果没有传，就从 .env 里读取。
第二，创建客户端：

self.client = OpenAI(
    api_key=self.api_key,
    base_url=self.base_url,
    timeout=self.timeout,
)

意思是：告诉 OpenAI SDK，我要访问哪个模型服务。
第三，发送 messages：

response = self.client.chat.completions.create(
    model=self.model,
    messages=messages,
    temperature=temperature,
    stream=True,
)

意思是：把对话内容发给模型，并使用流式返回。

8 编写 main.py

8.1 代码目标

main.py 是入口文件，只负责演示怎么使用 HelloAgentsLLM。
它不要复杂，也不要封装太多逻辑。第一节课最重要的是让读者看清楚调用顺序。

8.2 完整代码

创建 main.py：

from llm import HelloAgentsLLM
def main():
    llm = HelloAgentsLLM()
    messages = [
        {
            "role": "system",
            "content": "你是一个讲解清楚、表达简单的 AI 助手。",
        },
        {
            "role": "user",
            "content": "用高中生能听懂的话解释什么是 LLM Agent。",
        },
    ]
    print("--- 调用 LLM ---")
    response_text = llm.think(messages)
    if response_text:
        print("\n--- 完整模型响应 ---")
        print(response_text)
if __name__ == "__main__":
    main()

8.3 调用顺序

这个文件的执行顺序很简单：

创建 HelloAgentsLLM
→ 准备 messages
→ 调用 llm.think(messages)
→ 打印模型返回内容

这就是后面所有 Agent 课程的基础。

9 运行验证

9.1 执行命令

在项目目录下执行：

python main.py

预期输出类似：

--- 调用 LLM ---
🧠 正在调用模型：deepseek-chat
✅ 模型返回：
LLM Agent 可以理解成一个由大语言模型驱动的智能助手，它不只是回答问题，还能根据目标规划步骤、调用工具，并根据结果继续完成任务。
--- 完整模型响应 ---
LLM Agent 可以理解成一个由大语言模型驱动的智能助手，它不只是回答问题，还能根据目标规划步骤、调用工具，并根据结果继续完成任务。

只要能看到模型返回内容，就说明本节课完成了。

9.2 修改问题再运行

你可以把 main.py 里的问题改成：

"写一个 Python 快速排序算法"

再执行：

python main.py

如果模型能返回代码，说明你的调用链路是正常的。

10 常见坑

10.1 .env 没有生效

如果提示：

缺少 API Key，请在 .env 中配置 LLM_API_KEY

先检查 .env 是否在当前目录。
正确目录应该是：

agent-course-01-llm-call/
├── .env
├── llm.py
├── main.py
└── requirements.txt

然后检查变量名是不是写错了。
必须是：

LLM_MODEL_ID=xxx
LLM_API_KEY=xxx
LLM_BASE_URL=xxx

不是：

MODEL_ID=xxx
API_KEY=xxx
BASE_URL=xxx

10.2 base_url 写成了完整接口地址

这是新手最常见的问题。
如果你使用 SDK，一般配置的是：

LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

不要写成：

LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions

因为 /chat/completions 这段路径 SDK 会自动拼接。

10.3 模型名称写错

如果报错里出现：

model not found

一般是模型名不对。
解决办法：

去模型平台控制台确认模型名
确认账号是否有这个模型权限
先使用官方示例里的模型名
不要照抄过期文章里的模型名

10.4 API Key 错误

如果报错里出现：

401
unauthorized
invalid api key

一般是 API Key 错了。
先检查：

API Key 有没有复制完整
API Key 前后有没有多余空格
当前平台和 API Key 是否匹配
DeepSeek 的 Key 不要拿去调用 Qwen
Qwen 的 Key 不要拿去调用 Kimi

10.5 temperature 设置

本节课默认：

temperature=0

可以简单理解成：让模型尽量稳定回答。
推荐：

场景	temperature
学习、测试、写代码	`0`
普通问答	`0.2` 到 `0.5`
创意写作	`0.7` 左右

刚开始学习 Agent，推荐先用 0。结果稳定，方便排查问题。

11 本节课最终代码

11.1 requirements.txt

openai
python-dotenv

11.2 .env

LLM_MODEL_ID=deepseek-chat
LLM_API_KEY=你的API_KEY
LLM_BASE_URL=https://api.deepseek.com
LLM_TIMEOUT=60

11.3 llm.py

import os
from typing import List, Dict, Optional
from dotenv import load_dotenv
from openai import OpenAI
load_dotenv()
class HelloAgentsLLM:
    def __init__(
        self,
        model: Optional[str] = None,
        api_key: Optional[str] = None,
        base_url: Optional[str] = None,
        timeout: Optional[int] = None,
    ):
        self.model = model or os.getenv("LLM_MODEL_ID")
        self.api_key = api_key or os.getenv("LLM_API_KEY")
        self.base_url = base_url or os.getenv("LLM_BASE_URL")
        self.timeout = timeout or int(os.getenv("LLM_TIMEOUT", "60"))
        if not self.model:
            raise ValueError("缺少模型名称，请在 .env 中配置 LLM_MODEL_ID")
        if not self.api_key:
            raise ValueError("缺少 API Key，请在 .env 中配置 LLM_API_KEY")
        if not self.base_url:
            raise ValueError("缺少服务地址，请在 .env 中配置 LLM_BASE_URL")
        self.client = OpenAI(
            api_key=self.api_key,
            base_url=self.base_url,
            timeout=self.timeout,
        )
    def think(self, messages: List[Dict[str, str]], temperature: float = 0) -> str:
        print(f"🧠 正在调用模型：{self.model}")
        try:
            response = self.client.chat.completions.create(
                model=self.model,
                messages=messages,
                temperature=temperature,
                stream=True,
            )
            print("✅ 模型返回：")
            result = []
            for chunk in response:
                if not chunk.choices:
                    continue
                content = chunk.choices[0].delta.content
                if not content:
                    continue
                print(content, end="", flush=True)
                result.append(content)
            print()
            return "".join(result)
        except Exception as e:
            print(f"❌ 调用大模型失败：{e}")
            return ""

11.4 main.py

from llm import HelloAgentsLLM
def main():
    llm = HelloAgentsLLM()
    messages = [
        {
            "role": "system",
            "content": "你是一个讲解清楚、表达简单的 AI 助手。",
        },
        {
            "role": "user",
            "content": "用高中生能听懂的话解释什么是 LLM Agent。",
        },
    ]
    print("--- 调用 LLM ---")
    response_text = llm.think(messages)
    if response_text:
        print("\n--- 完整模型响应 ---")
        print(response_text)
if __name__ == "__main__":
    main()

12 总结

12.1 本节课学到了什么

本节课只做了一个最小闭环：

.env 配置模型
→ llm.py 封装调用
→ main.py 发起请求
→ 控制台看到模型输出

这个闭环很小，但非常重要。后面所有 Agent 能力都会建立在它上面。

12.2 为什么这样写

本节课没有做复杂封装，原因是：

第一节课的目标是跑通，不是设计框架
.env 已经能满足基础配置需求
OpenAI 兼容接口能覆盖很多常见模型

llm.think(messages) 这个入口后面可以继续复用
后面进入 CoT 时，可以这样调用：

messages = [
{"role": "system", "content": "你是一个擅长一步一步推理的助手。"},
{"role": "user", "content": "请一步一步分析这个问题：..."}
]
llm.think(messages)

也就是说，本节课不是孤立代码，而是后续 Agent 课程的底座。

13 参考文献

13.1 官方文档

OpenAI API Reference：Chat Completions、Streaming、OpenAI Python SDK
DeepSeek API Docs：OpenAI-compatible API format
阿里云百炼 Model Studio 文档：OpenAI 兼容接口调用千问模型
Moonshot Kimi API 开放平台文档：OpenAI 兼容 API
智谱 AI 开放文档：OpenAI API 兼容接入说明
Anthropic Claude API Docs：Claude Python SDK、Messages API
Google AI for Developers：Gemini API、Google Gen AI SDK

13.2 后续课程

02 CoT：显式步骤推理
03 ReAct：推理和行动交替
04 Tool Use：让模型调用工具
05 Memory：让 Agent 记住上下文
06 Reflection：让 Agent 自我修正

文章出处：求索空间

文章链接： https://blog.askerlab.com/01_ji_chu_da_mo_xing_diao_yong

大模型 AI专栏

您可能对以下文章感兴趣

评论列表：

暂无评论

01 基础大模型调用

1 背景

1.1 本节课要做什么

2 当前有几种大模型调用方式

2.1 第一种：官方原生接口

2.2 第二种：OpenAI 兼容接口

2.3 第三种：统一网关

2.4 本节课的推荐做法

3 一次大模型调用需要哪些信息

3.1 最少需要三个配置

3.2 为什么配置放到 .env

4 项目结构

4.1 最终目录

5 安装依赖

5.1 创建 requirements.txt

5.2 安装依赖

5.3 验证安装

6 配置 .env

6.1 创建 .env 文件

6.2 不同平台的配置示例

7 编写 llm.py

7.1 代码目标

7.2 完整代码

7.3 这段代码怎么理解

8 编写 main.py

8.1 代码目标

8.2 完整代码

8.3 调用顺序

9 运行验证

9.1 执行命令

9.2 修改问题再运行

10 常见坑

10.1 .env 没有生效

10.2 base_url 写成了完整接口地址

10.3 模型名称写错

10.4 API Key 错误

10.5 temperature 设置

11 本节课最终代码

11.1 requirements.txt

11.2 .env

11.3 llm.py

11.4 main.py

12 总结

12.1 本节课学到了什么

12.2 为什么这样写

13 参考文献

13.1 官方文档

13.2 后续课程

wireguard 局域网VPN方案

01 基础大模型调用

提示词维度测试仪

提示词机理档案

提示词写作指南：那些我反复回看的优质示例

目录

系列文章

分类

标签

链接