[智能体-2]：openAI API详解

下面从核心概念→认证→接口→参数→流式→函数调用→计费→国内兼容→最佳实践把 OpenAI API 讲透。一、OpenAI API 是什么OpenAI API 一套标准化的 RESTful 大模型调用协议基于 HTTP/JSON提供文本对话GPT-4o/3.5文生图 / 图编辑DALL・E 3语音转文字 / 文字转语音Whisper/TTS向量嵌入Embeddings工具调用 / 函数调用Function Calling微调、文件、向量库、批量任务等核心价值不仅是 OpenAI 自己用国内 99% 大模型千问、DeepSeek、星火、Kimi都兼容此协议你写一套代码换个base_urlapi_key就能切换模型。二、基础架构与认证1. 基础地址Base URLOpenAI 官方https://api.openai.com/v1通义千问https://dashscope.aliyuncs.com/compatible-mode/v1DeepSeekhttps://api.deepseek.com讯飞星火https://spark-api-open.xf-yun.com/v1Kimihttps://api.moonshot.cn/v12. 认证方式必懂所有请求必须带Bearer TokenAPI KeyhttpAuthorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Content-Type: application/jsonKey 以sk-开头仅生成时可见一次必须保存。绝对不能硬编码在前端 / Git / 客户端只能存在环境变量或密钥管理服务OpenAI。3. Python 官方 SDK最常用bash运行pip install openaipython运行from openai import OpenAI import os # 初始化客户端切换模型只改这两行 clientOpenAI( api_keyos.getenv(OPENAI_API_KEY), # 或 QWEN_API_KEY/DEEPSEEK_API_KEY base_urlos.getenv(OPENAI_BASE_URL) # 国内模型替换成对应地址 )三、核心接口Chat Completions对话最常用接口对应/v1/chat/completions支持多轮对话、流式输出、函数调用。1. 极简调用非流式python运行responseclient.chat.completions.create( modelgpt-4o, # 国内模型如 qwen-turbo、deepseek-chat messages[ {role: system, content: 你是 helpful 助手}, {role: user, content: 什么是 OpenAI API} ], temperature0.7, max_tokens1024 ) print(response.choices[0].message.content)2. 请求参数全解高频表格参数类型说明常用值modelstring模型 ID必填gpt-4o、gpt-3.5-turbo、qwen-turbomessagesarray对话历史必填role: system/user/assistanttemperaturefloat随机性0~20 严谨1 平衡2 发散max_tokensint最大输出长度1024、4096看模型上限top_pfloat核采样0~10.9常用frequency_penaltyfloat重复惩罚-2~20.1减少重复presence_penaltyfloat主题新鲜度-2~20streambool流式输出逐字返回False/Truestoparray停止词[\n\n]logit_biasdict强制 / 禁止 某些词{100257: -100}3. 响应结构json{ id: chatcmpl-xxx, object: chat.completion, created: 1758423456, model: gpt-4o, choices: [ { index: 0, message: { role: assistant, content: OpenAI API 是... }, finish_reason: stop } ], usage: { prompt_tokens: 15, completion_tokens: 32, total_tokens: 47 } }usage计费核心输入 / 输出 token 分开算钱。四、流式输出Streaming必学解决 “等待半天不出结果”逐字返回SSE 协议。python运行streamclient.chat.completions.create( modelgpt-4o, messages[{role: user, content: 讲个长故事}], streamTrue # 开启流式 ) for chunk in stream: if chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end, flushTrue)五、函数调用Function Calling高级让模型自动调用你的工具 / 接口如查天气、数据库、API。python运行# 1. 定义工具 tools [ { type: function, function: { name: get_weather, description: 获取指定城市天气, parameters: { type: object, properties: {city: {type: string, description: 城市名}}, required: [city] } } } ] # 2. 调用模型让它决定是否调用工具 responseclient.chat.completions.create( modelgpt-4o, messages[{role: user, content: 北京今天天气}], toolstools, tool_choiceauto ) # 3. 执行工具并返回结果 tool_callresponse.choices[0].message.tool_calls[0] if tool_call.function.name get_weather: import json argsjson.loads(tool_call.function.arguments) weatherget_weather(args[city]) # 你的函数 # 把结果发回模型生成自然语言回答六、其他常用接口1. 嵌入向量Embeddings用于检索、RAG、语义匹配python运行responseclient.embeddings.create( modeltext-embedding-3-small, input[OpenAI API 教程, 大模型接口] ) vectorresponse.data[0].embedding # 1536 维向量2. 文生图DALL・E 3python运行responseclient.images.generate( modeldall-e-3, prompt一只戴墨镜的猫赛博朋克风格, size1024x1024, n1 ) print(response.data[0].url)3. 语音转文字Whisperpython运行audio_fileopen(speech.mp3, rb) transcriptionclient.audio.transcriptions.create( modelwhisper-1, fileaudio_file ) print(transcription.text)七、计费Token 计算规则按输入 TokenPrompt 输出 TokenCompletion计费。估算1 Token ≈ 4 个英文字符 ≈ 1 个汉字。示例GPT-4o输入 $5/1M Token输出 $15/1M Token通义千问免费额度 按量计费更便宜八、国内大模型兼容重点1. 兼容原理国内厂商完全复用 OpenAI 的请求 / 响应格式仅需替换base_url换成厂商兼容地址api_key换成厂商 Keymodel换成厂商模型名如qwen-turbo、deepseek-chat2. 一键切换代码示例python运行# .env 文件 # QWEN_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 # QWEN_API_KEYsk-xxx # DEEPSEEK_BASE_URLhttps://api.deepseek.com # DEEPSEEK_API_KEYsk-yyy import os from openai import OpenAI def get_client(vendorqwen): return OpenAI( api_keyos.getenv(f{vendor.upper()}_API_KEY), base_urlos.getenv(f{vendor.upper()}_BASE_URL) ) # 用千问 clientget_client(qwen) # 用 DeepSeek clientget_client(deepseek)九、最佳实践避坑Key 安全永远用环境变量不要硬编码 / 上传 GitOpenAI。参数调优写代码 / 严谨任务temperature0创意写作temperature0.9~1.2流式优先用户端交互必须开 stream体验大幅提升。错误处理捕获APIError、RateLimitError、Timeout。多模型兼容基于 OpenAI 协议开发无缝切换国内模型。十、一句话总结OpenAI API 大模型的 “通用语言”官方用它国内千问 / DeepSeek / 星火 / Kimi 都兼容一套代码换base_urlapi_key即可切换模型掌握 Chat CompletionsStreamFunction Calling就能搞定 90% 应用场景。