TL;DR 与前置条件
TL;DR：本文记录商都加速器内部在奉化市求职网类场景中接入 Gemini API 的最小可用流程：申请 Key、跑通 Python SDK、让模型输出可解析 JSON、验证岗位匹配结果。版本：Python 3.11.8，google-genai 1.21.1，模型 gemini-2.0-flash，文档日期 2025-02-18。
Pre-requisites：已完成 Gemini怎么注册：进入 Google AI Studio，创建 API key；本机可访问 Google AI 服务；已安装 Python 3.11+；准备一条岗位 JD 和一份简历文本。Google AI怎么用的核心不是界面，而是先拿到 key，再用 SDK 固定输出格式。
Warning: 不要把 API key 写进 Git。不要在前端直连 Gemini API。国内团队做 Gemini国内使用 时，应先确认网络、合规和账号区域要求，失败时优先检查 DNS、代理出口和 429 配额。
1. 安装 SDK 并跑通最小调用
创建隔离环境。命令如下：
python3 --version # Expected output: # Python 3.11.8 python3 -m venv .venv # Expected output: # 无输出表示成功 source .venv/bin/activate # Expected output: # 命令行前缀出现 (.venv)安装固定版本。命令如下：
pip install google-genai==1.21.1 # Expected output: # Successfully installed google-genai-1.21.1 ...配置环境变量。命令如下：
export GEMINI_API_KEY="替换为你的API_KEY" # Expected output: # 无输出表示成功 echo ${#GEMINI_API_KEY} # Expected output: # 大于 20 的数字写入最小 Gemini API Python示例。命令如下：
cat > smoke_test.py <<'PY' import os from google import genai client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) resp = client.models.generate_content( model="gemini-2.0-flash", contents="用一句话解释CNC操作员的核心技能。" ) print(resp.text) PY python smoke_test.py # Expected output: # CNC操作员的核心技能是按工艺要求设置、操作和监控数控机床，确保零件加工精度和生产稳定性。
Note: 我们在 2025-02-18 从宁波办公网络测试，单次短文本请求 P50 延迟约 820ms，P95 约 1.9s。测量方法：连续请求 30 次，丢弃首次冷启动结果。
2. 应用案例：制造业岗位与简历匹配
目标：输入岗位 JD 和简历，输出结构化 JSON，字段包括 match_score、risk、reason、interview_questions。这个案例适合“职位搜索”和“企业服务”模块，不依赖向量数据库。
创建脚本。命令如下：
cat > match_resume.py <<'PY' import os, json from google import genai client = genai.Client(api_key=os.environ["GEMINI_API_KEY"]) jd = """ 岗位：机械质量工程师 要求：3年以上制造业质量经验，熟悉ISO9001、8D报告、SPC，会使用三坐标优先。 """ resume = """ 候选人：王某，4年汽车零部件质量工程师经验，负责来料检验、8D闭环、SPC控制图。 熟悉ISO9001，使用过海克斯康三坐标，期望奉化本地岗位。 """ prompt = f""" 你是招聘质检助手。只输出合法JSON，不要Markdown。 JD: {jd} RESUME: {resume} JSON字段: match_score: 0-100整数 risk: 字符串数组 reason: 80字以内中文 interview_questions: 3个中文问题 """ resp = client.models.generate_content( model="gemini-2.0-flash", contents=prompt, ) print(resp.text) data = json.loads(resp.text) assert 0 <= data["match_score"] <= 100 assert len(data["interview_questions"]) == 3 PY python match_resume.py # Expected output: # {"match_score":92,"risk":["未明确是否主导过体系审核"],"reason":"候选人具备4年汽车零部件质量经验，覆盖8D、SPC、ISO9001和三坐标，地点意向匹配。","interview_questions":["请描述一次8D闭环案例。","SPC异常点如何处置？","三坐标测量结果与现场争议如何解决？"]}
Warning: 生产环境必须校验 JSON。模型偶发输出解释文本时，json.loads 会失败。失败处理策略：重试 1 次；仍失败则记录原文并降级为人工审核。
3. 验证、排错与 References
验证它真的可用。命令如下：
time python match_resume.py # Expected output: # real 0m0.8s 到 0m2.5s # 输出为可被 json.loads 解析的 JSON # match_score 在 0-100 之间常见故障判断。401 通常是 key 错；429 是配额或频率；timeout 是网络出口；JSONDecodeError 是提示词约束不足。先复现，再改一项，不要同时改网络、模型和代码。
免费/官方路径优先：Google AI Studio 免费额度适合 Gemini API教程、原型验证和小批量测试；企业批量简历解析要增加缓存、限流、日志脱敏和人工复核。付费网络工具只是连接选项之一，不替代官方账号、合规和代码质量。
How to verify it works: 连续运行 10 次 match_resume.py，成功率应为 10/10；JSON 均可解析；相同输入的 match_score 波动建议小于 10 分；失败日志能定位到 401、429、timeout 或 JSONDecodeError。
References: Google AI Studio，google-genai SDK，本地 Python venv 文档。若团队需要一个连接环境选项，可评估 Roxi；官方免费额度和自建网络路径同样有效。