第一次接触Gemini的时候，我其实有点懵。打开Google的页面，满屏都是“多模态”“大模型”“API”这些词，感觉像是站在一扇巨大的门前，不知道该推哪一扇。后来我花了大概两周时间，从最基础的对话玩起，慢慢摸到了API调用的门槛，才意识到Gemini其实没有想象中那么遥远。它更像是一个可以陪你聊天、帮你干活、还能被你塞进自己程序里的多面手。这篇文章就是把我踩过的坑和梳理出来的路径，一次性摊开给你看。
什么是Gemini：模型家族、能力边界与适用场景
Gemini不是某一个单独的模型，它更像是一个家族。我刚开始以为只有一个版本，后来才发现里面有Nano、Flash、Pro、Ultra这些不同规格的成员。Nano跑在手机上，Flash追求速度和成本，Pro平衡能力和效率，Ultra则是目前最顶的那一档。选哪个完全取决于你要干什么。如果只是日常问答和写写邮件，Flash就够用。要是想处理复杂的推理任务或者长文档分析，Pro或者Ultra会更合适。
能力边界这块，我自己的体会是：Gemini在文本理解、多模态输入、代码生成这些方面确实强。它可以同时看图片、读PDF、听音频，甚至处理视频内容。但也不是万能的。比如涉及实时性极强的数据，它可能会给出过时的信息。涉及专业领域的深度判断，它偶尔也会一本正经地胡说八道。我一般会把它当成一个知识面很广但需要核验的助手，而不是绝对权威。
适用场景其实很宽。学生可以用它整理笔记、翻译文献。上班族可以用它写周报、做会议纪要。开发者可以用API把它接进自己的应用里，做智能客服、内容审核、数据分析。我自己最常用的场景是：把一堆杂乱的会议记录丢给它，让它提炼出待办事项和关键决策。省下来的时间，够我多喝两杯咖啡。
Gemini教程学习路线：新手使用与API开发双路径
学Gemini这件事，我建议先分清自己是想“用”还是想“建”。这两条路线的起点和终点都不一样。新手使用路线更偏向于直接和模型对话，学会怎么提问、怎么上传文件、怎么管理上下文。你不需要写代码，只需要理解界面上的按钮是干嘛的，以及什么样的指令能得到更好的回答。这条路走顺了，日常效率提升会非常明显。
API开发路线则是另一番景象。你需要面对API Key、请求结构、SDK选择、参数调优这些东西。我第一次调API的时候，光是搞明白认证方式就花了半小时。但一旦跑通第一个请求，后面的事情就会顺很多。你可以把Gemini的能力嵌入到自己的网站、机器人、工作流里，让它按照你的规则去处理任务。这条路更适合有一定编程基础、想做出产品或者自动化工具的人。
两条路线并不是完全割裂的。很多新手用着用着，就会冒出“能不能让它自动帮我做某件事”的念头，这时候就可以慢慢往API方向靠。反过来，开发者在调试API的时候，也需要回到对话界面去测试提示词的效果。我自己就是先用了两个月网页版，然后才开始写代码调用。先熟悉它的脾气，再把它请进自己的系统里，这个顺序比较舒服。
相关搜索词解析：Gemini新手入门使用教程、Gemini API接口调用教程
“Gemini新手入门使用教程”这个搜索词背后，藏着大量刚接触AI工具的人。他们可能连Google账号都没有，或者不知道怎么访问。这类搜索的意图很直接：告诉我第一步该点哪里。我当初也是这样，搜出来的教程要么太旧，要么跳步太多。所以我在后面的章节里会尽量把每一步都写清楚，包括怎么注册、怎么选模型、怎么新建对话、怎么导出结果。
“Gemini API接口调用教程”则面向另一群人。他们通常已经用过网页版，觉得手动操作太慢，想用代码批量处理或者集成到自己的项目里。这个搜索词下面，大家关心的是API Key怎么拿、Python SDK怎么装、第一个请求怎么写、流式输出怎么实现、错误码怎么处理。我自己在搜这类内容时，最烦的就是示例代码跑不通。所以后面我会尽量用当前可用的版本和写法。
这两个搜索词其实代表了一个连续的学习过程。先用起来，再调起来。我写这个教程的时候，脑子里一直放着这两种读者。你如果是纯新手，可以先看第2章和第3章。你如果已经会用了，想直接调API，可以跳到第4章和第5章。没有严格的前后依赖，但按顺序看会更顺。
学习前准备：账号、网络环境、工具与基础知识
账号这块，你需要一个Google账号。普通的Gmail就行，不需要什么企业认证。我建议专门注册一个用于AI工具的账号，和你的私人邮箱分开。这样万一遇到账号安全提示或者地区限制，不会影响你日常收邮件。注册流程很简单，跟着页面填就行。年龄设置那里注意一下，有些功能对未成年账号有限制。
网络环境是很多人卡住的地方。Gemini的服务在部分地区不可用，你需要确保自己的网络能正常访问。我自己的经验是，尽量用稳定的连接，不要在公共WiFi下频繁切换节点。有时候页面加载不出来，不一定是账号问题，可能是网络抖动。另外，手机端和电脑端的访问体验不太一样，移动端App在某些地区可能需要额外的设置。
工具方面，网页版什么都不用装，打开浏览器就能用。API开发的话，你需要一个代码编辑器，VS Code就很好。Python环境建议用3.9以上，Node.js用18以上。如果你还没装过这些，可以先花半小时搞定。基础知识这块，新手路线不需要编程，但要知道怎么打字提问。API路线需要你会一点Python或者JavaScript，知道什么是HTTP请求，什么是JSON。不会也没关系，我在后面的示例里会把每一步都写出来。
我教过三个朋友上手Gemini，他们问得最多的问题是“网址是什么”。我回忆自己第一次打开Gemini网页，盯着那个空白的输入框，手指悬在键盘上不知道敲什么。那会儿我连怎么注册都折腾了一会儿。这一章就把我踩过的界面坑、对话技巧和基础功能，按我自己的使用习惯摊开讲。你跟着走一遍，大概半小时就能摸清门道。
2.1 注册与访问：Web端、移动端及账号要求
我最早用的是Web端。浏览器输入gemini.google.com，页面会跳转到Google账号登录。没有Google账号的话，点“创建账号”走一遍流程，填姓名、生日、用户名、密码。我专门注册了一个新Gmail，用来隔离AI工具和私人邮件。年龄那里我填了真实年份，有些功能对未成年账号会锁。登录成功后，你会看到一个简洁的聊天界面，左边是历史对话列表，中间是输入框。整个过程不到五分钟，比我想象中简单。
移动端我是后来才装的。在App Store或者Google Play搜“Gemini”，图标是四角星那个。下载完打开，用同一个Google账号登录。手机端有个好处，可以直接调用相机拍照片，也可以按住麦克风说话。我在外面开会时，常用它录音转文字，再让Gemini提炼要点。移动端的界面更紧凑，底部是输入框，上面是对话流。按钮布局和网页版不太一样，但核心功能都在。
账号要求这块，普通Google账号就够用，不需要付费订阅。我试过用企业Workspace账号登录，也能进，但有些管理员会限制第三方AI服务。如果你在公司网络下打不开，可能是网络策略拦了。我自己的做法是：一个私人Gmail专门用于Gemini，开启两步验证。地区限制后面2.5节会细说，这里先记住：账号本身不挑，挑的是你所在的网络环境。
2.2 核心界面与功能：对话、上传文件、多模态输入与联网扩展
Gemini的对话界面，我把它分成三块。左边是历史会话，点一下就能回到之前的聊天。中间是主输入框，下面有一排小图标。右边偶尔会弹出一些建议卡片。我刚开始只会在输入框里打字，后来才发现图标里藏着不少好东西。那个加号按钮可以上传文件，支持图片、PDF、TXT、代码文件。我常把会议纪要的PDF拖进去，让它总结待办事项。上传后，Gemini会先读一遍文件，再回答我的问题。文件大小有限制，太大的话得分批传。
多模态输入是我最喜欢的功能。手机端可以直接拍照，比如拍一页书，问它“这段讲了什么”。网页端可以粘贴图片，或者把图片拖进输入框。我试过传一张折线图，让它分析趋势，它能把关键拐点说出来。视频和音频也能处理，不过网页端上传视频的入口比较隐蔽，我一般用手机拍完直接传。多模态的意思就是：你给它文字、图片、声音，它都能理解。我拿它认过植物，也拿它翻译过路牌。
联网扩展藏在输入框下面的地球图标里。点一下，Gemini就会去网上搜最新信息。我查实时汇率、当天新闻、比赛比分时都会开这个开关。不开联网的话，它的知识有截止日期，问太新的事情会答不上来。开了联网，回答里会带来源链接，我可以点进去核对。这个功能在网页版和移动端都有，位置不太一样。我习惯在问时效性问题前先看一眼地球图标亮没亮。
2.3 基础操作：新建对话、选择模型、上下文管理与结果导出
新建对话的按钮在左上角，一个铅笔或者加号图标。我每次换一个完全不同的话题时，都会点一下新建。不新建的话，之前的聊天记录会一直留在上下文里，Gemini可能会把旧话题的细节带进新回答。我吃过这个亏：前面聊了菜谱，后面问代码，它居然在代码注释里写了“加盐少许”。新建对话就是给Gemini一个干净的脑子。我一般一个任务一个对话，比如“写周报”一个，“翻译论文”另一个。
选择模型在输入框上方或者右侧，有一个下拉菜单。默认可能是Flash，速度快，适合日常问答。Pro模型更聪明，处理复杂逻辑和长文档时我会切过去。Ultra我很少用，响应慢一些，而且有些地区还没开放。我自己的习惯是：先拿Flash试，如果回答不够好，再换Pro重新问。切换模型不会丢失当前对话，但回答风格会变。你可以都试试，感受一下差别。
上下文管理是新手最容易忽略的事。Gemini的记忆有限，聊得太长，它会把前面的内容忘掉或者混淆。我一般聊到二三十轮，就会让它“把上面的要点总结一下”，存成新对话的种子。结果导出很简单：选中回答，右键复制，或者点分享按钮导出到Google Docs。我写文章时，会让Gemini先列大纲，导出到Docs，再自己改。图片结果可以下载，代码块可以一键复制。这些操作都不难，用两次就熟了。
2.4 新手练习：信息查询、内容总结、翻译润色与创意生成
信息查询是我每天用得最多的。早上问一句“今天有什么科技新闻”，开联网，它会把标题和摘要列出来。我还会问“量子纠缠用大白话解释”，它举的例子比教科书好懂。查概念、查定义、查对比，Gemini都能接。我提醒自己：涉及医疗、法律、金融的答案，我会再搜一遍权威来源。把它当搜索引擎用可以，但别当唯一信源。我常做的练习是：随手抓一个不懂的词，让它用三种方式解释——给小孩、给大学生、给专家。
内容总结适合对付长文章。我复制一篇公众号文章，粘贴进去，说“用三句话总结”。它会提炼核心观点。PDF论文也可以直接上传，问它“研究方法是什么”。我试过把两万字的行业报告丢进去，让它列关键数据，它真的能挑出来。翻译润色是我的高频场景。中译英时，我会加一句“用商务邮件语气”。英译中时，我会说“保留专业术语”。它翻完，我还会让它“再润色一版，更口语”。创意生成我用来破冰：起产品名、写朋友圈文案、编睡前故事。有一次我让它“用王家卫风格写一段咖啡广告”，结果挺有意思。
这些练习不需要编程，打开网页就能做。我建议你每天花十分钟，挑一个场景玩一下。信息查询练准确度，内容总结练提炼，翻译润色练语气控制，创意生成练想象力。玩一周下来，你会对Gemini的脾气有感觉。知道它什么时候靠谱，什么时候需要你补一刀。
2.5 常见问题：响应异常、地区限制与账号安全设置
响应异常我遇到过几次。有时候输入问题，它转圈半天，过一会儿报错“发生错误”。我一般先刷新页面，不行就换一个网络节点。还有一次，它回答到一半突然断了，我重新发送同一个问题就好了。如果一直转圈，可能是你所在地区网络不稳定。我还会检查输入内容是不是太长，或者包含敏感词。把长问题拆成短句，通常能恢复。Gemini偶尔会“罢工”，别慌，换个时间再试。
地区限制是很多人的拦路虎。打开页面显示“Gemini目前在你所在的国家/地区不可用”。我试过换网络节点，换到支持的地区就能访问。手机端如果提示不可用，可以检查App商店的账号地区。我自己的经验是：尽量用稳定的连接，不要频繁切换节点，否则账号可能触发安全验证。有些功能比如联网搜索，在部分节点下也会受限。遇到限制，先确认节点位置，再清一下浏览器缓存。
账号安全设置我踩过一次坑。有段时间我收到Google的安全提醒，说有人尝试登录。我赶紧开了两步验证，换了强密码。Gemini本身不会泄露你的对话，但如果你分享账号，别人能看到历史记录。我建议：专用账号、两步验证、定期查看登录设备。不要在公共电脑上勾选“记住我”。如果你用API Key（后面章节会讲），千万别把它贴在公开代码里。账号安全这件事，花十分钟设置，能省很多麻烦。
这一章的内容，我尽量按自己第一次使用的顺序来写。你如果跟着走一遍，应该能顺利打开Gemini，看懂界面，新建对话，选模型，上传文件，做几个小练习。遇到报错或者地区限制，也知道去哪儿找原因。下一章我会讲提示词怎么写，怎么让Gemini的回答更合你心意。到时候你会发现，界面只是入口，真正好玩的是对话本身。
上一章结尾我提到，界面只是入口，对话本身才是重头戏。我自己用Gemini的前两个月，基本在瞎问。“帮我写个方案”“解释一下这个”这种指令，得到的结果总差口气。后来我逼自己把每次提问当成给实习生派活，想清楚要什么、给什么背景、输出成什么样。这个转变让Gemini的回答质量翻了一倍。这一章就把我摸索出来的提示词结构、多轮控制、多模态玩法，还有踩过的坑，按我自己的使用习惯讲一遍。
3.1 提示词基础结构：角色、任务、上下文、格式与约束
我教朋友写提示词时，喜欢让他们先做填空题。角色：你是一个__。任务：请帮我__。上下文：背景是__。格式：用__输出。约束：不要__，控制在__字。这五个空填完，提示词就不会太离谱。我自己的习惯是，角色和任务必须写清楚，上下文看情况给，格式和约束能省掉很多来回修改。比如我要写一份竞品分析，会这样开头：“你是一个有十年经验的产品经理。请帮我分析三款在线笔记工具的优劣势。我的产品是面向学生群体的轻量笔记App。用表格输出，列名分别是功能、价格、目标用户、差异点。不要超过500字，语气客观。”这个提示词不算长，但Gemini给出的表格直接能用。
我朋友小张最开始只写“帮我分析一下竞品”，Gemini回了一大段泛泛而谈。我让他加上角色和格式约束，结果立刻具体了。角色能给Gemini一个知识范围，比如“你是一个Python专家”和“你是一个小学老师”，同样问递归，解释方式完全不同。任务要动词开头，别写“关于……的内容”，写“总结”“对比”“翻译”“生成”。上下文我一般放两三条关键信息，放太多反而干扰。格式我常用“分点”“表格”“JSON”“Markdown”。约束里我会写“不要用专业术语”“不要编造数据”“如果不知道就说不知道”。这些约束能减少胡编。
有一次我让Gemini“写一封给客户的道歉信”，没给角色和约束，它写得特别官方，像机器人。我重新写：“你是一个创业公司的客服负责人。请给一位因发货延迟而不满的客户写道歉信。背景是仓库搬迁导致延迟三天。用亲切口语，不超过200字，不要推卸责任，结尾给一张优惠券。”这次它写出来的信，我几乎没改就发出去了。提示词结构就像给AI画框，框越清晰，它越不会跑偏。我现在的习惯是，每次打开新对话，先花三十秒想清楚这五个空。
3.2 多轮对话与上下文控制：追问、纠错、摘要与重置
多轮对话是我觉得Gemini最像人的地方。第一轮回答不满意，我不会重新开一个对话，而是直接追问。比如它列了五个要点，我会说“第三个展开讲，给一个具体例子”。它就会针对第三点深入。追问的关键是引用它的原话，比如“你刚才说的‘用户留存’部分，能不能用AARRR模型重新梳理”。这样它知道你在说哪一块。我还会用纠错式追问：“不对，这个数据是2023年的，请用2024年的重新回答。”或者“语气太正式了，换成朋友聊天的感觉。”Gemini不会因为被纠正而生气，它马上调整。
上下文控制是门手艺。Gemini的记忆窗口有限，聊到三四十轮，它可能把前面说的细节忘了。我自己的做法是，每聊完一个阶段，就让它“把上面的关键结论总结成五条，用编号列出”。然后我复制这五条，新建一个对话，粘贴进去说“基于以下背景继续”。这叫摘要重置。还有一种情况，话题彻底变了，比如从写代码跳到写菜谱，我会直接新建对话。不新建的话，它可能在代码注释里给你加一勺盐。我吃过这个亏，现在养成了习惯：一个任务一个对话，任务结束就导出结果，关掉。
我观察过自己跟Gemini的对话记录，发现高效对话有个节奏：第一轮给完整提示词，第二轮追问细节，第三轮纠错或换角度，第四轮让它总结。超过四轮还没得到想要的结果，大概率是提示词本身有问题，我会重置对话，重新写一遍。重置不是失败，是止损。有人觉得多轮聊天显得自己跟AI很熟，其实上下文太长反而让回答变糊涂。我见过一个朋友跟Gemini聊了八十轮，最后问“我们刚才聊了什么”，Gemini的回答已经串成一锅粥了。
3.3 多模态提示：图片、PDF、表格与音视频处理思路
Gemini能看图片、读PDF、解析表格，还能处理音视频。我最早用多模态是拍了一张冰箱里的照片，问“能用这些食材做什么菜”。它认出了鸡蛋、西红柿、半颗白菜，给了三个菜谱。后来我工作中用得更多。上传一张折线图，我会说“这张图展示了什么趋势，拐点出现在哪个月，可能的原因是什么”。如果图片里有文字，我会加一句“提取图片中的文字，并按日期排序”。多模态提示的要点是告诉它看哪里。比如一张复杂的仪表盘截图，我会说“只看右下角的温度计，读数是多少”。不说清楚，它可能把整个图描述一遍，浪费时间。
PDF处理是我每周都要用的。我一般把论文或报告拖进去，先问“用三句话总结核心观点”，再问“研究方法部分用了哪些数据来源”。如果PDF很长，我会分章节提问，避免它漏掉细节。表格文件我试过CSV和Excel，Gemini能直接读取。我让它“找出销售额下降超过10%的月份，并列出对应产品”。它会给一个筛选后的列表。音视频方面，我常用手机录一段会议录音，传给Gemini，让它“提取待办事项和负责人”。它转文字后能识别出“张三下周交报告”这种任务。视频我试过传一段产品演示，问“演示中提到了哪三个卖点”，它也能答上来。多模态提示的核心是：先告诉它文件类型，再指定关注区域，最后要求输出格式。
有个小技巧我经常用：把图片和文字提示一起发。比如上传一张竞品海报，同时写“分析这张海报的配色、文案和排版，给三条改进建议”。这样Gemini既看了图，又知道你要什么维度的分析。如果只传图不说话，它可能只描述表面。我朋友试过传一张发票，问“这张发票能报销吗”，Gemini说“这是一张发票”，没给判断。后来他改成“你是一个财务助理，请检查这张发票的抬头、金额和日期是否完整，并判断是否符合报销要求”，回答就具体多了。多模态不是魔法，它仍然需要清晰的指令。
3.4 常见误区与优化：避免模糊指令、事实核验与隐私保护
我踩过最大的坑是模糊指令。刚开始我总说“写得好一点”“再优化一下”“要专业”。Gemini不知道“好”的标准是什么，只能猜。后来我改成“把第二段改得更口语，加一个生活化的例子”“把专业术语替换成初中生能懂的词”“删掉所有形容词，只保留数据和结论”。模糊指令就像跟理发师说“剪短一点”，结果永远不是你想要的。另一种模糊是代词太多。“把它改成那样”“基于这个再写一个”，Gemini可能分不清“它”和“这个”指什么。我现在会明确说“把上面第三段提到的用户画像，改写成一段150字的描述”。
事实核验是必须养成的习惯。Gemini会编造参考文献、统计数据、法律条文。我试过问一个不太出名的历史事件，它给了一个年份和人物，我搜了一下发现是错的。从那以后，涉及数字、日期、人名、法条、医疗建议，我都会开联网搜索，或者自己再查一遍。我还会让Gemini“给出信息来源链接”，如果它给不出，我就当这个回答不可靠。另一个技巧是交叉验证：把同一个问题用不同方式问两遍，看答案是否一致。不一致的地方就是需要警惕的地方。
隐私保护很多人不注意。我见过有人把公司内部财报PDF传给Gemini做总结，里面包含未公开的营收数据。Gemini的对话默认可能被用于训练，除非你关闭相关设置。我的做法是：敏感信息先脱敏，把公司名换成“A公司”，把具体数字换成“约X万”。个人隐私方面，不要传身份证、银行卡、密码、家庭住址。我自己的Gemini账号是专用的，不和私人邮箱混用。如果你用API，密钥更不能贴在公开代码里。提示词里也不要写“我的手机号是……”，AI不需要这些信息也能完成任务。
3.5 场景化模板：学习、办公、编程与内容创作
我整理了几个自己常用的提示词模板，你可以直接改。学习场景，我常用费曼技巧：“你是一个耐心的导师。请用费曼学习法解释[概念]。先给一个比喻，再拆解核心原理，最后指出一个常见误解。用口语，不超过300字。”这个模板我用来学区块链、量子计算、光合作用，效果比看百科好。另一个学习模板是出题：“基于以下文章，出五道选择题，四个选项，附答案和解析。”我用来复习考试。
办公场景，周报模板：“你是一个项目经理。请根据以下工作记录，写一份周报。分三部分：本周完成、下周计划、风险与求助。用简洁的条目，不要超过400字。”会议纪要模板：“提取以下录音转文字中的决策、待办和负责人，用表格输出。”邮件模板：“你是一个商务助理。请给[对象]写一封[目的]的邮件。语气[正式/友好]，字数[范围]，不要用套话。”
编程场景，代码解释：“你是一个资深Python工程师。请解释以下代码的功能、输入输出和潜在bug。用注释形式标出关键行。”调试模板：“我运行这段代码报错[错误信息]。请分析可能原因，给出修复后的代码，并解释修改点。”代码审查：“检查以下代码的安全漏洞、性能问题和可读性，按严重程度排序。”
内容创作场景，小红书文案：“你是一个小红书博主。请为[产品]写一篇种草笔记。标题带emoji，正文分三段，每段不超过三行，结尾加五个相关话题标签。语气活泼，不要夸张。”公众号开头：“你是一个科技专栏作者。请为[主题]写一个吸引人的开头，用故事或问题引入，不超过150字。”短视频脚本：“你是一个短视频编剧。请写一个60秒口播脚本，主题是[主题]。前3秒抓注意力，中间给三个要点，结尾引导关注。”
这些模板不是死的。我每次用都会根据具体任务微调。比如给小学生解释和给大学生解释，角色描述就不一样。模板的价值是让你不用从零开始想提示词。我建议你把自己常用的场景写成模板，存在备忘录里。下次打开Gemini，复制粘贴改几个词，效率高很多。提示词这门手艺，练得越多，越知道怎么跟AI说话。下一章我会讲API调用，那时候你会发现，提示词的逻辑在代码里同样适用。
上一章末尾我说提示词的逻辑在代码里同样适用。当时只是顺嘴一提。等我真正把Gemini API跑通，才发现这句话比我预想的更对。网页聊天是手动挡，API是自动挡。自动挡能批量处理、能集成到自己的工具里，但前提是你得先学会挂挡。我把自己从零开始调通第一个请求的过程拆开讲，包括准备、认证、写代码、调参数、管密钥。整个过程我踩了七八个坑，有些坑现在想起来还觉得蠢。
4.1 API调用前置准备：Google AI Studio、API Key与SDK选择
我最早以为调API要搞什么企业认证。打开Google AI Studio才发现，个人账号就能用。网址是aistudio.google.com。用Google账号登录，点“Get API Key”，创建一个密钥。整个过程不到一分钟。我提醒一句，这个页面需要能正常访问Google服务。网络环境你自己解决，我不多说。创建好的密钥长得像一串随机字符，复制下来。别截图发群里，别贴到GitHub。我朋友干过这事，第二天收到账单警告。
SDK我选了Python。理由很简单，我平时用Python写脚本。Google提供了google-generativeai这个库，pip install就能装。Node.js也有对应的包，叫@google/generative-ai。如果你只想快速测试，用REST加上curl也行，不用装任何东西。我刚开始用curl试了一次，看到返回的JSON，心里才踏实。选SDK这件事，看你的主力语言。我选Python，后面做批量处理、接数据库都方便。Node.js适合做网页后端。REST适合临时调试。
装好库之后，我把API Key存到环境变量里。Windows用set，Mac用export，或者在代码里读.env文件。千万别学我第一版代码，直接把密钥写成字符串。那段代码我传到了私有仓库，后来删了，但心里一直别扭。Google AI Studio的免费额度够新手玩很久。我前两周的测试基本没花钱。你可以在AI Studio里看到用量。前置准备就这些：账号、密钥、SDK。没有想象中复杂。
4.2 认证与请求结构：REST、Python与Node.js SDK
认证方面，REST请求把API Key放在URL参数里，比如?key=YOUR_API_KEY，或者放在请求头x-goog-api-key。我两种都试过，都能通。请求结构比网页聊天多了一层。网页上你打字就行。API里你要构造一个JSON。最基本的字段是contents，里面放角色和文本。角色可以是user或model。我一开始忘了写角色，直接传字符串，结果报错。后来改成列表，里面套字典，才跑通。REST的端点是generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent。方法用POST。
Python SDK把认证和请求结构都包了一层。初始化只要一行：genai.configure(api_key=os.environ["GOOGLE_API_KEY"])。然后model = genai.GenerativeModel('gemini-pro')。调用生成：response = model.generate_content("用一句话解释什么是API")。打印response.text就能看到回答。我写第一个Python脚本时，忘了配环境变量，报错说API key not valid。查了十分钟才发现是变量名写错了。Node.js SDK类似：const genAI = new GoogleGenerativeAI(process.env.API_KEY); const model = genAI.getGenerativeModel({ model: "gemini-pro" }); const result = await model.generateContent("..."); 然后result.response.text()。
请求结构里还有generationConfig和safetySettings。这两个是可选的。generationConfig用来控制温度、最大token这些。safetySettings用来调整安全过滤。我一开始没传这两个，也能用。后来做内容生成，发现默认温度有点低，回答太保守，才去翻文档。REST和SDK的字段名基本一致。如果你用REST，记得Content-Type是application/json。我漏了这个头，被服务器拒过一次。认证和请求结构弄明白，后面的调用就是填空。
4.3 第一个API示例：文本生成、流式输出与错误处理
我的第一个完整示例是文本生成。代码大概十行。导入库、配置密钥、选模型、发提示、打印结果。我跑通的那一刻，屏幕上出现了一段关于“如何煮出一杯好咖啡”的回答。那种感觉跟网页聊天不一样。网页上是你跟AI面对面。API是你派了一个信使，信使带回一封信。我后来把这个脚本改成命令行工具，输入问题，输出回答。你可以在提示词里加角色和格式，跟上一章讲的一样。比如“你是一个咖啡师，用三个要点回答，每点不超过二十字”。API照样能理解。
流式输出我试了一次就爱上了。默认情况下，Gemini生成完整回答才返回。流式输出是边生成边返回，像打字机一样。Python里加stream=True，然后遍历response。代码是：response = model.generate_content("写一首关于春天的短诗", stream=True); for chunk in response: print(chunk.text, end="")。这个在网页端感受不明显，但在自己的应用里，用户不用干等。我拿它做了一个本地问答小工具，回答超过两百字时，流式输出让等待感少了很多。不过流式模式下错误处理会麻烦一点，有的chunk可能带错误信息，需要判断。
错误处理是我花时间最多的地方。API调用会失败。网络超时、密钥无效、请求太频繁、内容被安全过滤。我一开始不写try/except，脚本直接崩，啥也看不到。后来我养成习惯，把所有调用包在try里，捕获Exception，打印e。常见错误码：400是请求格式不对，401是密钥错，429是超配额。429我遇到最多，免费额度有每分钟请求限制。我的做法是加一个简单的重试，等两秒再发。如果连续失败三次，就停下来看看是不是提示词违规。错误处理写不好，调试起来就是盲人摸象。
4.4 模型参数详解：温度、最大输出、候选数与安全设置
温度这个参数我调得最多。它的范围是0到2。温度低，回答更确定、更保守。温度高，回答更随机、更有创意。我做事实问答时用0.2，比如“北京有多少个区”。做文案创意时用0.9，比如“给一款新饮料想五个广告语”。默认值好像是0.9还是1.0，我记不清了。我自己的经验：写代码用0.2，写故事用1.0，日常对话用0.7。温度调到2的时候，回答会变得很飘，甚至胡言乱语。有一次我调到1.8问历史事件，它把两个朝代的年份混在一起了。
最大输出token数控制回答长度。默认可能比较小，长回答会被截断。我写报告总结时，会设置max_output_tokens=2048。注意这个数不是字数，是token数。一个中文词大概一到两个token。设太小，回答到一半停了。设太大，浪费额度。候选数candidate_count可以让你一次生成多个版本。我一般用1。做A/B测试时会设3，然后挑一个最好的。安全设置里有很多类别，比如仇恨、色情、暴力。默认设置会拦截一些内容。我写技术文章时，偶尔提到“攻击”“漏洞”就被拦截。后来我在safetySettings里把对应类别调成BLOCK_NONE，问题就解决了。调安全设置要谨慎，别把该拦的也放开了。
top_p和top_k也能调。top_p叫核采样，控制候选词的累积概率。top_k控制候选词数量。我很少动这两个，默认就行。温度已经够我用了。如果你要做严谨的数学推理，把温度设成0，top_p设成0.1。做创意生成，温度1.0以上，top_p 0.95。参数没有绝对正确的值，跟你的任务有关。我建议你建一个测试集，用同一个提示词跑不同参数，对比结果。我做过一个表格，温度从0.2到1.4，每个值跑三次，选最稳定的那个。这个笨办法帮我省了很多后续调试。
4.5 API计费、配额与安全：密钥管理、速率限制与成本控制
计费按token算。输入token和输出token分开计价。Gemini Pro的价格我印象中是每百万输入token几毛钱，输出贵一些。免费额度每个月有一定量，具体数字会变，去官网看。我第一个月做了大量测试，账单是零。第二个月我写了一个批量总结新闻的脚本，跑了三千条，花了不到一美元。计费不可怕，可怕的是忘了关。我见过有人把API Key放在前端代码里，被人扫到，一夜之间欠了几百美元。密钥管理第一条：永远不要提交到公开仓库。第二条：用环境变量。第三条：定期轮换。我在Google AI Studio里可以删除旧密钥，生成新的。我每两个月换一次。
配额分两种：每分钟请求数（RPM）和每分钟token数（TPM）。免费层的RPM很低，我忘了具体多少。反正我同时发十个请求，就会收到429。解决方法是加延迟。Python里用time.sleep(1)或者指数退避。我写了一个装饰器，遇到429就等2秒、4秒、8秒。如果你的应用需要高并发，就得升级到付费层。付费层的RPM高很多。我目前还在免费层，我的用量不大。速率限制不只是技术问题，也是设计问题。你得让调用节奏匹配你的配额。
成本控制我有三个习惯。第一，精简提示词。不要写一大堆废话，token就是钱。第二，用上下文缓存。如果同一个长文档要问很多问题，先上传一次，后面引用缓存。Gemini有缓存功能，能省输入token。第三，批处理。把多个小任务合并成一个请求。比如要翻译十句话，不要发十次，发一次，让模型返回一个列表。我做过对比，批处理能省一半以上的调用次数。安全方面，除了密钥，还要注意输出内容。API返回的内容如果直接展示给用户，要做过滤。我写了一个简单的关键词黑名单，防止模型输出不当内容。API给了你能力，也给了你责任。管好密钥、控制好速率、算好成本，你才能安心用下去。
下一章我会讲多模态API和函数调用。那些东西更有意思，但基础不牢，容易翻车。我建议你先把这章的代码跑通，把参数调一遍，把错误处理写好。提示词逻辑在代码里同样适用，这句话你会在下一个请求里真正体会到。
上一章我跑通了文本请求，心里踏实了几天。等我开始处理图片、PDF、让模型调函数、接进自己的小工具，才发现API的进阶玩法才是真正费脑子的地方。我把自己踩过的坑和最后跑通的方案写下来，你照着做能少走点弯路。
5.1 多模态API：图像理解、PDF解析、音频与视频能力调用
我第一次用多模态API，是想让Gemini帮我读发票。网页上直接拖图片就行，API里得把图片转成base64，再塞进contents。我用的Python，读图用PIL，转base64用标准库。请求体里加一个inline_data，指定mime_type为image/jpeg，data放base64字符串。跑通之后，Gemini准确说出了发票上的金额和日期。那个瞬间我觉得比文本请求有意思多了。图片别太大，超过几兆会报错。我一般先压缩到1兆以内再传。
PDF解析我试过两种方式。一种直接把PDF文件传给API，用file.upload上传，拿到文件URI，再在请求里引用。另一种把PDF每页转成图片，当图片处理。直接传PDF方便，省了转换步骤。我拿一份十页的产品说明书测试，Gemini能概括出主要功能点。不过PDF里的表格和复杂排版有时候会乱。音频和视频我也碰了碰。音频传wav或mp3，Gemini能转文字、做摘要。视频比较吃资源，我传了一个两分钟的短片，让它描述画面内容。等待时间比文本长很多，token消耗也大。我建议视频先抽帧，按图片处理，成本更低。
多模态请求最容易错在mime_type。我写错过一次，把image/png写成image/jpg，API直接返回400。安全过滤也会拦截一些图片。我传过一张带武器标志的新闻截图，被拦了。后来我在safetySettings里把暴力类别调成BLOCK_NONE，才通过。但调安全设置要小心，别把该拦的也放开了。我现在的习惯是先用小图片、短音频测试，跑通了再换大文件。多模态API让Gemini从文字助手变成能看能听的工具。你花半小时调通，后面能省很多手动处理的活。
5.2 结构化输出与函数调用：JSON模式、工具调用与业务自动化
我想让Gemini返回JSON，方便程序解析。一开始我在提示词里写“请返回JSON格式”，模型有时候会在JSON外面加一句“好的，以下是结果”。这段文字让json.loads直接报错。后来我用了response_mime_type="application/json"，模型就只吐纯JSON了。我拿它做信息抽取，比如从一段产品评论里提取情感、关键词、评分。返回的JSON放进数据库，一条条清清楚楚。这个功能对做自动化的人来说太实用了。你还可以在提示词里给出JSON schema的示例，模型会更听话。
函数调用是另一个让我兴奋的点。我定义了一个查天气的函数，写清楚函数名、参数、描述。用户问“北京今天多少度”，Gemini不会直接回答，而是返回一个函数调用请求，里面带着参数{city: "北京"}。我拿到这个请求，自己去调天气API，再把结果传回给Gemini。Gemini结合天气数据，生成一句自然语言回答。这个流程让模型能操作外部系统。我做过一个自动填表的demo，用户说“帮我订明天下午两点的会议室”，Gemini解析出时间、地点，调用我的预订函数。业务自动化场景里，这个能力能省掉大量胶水代码。
函数调用也有坑。函数描述写得太模糊，模型会选错函数。我定义了一个“发送邮件”和“发送短信”，描述里都写了“发送消息”，模型就混了。后来我把描述改具体，加上“邮件用于正式通知，短信用于紧急提醒”，准确率上来了。多轮函数调用还要维护对话历史，每次调用和结果都要按格式追加。我一开始忘了把函数结果传回去，模型一直重复调用同一个函数。结构化输出和函数调用配合起来，Gemini就从聊天机器人变成了能干活的智能体。
5.3 上下文缓存、长文本与批量处理：提升性能与降低成本
我处理一份五十页的合同，反复问不同条款。每次把全文传进去，输入token哗哗地涨。Gemini有上下文缓存功能，我把合同内容创建成缓存，拿到一个缓存ID。后续请求引用这个ID，不用再传全文。输入成本降了一大截，响应速度也快了。缓存有最小token限制，太短的内容不划算。还有过期时间，我一般设一小时。如果文档要问很多轮，缓存太值了。我算过一笔账，同一份长文档问十个问题，用缓存比不用省了七成输入费用。
长文本处理还有别的思路。Gemini支持很长的上下文，但太长会变慢。我习惯把长文档分段，每段做摘要，再把摘要拼起来。或者用检索的方式，只把相关段落传给模型。批量处理是另一个省钱的招。我要翻译一百条用户评论，不要发一百次请求。我把评论做成列表，一次发给Gemini，让它返回一个列表。一次请求搞定，调用次数从一百降到一。我做过新闻摘要，三千条新闻，每五十条一批，跑了六十次请求。比单条跑快得多，费用也低。批量处理要注意输出格式，要求模型返回JSON数组最稳。
上下文缓存和批量处理各有适用场景。缓存适合固定长文档、多轮问答。批量适合大量短任务、格式统一。我自己的项目里，两者经常一起用。先缓存一份知识库文档，再把用户问题批量发过去。性能提升很明显。速率限制还是要留意，批量请求太大可能触发429。我的做法是每批不超过五十条，批与批之间加一秒延迟。这些优化手段不复杂，能让你用更少的钱跑更多的量。
5.4 集成实战：接入聊天机器人、知识库、工作流与Web应用
我用Flask写过一个简单的聊天机器人。前端一个输入框，后端接收消息，调Gemini API，返回回答。流式输出用Server-Sent Events，用户能看着文字一个个蹦出来。每个用户开一个会话，对话历史存在内存里。并发一上来，内存涨得很快。后来我改成把历史存Redis，问题才解决。聊天机器人接Gemini不难，难的是管理上下文长度。我设了一个上限，超过就自动摘要旧对话。这样既能记住重要信息，又不会把token撑爆。
知识库集成是我花时间最多的。Gemini本身不存你的私有数据。我把公司文档切片，用嵌入模型转成向量，存到向量数据库。用户提问时，先检索最相关的几个片段，再把片段和问题一起发给Gemini。这样回答有据可依，不会瞎编。我试过把整本手册塞进提示词，效果差还贵。检索增强生成才是正路。工作流方面，我用n8n把Gemini接进邮件自动回复。收到邮件，提取正文，调API生成草稿，人工确认后发送。Web应用里千万注意API密钥安全。我见过有人把密钥写在前端JS里，被人扒出来刷了几百美元。密钥必须放后端，通过自己的服务器转发请求。
集成实战里，稳定性比功能更重要。Gemini API偶尔会超时或返回错误。我在后端加了重试和降级逻辑。重试三次还失败，就返回一个友好提示，不让用户干等。聊天机器人、知识库、工作流，这些场景对延迟敏感。流式输出能缓解等待焦虑。我建议你先做一个最小可用版本，跑通一个场景，再慢慢加功能。别一上来就搞大而全，容易卡在半路。
5.5 调试与评估：日志、提示词迭代、效果评测与异常监控
我每次调API都会记日志。请求内容、响应内容、token用量、耗时、错误码，全写进文件。用Python的logging模块，按天切分。出问题的时候，翻日志比猜快得多。有一次回答质量突然下降，我查日志发现是提示词里少了一个约束条件。日志还帮我发现过一个密钥泄漏，某个IP在疯狂调用。调试多模态请求时，我把base64图片也存下来，方便复现。日志不用多复杂，关键是坚持记。
提示词迭代我靠一个测试集。大概二十个典型问题，覆盖我的主要场景。每次改提示词，跑一遍测试集，人工打分。有时候改一个词，效果差很多。我还会用另一个模型来评估回答质量，省点人力。效果评测不能只看单次结果，要看稳定性。同一个提示词跑五次，有一次翻车就不行。我建了一个简单的评分表，准确、完整、格式正确各占几分。迭代了十几版之后，提示词才稳定下来。
异常监控我是后来才加的。连续失败超过三次、响应时间超过十秒、token用量突然翻倍，这些情况我会收到邮件。安全过滤触发次数也监控，频繁触发说明提示词或者输入有问题。监控让我能早发现早处理。有一次API配额用完了，监控告警，我及时升级了付费层，没影响线上服务。调试和评估是个长期活，不是一次搞定。你把这些基础打牢，后面做更复杂的集成心里才有底。下一章我会带你做两个实战项目，把这些进阶能力串起来用。
学完API进阶那几招，我手里攒了一堆零散的能力。图像识别、函数调用、上下文缓存，单独用都跑通了，可它们凑在一起能不能干点正经事？我花了两个周末，做了两个小项目。一个给自己用，一个给团队用。做完之后我才觉得，前面那些章节没白折腾。
6.1 实战一：新手用Gemini搭建个人效率助手
我每天早上到公司第一件事是翻邮件。十几封邮件看完，半小时没了。大部分是通知和抄送，真正要处理的没几封。我就想能不能让Gemini帮我先把邮件过一遍。Web端就能做，不用写代码。我把邮件内容复制粘贴到Gemini对话框，让它按紧急程度分类，列出需要我回复的条目。提示词写清楚：角色是行政助理，任务是从邮件里提取待办事项，格式用表格。跑了两天，我发现它分类挺准，偶尔把广告邮件当成重要通知。我加了一条约束，广告和推广类直接忽略。效果好了很多。
后来我不满足于只处理邮件。我把每天的会议记录也丢进去。开完会我把录音转成文字，粘贴给Gemini，让它提取决策点和待办事项，指定负责人和截止时间。它输出的表格我直接贴进Notion。这个流程帮我省了写会议纪要的时间。我把常用的几个提示词存成模板，用的时候改一下内容就行。新手做效率助手，不用碰API。Web端加上好的提示词，够用了。关键是找到自己每天重复做的信息处理工作，让Gemini替你干第一步。
我还在手机上装了Gemini App。通勤路上看到有意思的文章，分享到Gemini，让它总结要点。到公司打开电脑，总结已经在了。这种碎片时间的利用，比我以前收藏一堆文章回头再看效率高。个人效率助手的核心不是技术多复杂，是把你日常的信息流接进来。我用了一个月，慢慢把邮件摘要、会议纪要、文章提炼三个场景固定下来。每个场景一个提示词模板。不追求大而全，先把一个场景跑顺。你如果刚开始，选你每天花时间最多的那件事，让Gemini帮你做第一轮处理。
6.2 实战二：开发者用Gemini API构建智能问答服务
个人助手用爽了，我想给团队做一个内部知识问答服务。我们团队的技术文档散在好几个地方，新人找东西费劲。我打算把文档整合起来，用Gemini API做一个能对话的查询入口。上一章学的检索增强生成派上了用场。我把文档切片，用嵌入模型转成向量，存进Chroma。用户提问的时候，先检索最相关的五个片段。这些片段加上问题，拼成提示词发给Gemini。返回的答案后面附上来源文档的链接。这样用户能验证答案，不会盲目相信模型。
后端我用FastAPI。一个接口接收问题，走检索，调Gemini，返回答案。流式输出用SSE，前端能一个字一个字显示。开始我犯了个错，把检索到的五个片段全塞进提示词，不管长短。有时候检索结果里有很长的文档，token一下子上去了。后来我限制了每个片段的长度，超过就截断。答案质量没降，成本下来了。函数调用我也用上了。用户问“这个接口的负责人是谁”，我定义了一个查人员信息的函数。Gemini识别出意图，返回函数调用请求。我去查内部通讯录，把结果传回去。Gemini生成最终回答。这样问答服务不光能查文档，还能查结构化数据。
知识问答服务上线第一个月，团队里十几个人在用。我收集了他们的反馈。有人说答案太长，有人说找不到想要的。我根据反馈调提示词，加了一条“答案不超过三句话，先给结论再给依据”。满意度上来了。做这个项目的过程中，我最大的体会是检索质量决定上限。检索出来的片段不相关，Gemini再强也答不好。我花了比调API更多的时间在切片策略和检索排序上。切片别太大也别太小。我试过按段落切，效果比按固定字数切好。问答服务不是搭完就完事，得持续看日志，看哪些问题答得不好，回头优化检索。
6.3 部署与上线检查：环境配置、权限控制与稳定性保障
本地跑通和上线跑稳是两码事。我第一个版本把API密钥写在代码里，直接推到GitHub。好在发现得早，没出事。后来我把密钥放环境变量，用python-dotenv加载。服务器上再设一遍，代码里只读不写。团队里有人需要调API，我给他们单独建密钥，每人一个，出问题能追溯到人。Google AI Studio里能设配额上限，我按人头设了每日调用上限。防止有人写错循环把额度跑光。
服务器我选了台便宜的云主机。Docker打包，一条命令启动。环境变量在docker-compose里配。日志挂载到宿主机，方便查看。稳定性方面我加了几个保险。API调用超时设了十秒，超时自动重试一次。重试还失败就返回缓存里的历史答案，或者提示用户稍后再试。速率限制用令牌桶算法，每个用户每秒最多两个请求。防止有人恶意刷接口。监控用简单的方式，接口失败率超过百分之五、平均响应时间超过三秒，给我发邮件。这些配置写起来不复杂，出问题的时候能救命。
上线前我列了一个检查清单。密钥是否在环境变量里、日志是否开启了、重试逻辑是否生效、速率限制是否配置、监控告警是否测试过。每项打勾才发布。团队用了一个月，没出大故障。有一次Gemini API区域故障，我们的服务降级到返回检索片段原文，用户虽然没拿到生成答案，但至少能自己看文档。这个降级逻辑是我上线前专门加的。部署这件事，多做一步准备，线上少一次事故。你如果准备上线自己的服务，把密钥管理、重试降级、监控告警这三件事做扎实，比加新功能重要。
6.4 持续学习资源：官方文档、模型更新、社区案例与常见问题
Gemini更新挺快的。我养成了每周看一次官方文档的习惯。Google AI的文档里有个更新日志页面，模型版本、API变更、新功能都列在上面。有一次Gemini更新了函数调用的参数格式，我在更新日志里提前看到，改了代码。不然线上服务突然报错，排查起来很麻烦。官方文档的快速入门和示例代码我常翻，有些写法比我自己的更简洁。AI Studio里的示例项目也值得看，能学到不少工程上的技巧。
社区资源我主要看两个地方。一个是GitHub上搜Gemini的仓库，看别人怎么用。有个仓库专门收集Gemini的提示词模板，我从中挑了几个改改用。另一个是Reddit的GoogleGemini版块。上面有人分享踩坑经验，也有人问问题。我遇到报错的时候，先搜社区有没有人遇到过。大部分情况都能找到答案。Stack Overflow上Gemini相关的问答也越来越多。社区的好处是你能看到真实场景里的用法，官方文档不会告诉你这些。
常见问题我整理了一份自己的FAQ。比如API返回429怎么办、多模态请求怎么压缩图片、函数调用不触发怎么调描述。每次遇到新问题解决之后，我就补一条进去。这份FAQ后来成了团队新人的入门材料。学习资源不在多，在持续看。我给自己定了个规矩，每周至少花一小时看官方更新和社区帖子。这一小时投入，能帮我省掉后面几小时的调试时间。模型在进化，用法在变化，停下学习就会掉队。
6.5 学习成果复盘：从会用、会调到能集成、能优化
回头看从第一章到现在，变化挺大的。最开始我连Gemini界面都不熟，只会打字提问。现在我能用API搭出一个团队在用的问答服务。这个过程中，会用是第一步，把Web端的基本操作和提示词技巧练熟。会调是第二步，能发API请求、处理响应、调试错误。能集成是第三步，把Gemini接进自己的系统，跟数据库、消息队列、前端应用配合。能优化是第四步，关注成本、延迟、稳定性，让服务跑得久跑得稳。每一步都需要动手做，光看教程学不会。
我踩过的坑总结下来有几个。密钥别写死在代码里，这是底线。上下文管理要有上限，别让对话历史无限增长。检索增强生成比硬塞长文本效果好，也便宜。函数调用的描述要写具体，别让模型猜。批量处理能省调用次数，但要注意每批的大小。这些经验没有一条是从文档里直接读到的，都是自己跑项目跑出来的。你如果正在学，别怕犯错。每个报错都是一次学习机会。我到现在还经常遇到新问题，解决一个就记一条。
下一步我打算试试Gemini的视频理解能力。上一章只做了简单测试，我想用在监控场景里，让Gemini分析摄像头画面，发现异常自动报警。这个项目比问答服务复杂，涉及实时流处理和低延迟要求。不过有了前面的积累，我心里有底。学习Gemini的过程让我明白一个道理，工具在变，解决问题的思路不变。把基础打牢，新功能来了上手就快。你跟着这个教程走到这里，应该也有了自己的心得。接下来找个自己真正需要的场景，动手做一个项目。做出来一个，比看十篇教程管用。
评论
发表评论