Gemini 3.5 Flash 入门：实用指南

上个月，我正在搭建一个客服工单仪表盘，需要处理收到的工单、对它们进行分类、提取关键信息并起草回复。一开始我用的是个比较重的大模型，但每天要处理几千张工单，我的 API 账单很快就成了项目里最烧钱的一项。我需要速度快、成本低，但又不能牺牲太多智能。就在这时候，我决定试试 Gemini 3.5 Flash。

Google 把 Flash 定位为速度和成本优化版的模型，但依然能提供他们所谓的“持续的前沿级智能”。说白了就是：它应该几乎和那些大模型一样聪明，但速度更快、价格更便宜。在我的工单处理流程中把它摸透之后，我来手把手教你怎么配置，它在哪些方面特别出彩，又在哪些地方容易踩坑。

第一步：获取 API Key

首先，你得有访问权限。打开 Google AI Studio (aistudio.google.com)，用你的 Google 账号登录。

登录后，点击左侧边栏的“Get API Key”按钮。系统会提示你在 Google Cloud 中创建一个新项目，或者选择一个已有的项目。为了互不干扰，我直接建了个名叫“flash-testing”的新项目。

点击“Create API key in new project”，它就会为你生成一个密钥。立马复制保存好！我之前就吃过亏，没保存就点走了，结果只能重新生成一个——挺烦人的，但也不算什么大灾难。

把它设为环境变量，这样你就不会不小心把它硬编码到代码里了：

export GEMINI_API_KEY="your-api-key-here"

我把这行加到了我的 .zshrc 文件里，这样每次开终端它都在。

第二步：发起第一次调用

我是写 Python 的，所以直接装了官方 SDK：

pip install google-generativeai

这是我写的第一个测试脚本——一个简单的分类任务，跟我在客服工单里的需求差不多：

import google.generativeai as genai
import os

genai.configure(api_key=os.environ["GEMINI_API_KEY"])

model = genai.GenerativeModel('gemini-3.5-flash')

response = model.generate_content(
    "Categorize this support ticket into one of: [Billing, Technical, Account, General]. "
    "Ticket: 'I've been charged twice for my subscription this month and I can't find a way to request a refund through the settings page.' "
    "Respond with only the category name."
)

print(response.text)

运行一下，你应该会得到：Billing

响应不到 300 毫秒就回来了。这是我第一次发出“哇”的时刻。之前用的那个大模型，干同样的活儿得要 2-3 秒。当你每天要处理几千个请求时，这个差距可是天壤之别。

第三步：为真实工作流提供结构化输出

做个演示的话，简单分类还行，但我真实的处理流程需要提取结构化数据。我需要分类、紧急程度和摘要——而且全都要能被代码程序化解析的格式。

这就是我遇到的第一个坑。一开始，我试着直接在提示词里要 JSON，然后手动解析：

# 我的第一次尝试（很脆弱）
response = model.generate_content(
    "Extract from this ticket and return as JSON: category, urgency (1-5), summary. "
    "Ticket: 'System has been down for 4 hours, all our production servers are offline, losing $50k/hour.'"
)

有时候它返回的是干净的 JSON；有时候它把 JSON 裹在 markdown 代码块里；还有时候它会在前面加上句废话，比如“这是提取的信息：”，直接把我的解析器搞崩了。

靠谱的做法是使用 API 内置的 JSON 模式：

import json

model = genai.GenerativeModel(
    'gemini-3.5-flash',
    generation_config=genai.GenerationConfig(
        response_mime_type="application/json",
        response_schema={
            "type": "object",
            "properties": {
                "category": {"type": "string", "enum": ["Billing", "Technical", "Account", "General"]},
                "urgency": {"type": "integer", "minimum": 1, "maximum": 5},
                "summary": {"type": "string"}
            },
            "required": ["category", "urgency", "summary"]
        }
    )
)

response = model.generate_content(
    "Process this support ticket: 'System has been down for 4 hours, all our production servers are offline, losing $50k/hour.'"
)

data = json.loads(response.text)
print(data)
# {'category': 'Technical', 'urgency': 5, 'summary': 'Production servers offline for 4 hours causing significant revenue loss'}

有了 schema 的强制约束，我再也没收到过格式错误的响应。这绝对是我整个流程稳定性的一大转折点。

第四步：为响应式应用开启流式输出

在我的处理流程中，起草回复的部分往往输出较长，我希望用户能实时看到草稿生成的过程。Flash 支持流式输出，而且用起来非常简单：

