## 1. 从零开始：注册百度智能云与开通千帆服务 如果你和我一样，对AI大模型充满好奇，想亲手试试让代码“开口说话”，那百度千帆大模型平台绝对是个不错的起点。它就像一个大型的“模型超市”，里面摆满了百度自家和第三方的好东西，比如我们熟知的文心一言系列模型。最关键的是，它提供了非常清晰的API和SDK，让我们开发者能像点外卖一样，轻松地把强大的AI能力“叫”到自己的应用里。整个过程，从注册到写出第一行调用代码，顺利的话半小时内就能搞定。我自己刚开始摸索的时候也走过一些弯路，这里就把最顺滑的一条路径分享给你。 首先，我们得有个“入场券”，也就是百度智能云的账号。直接访问百度智能云的官网，用你的百度账号登录。这里有个非常重要的步骤：**实名认证**。平台为了安全和管理，要求所有使用大模型服务的用户都必须完成实名认证。操作很简单，一般就是微信扫码然后刷个脸，几分钟就完事了。认证成功后，你把鼠标移到网页右上角你的用户名上，如果能看到“实名认证用户”的提示，那就说明这一步已经通过了。我当初在这里卡了一下，因为总想着先看看产品再认证，但其实这是硬性规定，早做早省心。 拿到“入场券”后，我们得去具体的“场馆”。回到百度智能云首页，你会看到一个很显眼的“立即体验”或者“千帆大模型”之类的入口，点击它就能进入千帆ModelBuilder的控制台。第一次进来，页面顶部很可能会有一个醒目的提示，告诉你“尚未开通模型服务”。别犹豫，点击旁边的“立即开通”按钮。系统会弹出一个确认对话框，直接点“确认开通”就行。这个过程是免费的，开通的是服务的权限，而不是立刻开始计费，所以不用担心。开通成功后，那个提示就会消失，你会看到一个功能清晰的管理面板。这里我建议你稍微花两分钟环顾一下这个控制台的布局，比如左边通常有菜单栏，里面会有“模型广场”、“体验中心”、“在线推理”等选项，后面我们都会用到。 ## 2. 先逛后买：探索模型广场与体验中心 开通了服务，先别急着写代码。就像去数码城买电脑，总得先看看样机、试试手感吧？千帆的“模型广场”和“体验中心”就是让我们“逛”和“试”的地方。这对于我们后续选择用哪个模型来开发，至关重要。 **模型广场**，你可以把它理解为所有可用模型的“总目录”。在这里，百度把所有上架的模型都罗列了出来，数量不少，得有几十个。除了百度自家的文心一言（ERNIE）系列，比如ERNIE-3.5-8K、ERNIE-4.0-8K等，你还能看到一些其他的模型。每个模型卡片上通常会标注模型的基本信息，比如所属公司、主要能力（是擅长对话、还是擅长文本生成、代码生成等）、以及上下文长度。上下文长度是个关键参数，你可以简单理解为模型的“短期记忆容量”，比如8K大概相当于6000多个汉字，这个数字决定了你一次性能和它聊多长的天，或者让它处理多长的文档。第一次看可能会有点眼花缭乱，我的建议是，对于刚入门，直接认准“ERNIE-3.5-8K”这个模型，它在通用性、性能和成本上是一个很好的平衡点，官方文档和示例也最多。 光看参数不够，还得上手试试。“体验中心”就是干这个的。在这里，你可以选择一个模型，然后直接在网页对话框里跟它聊天。你可以问它问题，让它写首诗，或者尝试让它总结一段你粘贴进去的文字。这个试用的过程有双重目的：第一，直观感受模型的对话能力和风格，看看它是不是符合你的预期；第二，也是更实际的一点，**这里是免费的**。没错，在体验中心里的对话交互，目前是不收费的，你可以尽情测试不同模型的效果。我经常在这里测试一些刁钻的问题，看看不同模型的反应差异，这比光看说明书有用多了。不过要注意，这种免费体验通常有频率限制，防止被滥用，但对于个人测试来说完全够用。 ## 3. 理解消费：在线推理与费用须知 “试吃”之后，就要考虑“正餐”怎么买了。当我们通过自己的程序调用API时，就会产生实际的计算资源消耗，也就是费用。所有关于模型调用计费的管理和查看，都在“在线推理”这个页面。这里是你需要特别留心的地方，因为涉及到真金白银。 点进在线推理页面，你会看到一个模型服务列表，里面列出了你已经开通了调用权限的模型。每个模型后面都会明确标注它的计费状态，最常见的是“按量后付费”。这是什么意思呢？就是说，你没有预付费的套餐，而是先用，月底或者根据账单周期，百度会根据你的实际使用量（通常是按输入和输出文本的token数量计算）来扣费。这种模式非常灵活，用多少算多少，特别适合前期探索和小流量应用。 但灵活也意味着需要自己做好管控。**这里有个非常重要的提醒：千万不要在代码里把AK/SK（访问密钥）写死然后上传到公开的代码仓库（比如GitHub）**。万一密钥泄露，别人就可以用你的账号疯狂调用API，产生巨额账单。我就听说过有开发者因为疏忽吃了亏。所以，务必使用环境变量来管理密钥（后面会讲），并且定期在控制台查看“费用中心”的消费情况。对于个人学习和小项目，你可以先设置一个很低的预算提醒，比如每月10元，这样一旦用量异常，能及时收到通知。大部分模型的单价其实并不高，尤其是像ERNIE-3.5这样的模型，调用一次常规对话的成本可能只有几分甚至几厘钱，但安全意识必须从一开始就建立起来。 ## 4. 磨刀不误砍柴工：开发环境与SDK安装 好了，场地逛了，规则也清楚了，现在该回到我们开发者的主场——本地电脑了。要让Python程序能和千帆平台对话，我们需要安装官方的SDK工具包。这个过程就像给你的Python安装一个专用的“翻译器”和“快递员”，它负责把我们的请求打包成标准格式，发送给千帆的服务器，再把服务器的回复解析成我们方便处理的格式。 首先，确保你的Python环境是3.7或以上版本。打开你的命令行终端（Windows上是CMD或PowerShell，Mac/Linux上是Terminal），输入 `python --version` 或者 `python3 --version` 查看。如果版本符合，就可以进行安装了。安装命令非常简单，就一行： ```bash pip install qianfan ``` 如果你在国内，为了提高下载速度，可以考虑使用国内的镜像源，比如清华源： ```bash pip install qianfan -i https://pypi.tuna.tsinghua.edu.cn/simple ``` 执行这个命令后，pip包管理器会自动去下载`qianfan`这个包以及它依赖的所有其他包（比如处理网络请求的`aiohttp`、处理配置的`pydantic`等）。你会看到命令行里刷刷地滚过很多下载和安装信息。这个过程可能会持续一两分钟，取决于你的网速。我第一次安装的时候，被它安装的一大串依赖包吓了一跳，心想怎么这么复杂。其实不用担心，这正是SDK功能完善的表现，它把可能需要用到的功能都提前打包好了，我们直接用就行。 安装完成后，可以在Python交互环境里验证一下。打开Python，输入 `import qianfan`，如果不报错，就说明安装成功了。这里有个小坑我遇到过：如果你的电脑上有多个Python环境（比如同时装了Anaconda和系统Python），要确保你安装SDK时用的pip和后续运行代码时用的python是同一个环境下的。不然就会出现“明明装好了，运行时却说找不到模块”的经典问题。一个检查的好办法是，在命令行里分别用 `which pip` 和 `which python`（Linux/Mac）或 `where pip` 和 `where python`（Windows）看看它们的路径是否属于同一个父目录。 ## 5. 获取钥匙：找到你的Access Key与Secret Key SDK装好了，但我们还不能直接调用。因为千帆服务器需要知道是谁在调用，并且要确认这个调用是经过授权的。这就好比你去银行取钱，光有账户名不行，还得有密码。在API调用的世界里，这个“密码”就是一对密钥：Access Key (AK) 和 Secret Key (SK)。AK有点像你的用户名，是公开的；SK则是绝密的密码，千万不能泄露。 获取这对密钥的路径是：登录百度智能云控制台，在右上角头像菜单里找到“安全认证”，或者直接搜索“访问密钥”。进入“访问密钥”管理页面后，你就能看到你的AK了。SK默认是隐藏的，点击“显示”按钮，系统通常会要求进行一次额外的安全验证，比如输入手机验证码。验证通过后，你才能看到完整的SK。 **请立刻、马上、务必把这对AK/SK妥善保存好，并且像对待银行卡密码一样对待SK。** 我个人的习惯是： 1. **绝不写入代码**：不要像下面这样直接把密钥写在`.py`文件里。 ```python # 危险！不要这样做！ os.environ["QIANFAN_ACCESS_KEY"] = "your_iam_ak_here" os.environ["QIANFAN_SECRET_KEY"] = "your_iam_sk_here” ``` 2. **使用环境变量（推荐）**：在运行程序之前，在终端里设置环境变量。 - Windows (PowerShell): `$env:QIANFAN_ACCESS_KEY="your_ak"; $env:QIANFAN_SECRET_KEY="your_sk"` - Windows (CMD): `set QIANFAN_ACCESS_KEY=your_ak && set QIANFAN_SECRET_KEY=your_sk` - Linux/Mac: `export QIANFAN_ACCESS_KEY="your_ak" && export QIANFAN_SECRET_KEY="your_sk"` 3. **使用`.env`文件（项目级管理）**：在项目根目录创建一个名为`.env`的文件，里面写上： ``` QIANFAN_ACCESS_KEY=your_iam_ak_here QIANFAN_SECRET_KEY=your_iam_sk_here ``` 然后在Python代码开头使用`python-dotenv`库来加载。记得把`.env`文件加入你的`.gitignore`，确保它不会被提交到公开仓库。 第一种方法每次开新终端都要重设，麻烦；第二种方法是主流做法，安全又方便。控制台上也提供了密钥的禁用和重新生成功能。如果你怀疑SK可能泄露了，别犹豫，立刻去禁用旧的，生成一对新的。 ## 6. 第一行对话：用Python SDK发起调用 钥匙在手，天下我有。现在我们来写一个最简单的Python脚本，完成和千帆大模型的第一次正式“对话”。我们选用之前提到的`ERNIE-3.5-8K`模型。创建一个新的Python文件，比如叫做 `first_chat.py`。 假设我们采用上面提到的第二种方法，通过环境变量传递了AK/SK，那么代码可以如此简洁： ```python import os import qianfan # 注意：AK/SK应已通过环境变量 QIANFAN_ACCESS_KEY 和 QIANFAN_SECRET_KEY 设置 # 代码中无需再显式写入！ # 创建ChatCompletion对象 chat_comp = qianfan.ChatCompletion() # 发起一次对话请求 resp = chat_comp.do( model="ERNIE-3.5-8K", # 指定使用的模型 messages=[ { "role": "user", # 角色是用户 "content": "请用Python写一个函数，计算斐波那契数列的第n项。" # 用户的消息内容 } ] ) # 打印响应的完整内容（一个字典） print("完整响应：", resp) # 更优雅地，提取出AI回复的文本内容 if 'result' in resp['body']: ai_reply = resp['body']['result'] print("\nAI的回复：") print(ai_reply) ``` 我们来拆解一下这段代码。首先导入必要的模块。`qianfan.ChatCompletion()` 是SDK提供给我们的一个核心类，专门用于处理对话补全任务。`chat_comp.do()` 是发起请求的方法。里面有两个关键参数： - `model`: 字符串，指定你要调用哪个模型。必须和模型广场里列出的名称完全一致。 - `messages`: 一个列表，里面按顺序存放了对话的历史记录。每个记录都是一个字典，包含 `role`（角色，通常是 `"user"` 或 `"assistant"`）和 `content`（内容）。即使我们是第一次问问题，也需要以这种格式告诉模型：这是一条来自用户的消息。 运行这段代码，如果一切配置正确，几秒钟后你就会在终端看到返回结果。返回的 `resp` 是一个结构化的对象，`resp['body']` 里包含了服务器返回的核心数据。其中 `result` 字段就是AI生成的回复文本。你可能会看到除了回复，还有 `id`（本次对话的唯一标识）、`usage`（本次调用消耗的token数量，关系到费用）等信息。看到那个 `usage` 字段了吗？这就是你这次调用花了多少钱的依据，多留意它，能帮你更好地优化提示词，控制成本。 ## 7. 深入一步：处理多轮对话与调节参数 第一次调用成功，成就感满满。但真实的对话往往不是一问一答就结束的，我们需要让模型记住之前的聊天内容，进行多轮对话。这就要用到 `messages` 列表的威力了。这个列表本质上就是提供给模型的“上下文窗口”，模型会根据这个窗口里的所有内容来生成下一个回复。 我们来看一个多轮对话的例子： ```python import qianfan chat_comp = qianfan.ChatCompletion() # 模拟一个多轮对话的上下文 conversation_history = [ {"role": "user", "content": "你觉得学习编程最难的是什么？"}, {"role": "assistant", "content": "学习编程初期，最难的可能是一种思维方式的转变，要从“描述问题”转向“精确地、分步骤地解决问题”。另外，面对错误信息时的调试能力也需要时间积累。"}, {"role": "user", "content": "那对于调试，你有什么给新手的建议吗？"} # 这个问题是基于上面历史的 ] resp = chat_comp.do( model="ERNIE-3.5-8K", messages=conversation_history # 把整个历史对话传进去 ) print(resp['body']['result']) ``` 在这个例子里，模型在回答第二个问题时，是能看到第一个问题和它自己第一次的回答的，所以它的回复会更有连贯性。**这里就体现出上下文长度（比如8K）的重要性了**。如果你不停地往 `messages` 列表里追加内容，总token数超过了模型的上下文窗口，最旧的消息就会被“挤出去”，模型就会“忘记”很早之前的对话。所以对于长文档处理或超长对话，你需要设计一些策略，比如只保留最近N轮对话，或者对历史进行摘要。 除了对话内容，`do()` 方法还有很多参数可以调节模型的行为，让生成的结果更符合你的需求。常用的有： - `temperature`（温度）：取值范围通常在0到1之间。这个值越低（如0.1），模型的输出就越确定、越保守，重复问同一个问题，答案可能几乎一样。这个值越高（如0.9），输出就越随机、越有创造性。写代码、做事实问答时调低点（比如0.2）；写诗歌、想创意时调高点（比如0.8）。 - `top_p`（核采样）：另一种控制随机性的方式，和temperature选一个用就行，通常效果类似。 - `max_output_tokens`（最大输出token数）：限制模型一次最多生成多长的回复，防止它“滔滔不绝”产生过高费用。 你可以这样使用它们： ```python resp = chat_comp.do( model="ERNIE-3.5-8K", messages=[...], temperature=0.3, max_output_tokens=500 ) ``` 多试试不同的参数组合，观察输出变化，是快速掌握模型“脾气”的好方法。 ## 8. 避坑指南：常见问题与实战技巧 走完整个流程，你可能已经成功调用了模型。但在实际开发中，总会遇到一些“小石头”。这里我分享几个自己踩过的坑和总结的技巧，希望能帮你更顺畅。 **网络问题与超时**：SDK默认会有请求超时设置。如果你的网络环境不太稳定，或者请求的回复特别长（比如生成一篇长文），可能会遇到超时错误。你可以在初始化 `ChatCompletion` 对象时配置超时时间： ```python from qianfan import QfResponse chat_comp = qianfan.ChatCompletion(timeout=60.0) # 设置60秒超时 ``` 如果遇到SSL证书问题（在某些内部网络环境下），可以尝试通过环境变量 `QIANFAN_SSL_VERIFICATION` 设置为 `False` 来跳过验证（仅限测试环境，生产环境不推荐）。 **费用监控与优化**：前面提过，`usage` 字段是你的好朋友。定期打印或记录它。你会发现，同样意思的提示词，表达更简洁、更清晰，消耗的token就更少。比如，把“请你帮我写一个关于春天的诗歌，要优美一点，字数大概在100字左右”优化成“写一首100字左右的咏春七言诗”，效果可能差不多，但后者更省。对于高频调用，可以考虑使用SDK内置的异步接口（`ado`）或者批量处理能力来提升效率。 **错误处理**：你的代码不能假设每次调用都100%成功。网络抖动、模型临时过载、额度不足等都可能导致调用失败。好的做法是用 `try-except` 把调用包起来： ```python try: resp = chat_comp.do(...) # 处理成功响应 except Exception as e: print(f"调用API时发生错误：{e}") # 这里可以根据错误类型进行重试、降级处理或记录日志 ``` **模型选择**：不要只盯着一个模型。在模型广场里，有些模型可能专门优化了代码能力（比如Code系列），有些在长文本理解上更强。根据你的具体任务，去体验中心多试试几个，找到最适合的那个。官方文档和GitHub上的示例仓库是学习更多高级用法（如函数调用、知识库增强）的最佳去处。 最后，保持耐心和好奇心。大模型开发不像调用一个简单的数学函数，它充满了不确定性。同样的提示词，今天和明天的回复可能就有细微差别。关键是通过不断的测试、调整参数、优化你的提示词（这就是现在很火的“提示工程”），来让模型稳定地输出你想要的结果。当你看到自己写的几行代码，真的引来了一个“数字大脑”的回应时，那种感觉，还是挺奇妙的。