尧图建网站 尧图建网站 YAOTU WEB BUILD 免费咨询
ARTICLE DETAIL

资讯详情

深耕网站建设与建站编程的一线实战洞察。

AI 大模型agent开发入门(一)- 理解API接口

AI 大模型agent开发入门(一)- 理解API接口 本文是agent开发系列的第一篇适合刚开始接触大模型开发的同学阅读既然是agent开发那就离不开大模型调用学习大模型调用我认为第一课理解API。其他相关文章AI 大模型 Agent 开发入门二从让AI从“会回答”到“会做事”-CSDN博客很多人第一次学习大模型API通常是从复制一段代码开始的from openai import OpenAI client OpenAI( api_keyyour-api-key ) response client.chat.completions.create( modelyour-model, messages[ { role: user, content: 请介绍一下你自己 } ] ) print(response.choices[0].message.content)代码运行后终端成功打印出模型回答于是我们似乎已经“学会了调用大模型”。但要真正理解大模型 API不需要先背大量参数。更好的方式是沿着一条请求从程序出发观察它如何到达模型服务器又如何把答案返回给用户。一次最基础的大模型调用可以概括为理解这条链路后后续学习参数控制、结构化输出、工具调用和 Agent都会容易很多。一、程序是怎样找到并访问模型的调用模型之前程序必须先解决两个问题我是谁我要访问哪个服务器这会用到两个概念API Key和Base URLclient OpenAI( api_keyos.getenv(MODEL_API_KEY), base_urlhttps://example.com/v1 )API Key 用来证明调用者身份Base URL 用来确定请求发送到哪里。1、API Key程序访问模型服务的身份凭证大模型 API 通常不是匿名服务。模型平台收到请求后需要判断请求属于哪个账号账号能否使用当前模型是否还有可用余额是否超过调用频率限制本次请求应该记录到谁的账单中。API Key 就是程序调用模型服务时使用的身份凭证。from openai import OpenAI client OpenAI( api_keyyour-api-key )从功能上看它有些类似账号密码。但与普通密码不同API Key 主要供程序使用这意味着一旦 API Key 泄露其他人就可能冒用你的身份调用模型消耗额度甚至产生费用。因此不建议把真实 API Key 直接写进代码# 不推荐 client OpenAI( api_keysk-xxxxxxxxxxxxxxxx ) #更常见的做法是通过环境变量读取 import os from openai import OpenAI client OpenAI( api_keyos.getenv(MODEL_API_KEY) )#Windows PowerShell 可以这样设置 $env:MODEL_API_KEYyour-api-key #Linux 或 macOS 可以这样设置 export MODEL_API_KEYyour-api-key这样做有三个明显好处避免密钥随着代码上传到 GitHub开发、测试和生产环境可以使用不同的 Key更换密钥时不需要修改业务代码。.env文件虽然比直接写进代码更方便但它仍然包含真实密钥在项目上传git时也要加入.gitignore.env2、Base URL告诉程序模型服务器在哪里API Key 解决了“我是谁”Base URL 则解决了“请求发到哪里”。client OpenAI( api_keyos.getenv(MODEL_API_KEY), base_urlhttps://example.com/v1 )Base URL 可以理解为一组 API 接口共同使用的根地址。SDK 会在它后面拼接具体接口路径。例如聊天接口最终可能请求https://example.com/v1/chat/completions很多模型平台都提供所谓的“OpenAI 兼容接口”。它的意思通常不是这些平台使用了 OpenAI 的模型而是它们采用了相似的请求格式。开发者可以继续使用 OpenAI SDK只修改以下内容API KeyBase URL模型名称。from openai import OpenAI client OpenAI( api_keyos.getenv(MODEL_API_KEY), base_url模型平台提供的地址 ) response client.chat.completions.create( model模型名称, messages[ { role: user, content: 你好 } ] )这也是为什么同一套代码稍作修改就可能接入 Kimi、DeepSeek、Qwen、OpenRouter 或其他兼容平台。不过“OpenAI 兼容”并不等于所有能力完全一致。不同平台可能在以下方面存在差异支持的模型参数不同流式返回格式不同是否支持图片输入是否支持工具调用是否支持结构化输出错误码和限流规则不同。因此兼容接口可以降低接入成本但正式开发时仍要查看对应平台的官方文档。3、Messages模型本次能够看到的对话找到服务器并完成身份认证后程序需要把问题发送给模型。现代聊天模型通常不是只接收一个字符串而是接收一组消息messages [ { role: system, content: 你是一名耐心的 Python 教师。 }, { role: user, content: 请解释什么是装饰器。 } ]这里的role表示消息由谁发出。最常见的角色包括system定义模型的身份、总体规则和回答方式user用户当前提出的问题assistant模型之前返回的回答。例如一个连续对话可能是messages [ { role: system, content: 你是一名 Python 教师回答时尽量使用简单示例。 }, { role: user, content: 什么是列表推导式 }, { role: assistant, content: 列表推导式是一种简洁创建列表的语法。 }, { role: user, content: 再给我一个带条件判断的例子。 } ]这里有一个非常重要的事实大多数聊天 API 本身并不会自动记住你上一轮说了什么。第二次调用时之所以模型能理解“再给我一个例子”指的是什么是因为程序把前面的消息重新发送给了模型。也就是说模型的“聊天记忆”通常不是模型平台自动保存的而是由调用方维护messages列表实现的。你的程序需要负责保存历史消息将必要历史重新发送删除无关历史在消息过长时进行摘要或截断。这一点会直接引出下一个核心概念Token。二、模型看到的不是文字而是 Token1、什么是token当请求到达模型服务器后模型不会直接按照汉字数或单词数处理文本。在真正进入模型之前文本会先经过 Tokenizer也就是分词器被切分成一系列 Token。Token 是模型处理文本时使用的基本单位。例如请帮我写一个 Python 函数这句话并不一定按照每个汉字、每个英文单词分别计算。因此下面两种说法都不准确1 个汉字一定等于 1 个 Token1 个英文单词一定等于 1 个 TokenToken 之所以重要是因为它同时决定三件事请求费用请求能够容纳的内容长度模型处理请求所需的时间。2、输入 Token 不只是当前问题一次请求中的输入 Token通常包括System 提示词 历史对话 当前用户问题 工具调用结果 检索到的文档 其他附加上下文假设用户当前只问了一句话请继续。这句话本身可能很短。但如果程序同时发送了前面几十轮聊天那么平台计算的不是“请继续”这三个字而是整份messages中的全部内容。例如系统提示词1,000 Token 历史对话18,000 Token 当前问题20 Token这次请求的输入量大约是 19,020 Token而不是 20 Token。这也是为什么聊天时间越长后续调用往往越贵、越慢。3、上下文窗口是一张有限大小的工作台每个模型都有自己的上下文窗口例如32K 128K 256K 1M这里的 K 通常表示约一千个 Token。很多初学者会把上下文窗口理解为用户一次最多可以输入多少内容。但更准确的理解是模型在一次请求中能够同时处理的全部 Token 数量。其中不仅包括用户输入也通常需要包括模型即将生成的内容。可以把上下文窗口理解为一张固定大小的工作台。工作台上可能放着系统提示词历史对话当前问题检索资料工具执行结果模型需要填写的答案。前面的资料放得越多留给模型生成答案的空间就越少。假设某个模型的上下文窗口是 128K Token当前请求中已经包含系统提示词5K历史对话80K当前输入20K工具结果10K输入部分已经占用了 115K Token。理论上剩余空间大约为 13K Token。如果程序仍要求模型生成 20K Token就可能超过上下文限制。因此上下文窗口并不等于单纯的“最大输入长度”。它更接近输入 Token 输出 Token ≤ 上下文窗口具体计算规则会因模型和接口而异但这种理解适用于绝大多数开发场景。4、为什么上下文不是越长越好上下文窗口越大意味着模型能够一次读取更多资料但不代表应该把所有信息都塞进去。过多上下文可能带来几个问题请求费用增加响应速度变慢无关信息干扰模型判断重要指令被淹没更容易触发长度限制。实际开发中通常需要主动管理上下文。常见做法包括只保留最近几轮对话将较早内容压缩成摘要删除和当前问题无关的消息通过检索只取回相关文档避免重复发送完全相同的大段提示词对超长文本进行分块处理。例如一个聊天程序不一定要永久保留全部对话MAX_HISTORY 10 recent_messages messages[-MAX_HISTORY:]更复杂的做法是在对话变长后将旧消息总结为一段较短的摘要此前对话摘要 用户正在开发一个 Unity 项目已经完成对象池基础实现 当前希望增加异步资源加载和异常处理。相比发送几十轮完整消息摘要可以显著降低 Token 消耗。不过摘要也会丢失细节因此不能机械地压缩所有内容。哪些信息必须保留取决于具体业务。三、模型生成的答案如何回到程序1、流式输出模型开始生成内容后服务器还需要决定如何把结果返回给调用方。最简单的方式是等模型生成完整答案后再一次性返回。response client.chat.completions.create( modelyour-model, messages[ { role: user, content: 请介绍 Python 的主要特点 } ] ) print(response.choices[0].message.content)这种模式的流程是发送请求→ 等待模型完成全部生成→ 返回完整答案→ 程序开始显示如果答案很短等待感并不明显。但当模型需要生成长文章或大量代码时用户可能等待十几秒却看不到任何内容容易误以为程序卡住了。ChatGPT、Claude、Kimi 等产品能够逐步显示答案是因为它们通常采用了 Streaming也就是流式输出。开启流式输出后服务器不会等待完整答案生成完毕而是将已经生成的内容片段持续发送给程序模型生成一部分→ 立即返回一部分→ 模型继续生成→ 继续返回Python 示例通常类似这样stream client.chat.completions.create( modelyour-model, messages[ { role: user, content: 请介绍 Python 的主要特点 } ], streamTrue ) for chunk in stream: content chunk.choices[0].delta.content if content: print(content, end, flushTrue)其中streamTrue表示启用流式返回。程序收到的每个chunk都只是完整答案的一部分因此需要不断读取并拼接。输出过程可能类似Python Python 是 Python 是一种 Python 是一种高级编程语言……需要注意Streaming 的核心价值通常不是大幅缩短模型生成完整答案的总时间而是缩短用户第一次看到内容的时间。假设模型完整生成答案需要 15 秒非流式模式用户可能等 15 秒后才看到全部内容流式模式用户可能在第 1 秒就看到第一段文字。因此流式输出特别适合AI 聊天页面AI 写作工具代码生成工具长文本生成需要支持“停止生成”的场景。2、Streaming 也会增加开发复杂度流式输出看起来只是增加了一个streamTrue但在真实项目中还需要处理很多问题多个文本片段如何拼接网络中断后如何处理用户点击停止时如何终止请求已生成内容是否需要实时保存工具调用参数如何从多个片段中组合前端如何避免频繁刷新造成卡顿流式过程中出现错误如何提示用户。尤其是结构化输出场景。假设模型需要返回 JSON{ title: 大模型 API 入门, score: 90 }在流式过程中你可能先收到{ title: 大模型此时它还不是合法 JSON程序不能直接解析。因此下面这些业务通常更适合等待完整结果严格 JSON 输出数据抽取后台批处理自动化任务需要完整校验后才能继续执行的流程。Streaming 不是必须开启的高级功能而是一种结果交付方式。判断是否使用它可以问自己一个问题用户是否需要在模型生成完成之前就看到中间内容需要就使用流式输出不需要则一次性返回往往更加简单可靠。四、把一次 API 请求重新串起来现在回头看最开始的代码from openai import OpenAI client OpenAI( api_keyyour-api-key ) response client.chat.completions.create( modelyour-model, messages[ { role: user, content: 请介绍一下你自己 } ] ) print(response.choices[0].message.content)整个API可以概括为后续学习的很多能力都建立在这条请求链路上temperature控制生成结果的随机程度输出长度参数限制模型生成规模Structured Output 约束模型返回固定格式Function Calling 允许模型请求外部工具Rate Limit 限制单位时间内的请求和 Token 数Retry 处理限流、超时和服务异常RAG 将检索资料加入模型上下文Agent 在模型、工具和状态之间组织多轮执行。这些知识并不是相互独立的功能清单而是不断扩展同一条调用链路。结语学习大模型 API 最容易陷入的误区是一开始就背模型名称、接口参数和 SDK 写法。这些内容变化很快。模型会更新接口会升级不同厂商的参数也不完全一致。但一次请求背后的核心逻辑相对稳定程序需要凭证才能访问服务请求需要发送到正确的接口地址模型根据本次提供的消息理解上下文文本会被转换为 TokenToken 影响费用、速度和上下文容量生成结果可以一次性返回也可以流式返回。只要理解了这条链路即使以后更换模型平台、SDK 或编程语言也只是代码形式发生变化底层思路并没有改变。下面这篇文章可以让模型不仅仅是回答问题还可以让他调用工具AI 大模型 Agent 开发入门二从让AI从“会回答”到“会做事”-CSDN博客
返回列表