model = genai.GenerativeModel('gemini-3.5-flash')

response = model.generate_content(
    "Draft a professional but empathetic response to this customer: "
    "They've been double-charged and can't find the refund option. "
    "Our refund process is in Settings > Billing > Payment History > Request Refund. "
    "Refunds take 3-5 business days.",
    stream=True
)

for chunk in response:
    print(chunk.text, end='', flush=True)

第一个 token 返回得极快——大概 150 毫秒左右。流式输出的感觉非常干脆自然，比起云端 API，它的响应速度更接近你本地跑的模型。

第五步：多模态输入

我的客服工单里有时会包含报错截图。Flash 能处理多模态输入，所以我写了个函数，把图片和文本放在一起处理：

from PIL import Image
import io

def process_ticket_with_image(text, image_path):
    img = Image.open(image_path)
    
    model = genai.GenerativeModel('gemini-3.5-flash')
    
    response = model.generate_content([
        "Analyze this support ticket and attached screenshot. "
        "Identify the error code shown and suggest a fix.",
        text,
        img
    ])
    
    return response.text

# 使用方法
result = process_ticket_with_image(
    "Getting this error when trying to log in",
    "error_screenshot.png"
)
print(result)

它从截图里读取报错弹窗的能力让我挺惊讶的。它甚至从一张模糊的浏览器截图里准确提取出了“ERR_SSL_PROTOCOL_ERROR”，并建议清除 SSL 缓存。不过话说回来，它处理截图里的手写笔记就比较吃力了——这点要注意。

第六步：工具使用与函数调用

对我的处理流程来说，真正的杀手锏是函数调用。我希望模型在处理工单时，能自己去查客户信息和系统状态：

def get_customer_status(customer_id: str) -> dict:
    """Get customer account status."""
    # 实际情况中，这里会查询你的数据库
    return {"id": customer_id, "plan": "Pro", "status": "active", "open_tickets": 3}

def check_system_status(system: str) -> dict:
    """Check if a system is currently operational."""
    return {"system": system, "status": "operational", "uptime": "99.9%"}

model = genai.GenerativeModel(
    'gemini-3.5-flash',
    tools=[get_customer_status, check_system_status]
)

response = model.generate_content(
    "Customer C-12345 is reporting they can't access the dashboard. "
    "Check their account status and the dashboard system status before responding."
)

# 模型会返回一个函数调用，而不是文本
# 你执行该函数，然后把结果传回给模型

我折腾了好一阵子才把它调顺。我犯的第一个错就是没给函数写清晰的 docstring——模型得靠这些描述才能明白什么时候该调用、怎么调用每个函数。加上详细的 docstring 和明确的参数类型后，函数调用就变得非常稳定了。

实用技巧与诚实的局限性

把 Flash 放到生产环境跑了几周后，这是我总结出来的经验：

Flash 擅长的地方：

大批量、直白的任务，比如分类、信息提取和简单的草稿撰写
对延迟敏感的场景（实时功能、聊天界面）
对成本敏感的应用，每天要调用几千次 API 的那种
涉及截图、图表或扫描文档的多模态任务

Flash 吃力的地方：

复杂的多步推理。我试过让它帮我排查异步代码里一个棘手的竞态条件，它信誓旦旦给出的修复方案根本行不通。遇到这种问题，我还是会用更重的大模型。
包含细微细节的超长上下文。它确实能处理官方标称的上下文窗口，但我发现它偶尔会漏掉藏在长提示词深处的小细节。
高度创意或微妙的写作。起草客服回复？很棒。用特定品牌调性写营销文案？表现就不太稳定了。

我最大的建议： 把 Flash 当作你的主力，只有在真正需要的时候才升级用更重的大模型。我的流程现在 90% 的工单都用 Flash 处理，只有那 10% 真正复杂的工单才会路由给更强大的模型。我的 API 成本降了 80%，而输出质量没有任何肉眼可见的下降。

一个避坑提醒： API 里的模型名是 gemini-3.5-flash，不是 gemini-3-flash，也不是 gemini-flash-3.5。第一天我就因为写错名字白白浪费了二十分钟。拿不准的话多查查文档——Google 的命名规则并不总是那么直观。

Flash 不会在所有任务上都取代大模型，但在日常大量的 API 工作中——分类、提取、摘要和结构化生成——它已经成了我的默认选择。速度和成本上的节省是实打实的，而且质量也足够好，只有在遇到真正棘手的难题时，你才会察觉到它和重模型之间的差距。