1. 从“调不通”到“用得好”LLM API 实战入门最近在社区和项目里看到不少朋友在尝试调用各类大语言模型LLM的API时总会遇到一些“拦路虎”。比如兴致勃勃地写了几行代码结果返回一个冷冰冰的400 Bad Request错误信息是invalid prompt: your prompt was flagged as potentially violating our usage policy瞬间一头雾水。又或者好不容易请求成功了但模型返回的内容要么答非所问要么啰嗦冗长完全不是自己想要的效果。这背后其实涉及两个核心环节API调用和Prompt工程。很多人把它们分开看前者是“技术活”后者是“玄学”。但在我看来这两者密不可分共同决定了你能否高效、稳定地从LLM中“榨取”出有价值的信息。这篇文章我想从一个一线开发者的角度抛开那些高大上的概念直接聊聊怎么把LLM API用起来以及如何通过设计Prompt提示词来真正解决问题。无论你是想在自己的应用里集成智能对话、内容生成还是做数据分析、代码辅助理解这些基础都是第一步。我们会从最实际的HTTP请求开始一步步拆解参数然后深入到Prompt设计的核心技巧最后再谈谈如何应对那些常见的错误和性能瓶颈。目标很简单让你看完就能动手减少踩坑。2. 理解LLM API不止是发送一个请求在开始写代码之前我们必须先搞清楚LLM API到底是什么以及它和传统的Web API比如获取天气、支付接口有什么本质不同。这决定了我们的使用方式。2.1 LLM API的核心一个“文本续写”服务你可以把主流的LLM API如OpenAI的Chat Completions、Anthropic的Messages、DeepSeek的Chat Completions等理解为一个超级强大的“文本续写”黑盒。你给它一段文本即Prompt它基于海量训练数据预测并生成最可能接在这段文本后面的内容。因此API调用的核心就是精心构造这段“上文”Prompt并告诉模型你希望它如何续写。这与查询数据库API输入条件返回确定结果或计算API输入公式返回精确数值有根本区别。LLM的响应是概率性和创造性的没有唯一“正确”答案只有“更合适”或“更符合要求”的答案。这个认知是后续所有工作的基础。2.2 关键参数详解控制输出的“旋钮”调用一个Chat Completion类型的API通常需要关注以下几个核心参数。理解它们你就掌握了控制模型输出的主动权。1.model选择引擎这是指定使用哪个模型比如gpt-4o、claude-3-5-sonnet、deepseek-v4-flash等。不同模型在能力、速度、成本上差异巨大。能力更大、更新的模型通常理解力和创造力更强能处理更复杂的任务。速度与成本更小的模型如deepseek-v4-flash响应更快单价更低适合对实时性要求高或简单任务。deepseek-v4-pro则能力更强适合复杂推理。选择建议从轻量级模型开始测试你的Prompt和流程验证通过后再用更强模型做生产或关键任务。永远关注API文档中关于模型可用性的说明像The supported api model names are deepseek-v4-pro or deepseek-v4-flash这样的错误就是因为传入了不支持的模型名。2.messages对话的历史与结构这是Prompt的载体是一个消息对象的数组。每个对象通常包含role和content。role一般为system,user,assistant。system设定模型的角色、行为准则和整体目标。这是塑造模型“人设”的关键应简洁、明确。例如“你是一个专业的代码助手用中文回答代码部分用markdown代码块包裹。”user代表用户的输入即你的问题或指令。assistant代表模型之前的回复。在多轮对话中你需要将历史对话按顺序放入messages数组模型才能理解上下文。content对应角色的文本内容。 一个典型的结构如下[ {role: system, content: 你是一个翻译助手将用户输入的中文翻译成英文。}, {role: user, content: 今天的天气真好。} ]3.max_tokens控制生成长度这限制了模型本次生成内容的最大token数可以粗略理解为字数。必须设置且不能超过模型上下文窗口的上限。为什么重要防止模型生成过于冗长的内容消耗不必要的token费用和时间。如何估算你的输入Prompt本身也占token。你需要预留足够的max_tokens给输出。如果设置太小回复会被截断出现[输出被截断]的情况。如果设置超过模型上限会直接报错例如api error: 400 this models maximum context length is 1048565 tokens. however, your messages resulted in 1200000 tokens。经验值对于简短问答512或1024通常足够。对于长文生成可能需要2048或4096。务必查阅对应模型的上下文长度文档。4.temperature和top_p控制随机性这两个参数影响生成的“创造性”或“确定性”。temperature温度0.0~2.0值越低输出越确定、可重复倾向于选择最高概率的词值越高输出越随机、有创意。对于代码生成、事实问答建议较低0.1~0.3对于创意写作、头脑风暴可以调高0.7~1.0。top_p核采样0.0~1.0另一种控制随机性的方式。它从概率质量最高的token中采样直到累积概率超过top_p。通常与temperature二选一使用调整一个即可。默认值如0.7或1.0适用于大多数情况。5.stream流式传输设置为true时API会以Server-Sent Events (SSE) 的形式流式返回token即边生成边返回。这对于需要实时显示生成内容的应用如聊天界面至关重要能极大提升用户体验避免长时间等待。3. 实战从零完成一次API调用理论说再多不如动手试一次。我们以DeepSeek API为例展示一个完整的调用流程。选择DeepSeek是因为它目前提供了极具竞争力的免费额度非常适合学习和原型开发。3.1 环境准备与认证首先你需要一个API密钥。前往DeepSeek平台注册并创建API Key。接下来我们使用Python的requests库进行调用这是最通用、最直观的方式。# 安装必要的库 pip install requestsimport requests import json # 配置 API_KEY 你的-DeepSeek-API-KEY # 请替换为你的真实密钥 API_URL https://api.deepseek.com/chat/completions headers { Authorization: fBearer {API_KEY}, Content-Type: application/json }3.2 构造请求与处理响应现在我们构造一个简单的翻译请求。def call_deepseek_api(prompt_text, system_promptNone): 调用DeepSeek Chat Completions API messages [] if system_prompt: messages.append({role: system, content: system_prompt}) messages.append({role: user, content: prompt_text}) data { model: deepseek-v4-flash, # 使用轻量快速的模型 messages: messages, max_tokens: 512, temperature: 0.3, stream: False # 首次测试先关闭流式 } try: response requests.post(API_URL, headersheaders, jsondata, timeout30) response.raise_for_status() # 如果状态码不是200抛出HTTPError异常 result response.json() # 提取助手的回复 reply result[choices][0][message][content] return reply except requests.exceptions.HTTPError as http_err: # 重点处理HTTP错误如400 429等 error_detail response.json().get(error, {}).get(message, Unknown error) print(fHTTP错误 {response.status_code}: {error_detail}) return None except requests.exceptions.RequestException as req_err: print(f请求异常: {req_err}) return None except (KeyError, IndexError, json.JSONDecodeError) as parse_err: print(f解析响应失败: {parse_err}) print(f原始响应: {response.text}) return None # 测试调用 system_prompt 你是一个翻译助手将用户输入的中文准确、流畅地翻译成英文。 user_prompt 人工智能正在深刻改变每一个行业。 translation call_deepseek_api(user_prompt, system_prompt) if translation: print(翻译结果, translation)这段代码包含了几个关键实践结构化消息明确区分了system和user角色。错误处理重点捕获了HTTP错误如400 429限速并尝试从响应体中提取可读的错误信息这对于调试至关重要。超时设置网络请求必须设置超时避免程序无限期挂起。响应解析安全地访问嵌套的JSON结构避免因响应格式意外变化导致程序崩溃。3.3 处理流式响应对于需要实时显示的场景我们需要处理流式响应。这稍微复杂一点但能带来质的体验提升。def call_deepseek_api_stream(prompt_text, system_promptNone): messages [] if system_prompt: messages.append({role: system, content: system_prompt}) messages.append({role: user, content: prompt_text}) data { model: deepseek-v4-flash, messages: messages, max_tokens: 1024, temperature: 0.7, stream: True # 开启流式 } try: response requests.post(API_URL, headersheaders, jsondata, timeout60, streamTrue) response.raise_for_status() full_content print(模型回复流式: , end, flushTrue) for line in response.iter_lines(): if line: line_decoded line.decode(utf-8) if line_decoded.startswith(data: ): data_str line_decoded[6:] # 去掉 data: 前缀 if data_str [DONE]: break try: chunk json.loads(data_str) delta chunk[choices][0][delta] # 流式响应中内容在 delta.content 里 if content in delta: content_piece delta[content] print(content_piece, end, flushTrue) full_content content_piece except json.JSONDecodeError: continue print() # 换行 return full_content except requests.exceptions.RequestException as e: print(f流式请求失败: {e}) return None # 测试流式调用 stream_result call_deepseek_api_stream(请用一段话描述秋天的景色。)流式处理的核心是设置streamTrue和streamTrue参数。使用response.iter_lines()逐行读取服务器发送的事件流。每一行数据以data:开头有效数据是JSON结束标志是data: [DONE]。从choices[0].delta.content中获取当前生成的文本片段并实时拼接和显示。4. Prompt工程从“有效”到“高效”API调通只是第一步让模型产出符合预期的内容才是真正的挑战。这就是Prompt工程的用武之地。它不是魔法而是一种结构化的沟通技巧。4.1 核心原则清晰、具体、提供上下文一个糟糕的Prompt“写点关于机器学习的东西。” 一个优秀的Prompt“你是一位科技博客作者。请为初学者写一篇约500字的博客文章介绍机器学习中的‘监督学习’概念。要求定义清晰并提供一个现实生活中的类比比如教孩子识别水果。文章风格应通俗易懂充满热情。”两者的区别在于后者遵循了以下原则角色Role “科技博客作者” – 设定了语气和视角。任务Task “写一篇博客文章” – 明确输出格式。受众Audience “初学者” – 决定了内容的深度和术语使用。要求Requirements “约500字”、“定义清晰”、“提供一个现实生活中的类比”、“风格通俗易懂、充满热情” – 给出了具体、可衡量的约束和期望。上下文Context “机器学习中的‘监督学习’概念” – 限定了主题范围。4.2 结构化Prompt模板对于复杂任务使用模板能确保一致性。一个通用的模板可以如下# 角色 [明确模型扮演的角色如资深软件架构师、专业编辑、挑剔的客户等] # 背景/目标 [简要说明任务的背景和最终要达成的目标] # 任务 [清晰、分步骤地描述需要模型完成的具体任务] # 输出格式要求 [指定输出的格式如Markdown报告、JSON对象、带注释的代码、项目大纲列表等] # 约束与注意事项 [列出所有限制条件如必须使用中文、不能包含特定信息、必须引用某个概念、字数限制、风格要求等] # 输入/示例可选 [提供输入数据的示例或给出一个输入输出的范例供模型参考]实战示例代码评审助手# 角色 你是一位经验丰富的Python高级开发工程师擅长代码安全、性能和可读性评审。 # 背景/目标 我将给你一段Python函数代码。请对其进行全面的代码评审。 # 任务 1. 首先用一句话总结这个函数的功能。 2. 然后按以下类别列出发现的问题和改进建议 - 安全性如注入风险、硬编码密钥 - 性能如时间复杂度、不必要的循环 - 可读性与风格PEP 8遵守情况、命名、注释 - 健壮性异常处理、边界条件 3. 最后提供一个重构后的优化版本代码。 # 输出格式要求 请使用Markdown格式输出包含“功能总结”、“问题与建议”、“优化后代码”三个二级标题。 # 约束与注意事项 - 评审意见必须具体指出代码行号或片段。 - 优化后的代码必须保持原函数接口不变。 - 所有建议需以中文给出。 # 输入 python def process_data(user_input, config_fileconfig.json): import json with open(config_file) as f: config json.load(f) sql fSELECT * FROM users WHERE name {user_input} # ... 执行sql的代码省略使用这样的结构化Prompt模型返回的结果会非常有条理直接满足后续自动化处理或人工阅读的需求。 ### 4.3 进阶技巧思维链与少样本学习 对于逻辑推理或复杂任务可以引导模型“一步步思考”。 * **思维链Chain-of-Thought**在Prompt中明确要求模型展示推理过程。 * **Prompt**“小明有5个苹果他给了小红2个又买了3个橙子。请问他现在有多少个水果请一步步思考。” * **模型输出**“首先计算苹果数量5 - 2 3个苹果。然后计算水果总数苹果3个 橙子3个 6个水果。所以他现在有6个水果。” 这种方式不仅能让答案更可靠也便于我们检查模型的逻辑是否正确。 * **少样本学习Few-Shot Learning**在Prompt中提供几个输入输出的例子让模型模仿。 将情感分类为积极、消极或中性。 示例1 输入这部电影太精彩了我看了三遍 输出积极 示例2 输入服务很慢食物也凉了。 输出消极 示例3 输入包裹已于下午送达。 输出中性 现在请分类 输入这个新功能用起来还行没什么特别的。 输出 通过提供示例模型能快速理解你想要的输出格式和分类标准特别适用于格式固定或定义独特的任务。 ## 5. 避坑指南常见错误与优化策略 在实际调用中你一定会遇到各种错误和不如预期的结果。以下是典型问题的排查思路和解决方案。 ### 5.1 错误码解析与处理 * **400 Bad Request**这是最常见的错误意味着请求格式有问题。 * **invalid prompt: your prompt was flagged as potentially violating our usage policy**: 你的Prompt内容触发了内容安全策略。**不要尝试绕过**。应仔细检查Prompt中是否包含暴力、仇恨、违法或极端敏感内容并重新措辞专注于解决技术或合规问题。 * **‘type’ must be in [“enabled”, “disabled”, “auto”]**: 这表明你传入了一个API不支持的参数值。仔细核对API文档检查是否有参数名拼写错误或值不在允许范围内。 * **this model‘s maximum context length is ...**: 上下文超长。你需要减少 messages 中历史对话的总长度或者选择上下文窗口更大的模型。对于长文档处理可以考虑先进行摘要或分段。 * **通用排查**首先使用 print(json.dumps(data, indent2)) 打印出你发送的完整请求体与官方API文档示例逐字段对比。99%的400错误源于字段名错误、嵌套结构错误或值类型错误比如该传字符串的传了数字。 * **429 Too Many Requests**请求速率超限。所有API都有速率限制RPM-每分钟请求数 TPM-每分钟token数。 * **解决方案**实现请求重试逻辑并加入指数退避延迟。例如遇到429时等待 (2 ** retry_count) 秒后再重试并设置最大重试次数。 python import time def call_api_with_retry(data, max_retries3): for attempt in range(max_retries): try: response requests.post(API_URL, headersheaders, jsondata, timeout30) if response.status_code 429: wait_time 2 ** attempt # 指数退避 print(f速率限制等待 {wait_time} 秒后重试...) time.sleep(wait_time) continue response.raise_for_status() return response.json() except requests.exceptions.RequestException: if attempt max_retries - 1: raise time.sleep(1) return None * **5xx Server Error**服务器内部错误。通常是API服务提供方的问题。 * **解决方案**记录错误信息进行重试。如果持续发生需要查看服务状态页或联系支持。错误信息如 api error: connection closed mid-response. the response above may be incomplete 就属于此类可能是网络波动或服务端中断重试通常能解决。 ### 5.2 性能与成本优化 * **缓存重复请求**如果你的应用中有大量相似或重复的Prompt例如标准化的系统指令不同的用户查询可以考虑缓存模型的响应结果。但要注意对于 temperature 0 的请求输出可能不同缓存需谨慎。 * **精简Prompt**Prompt中的每一个token都计费且消耗上下文窗口。删除不必要的废话使用简洁明了的指令。将固定的系统指令存储在变量中复用而不是每次请求都重新拼接。 * **异步与非阻塞调用**对于需要批量处理或前端交互的应用使用异步请求如 aiohttp 库可以避免阻塞主线程提升吞吐量和响应速度。 * **合理设置 max_tokens**根据任务实际需要预估输出长度不要盲目设置一个很大的值。你可以先进行几次测试观察典型回复的长度然后设置一个略高于平均值的 max_tokens。 * **模型选型**如前所述在非关键路径或简单任务上使用更小、更快的模型如 deepseek-v4-flash能显著降低成本并提高响应速度。 ### 5.3 Prompt的迭代与评估 设计Prompt不是一个一蹴而就的过程而是一个“编写-测试-评估-修改”的循环。 1. **定义成功标准**在开始前就想清楚什么样的输出算合格是格式完全正确是包含了所有关键信息还是风格符合要求 2. **创建测试集**准备一组具有代表性的输入用例包括简单、复杂和边界情况。 3. **批量测试与评估**编写脚本用你的Prompt批量处理测试集将输出保存下来。 4. **人工分析**仔细阅读输出找出问题模式。是格式错误是遗漏信息还是理解了偏差 5. **迭代Prompt**根据分析结果有针对性地修改Prompt。可能是增加约束、提供示例、改变角色描述或拆分任务步骤。 6. **自动化评估可选**对于某些任务可以用规则或另一个LLM调用这被称为“LLM-as-a-Judge”来对输出进行评分加速迭代循环。 记住Prompt工程的目标是**减少歧义对齐意图**。你和模型之间的“沟通损耗”越小结果就越理想。 ## 6. 超越基础构建稳健的应用 当你掌握了单次调用后下一步就是思考如何将其融入一个真正的、稳健的应用中。 ### 6.1 设计健壮的客户端 一个生产级的API客户端不应只是简单的函数调用。它应该包含 * **配置管理**将API密钥、Base URL、默认模型等配置外置如环境变量、配置文件避免硬编码。 * **统一的错误处理与日志**对所有可能的异常网络、HTTP、解析、业务逻辑进行捕获、分类和记录并给出用户友好的提示或执行降级策略。 * **重试与退避机制**如前所述针对429、5xx等可重试错误实现策略。 * **连接池与超时管理**对于高频调用使用 requests.Session 或类似机制管理HTTP连接并合理设置连接、读取超时。 * **监控与度量**记录每次调用的延迟、消耗token数、成功率便于后续性能分析和成本核算。 ### 6.2 处理长上下文与复杂任务 对于超出模型上下文窗口的长文本或者需要多步骤推理的复杂任务单次API调用无法解决。 * **“Map-Reduce”策略**将长文档分割成有重叠的片段Chunk分别发送给模型处理Map最后再将所有结果汇总Reduce。例如总结一本电子书可以先分章节总结再对章节摘要进行总结。 * **使用Agent框架**对于需要工具调用如搜索、计算、查数据库、多轮规划和复杂决策的任务可以考虑使用LangChain、LangGraph等框架。它们提供了构建“智能体”的范式将LLM作为核心控制器协调一系列工具和步骤来完成目标。例如一个数据分析Agent可以接受自然语言问题然后自动编写SQL查询、执行、并对结果进行解释。 * **函数调用Function Calling**这是让LLM与外部工具交互的官方推荐方式。你可以在请求中定义一系列工具函数的schema模型在认为需要时会返回一个包含具体函数调用参数的JSON。你的代码再根据这个JSON去真正执行函数并将结果返回给模型进行下一步。这极大地增强了LLM的实操能力。 从简单的API调用到设计精良的Prompt再到构建稳健的应用集成这条路径上的每一步都需要清晰的思考和不断的实践。最关键的是开始动手从一个具体的、小规模的任务开始调用一次API分析返回结果调整你的Prompt再观察变化。这个快速反馈循环是掌握LLM应用开发最有效的方法。 LLM API调用与Prompt工程实战：从入门到高效应用
1. 从“调不通”到“用得好”LLM API 实战入门最近在社区和项目里看到不少朋友在尝试调用各类大语言模型LLM的API时总会遇到一些“拦路虎”。比如兴致勃勃地写了几行代码结果返回一个冷冰冰的400 Bad Request错误信息是invalid prompt: your prompt was flagged as potentially violating our usage policy瞬间一头雾水。又或者好不容易请求成功了但模型返回的内容要么答非所问要么啰嗦冗长完全不是自己想要的效果。这背后其实涉及两个核心环节API调用和Prompt工程。很多人把它们分开看前者是“技术活”后者是“玄学”。但在我看来这两者密不可分共同决定了你能否高效、稳定地从LLM中“榨取”出有价值的信息。这篇文章我想从一个一线开发者的角度抛开那些高大上的概念直接聊聊怎么把LLM API用起来以及如何通过设计Prompt提示词来真正解决问题。无论你是想在自己的应用里集成智能对话、内容生成还是做数据分析、代码辅助理解这些基础都是第一步。我们会从最实际的HTTP请求开始一步步拆解参数然后深入到Prompt设计的核心技巧最后再谈谈如何应对那些常见的错误和性能瓶颈。目标很简单让你看完就能动手减少踩坑。2. 理解LLM API不止是发送一个请求在开始写代码之前我们必须先搞清楚LLM API到底是什么以及它和传统的Web API比如获取天气、支付接口有什么本质不同。这决定了我们的使用方式。2.1 LLM API的核心一个“文本续写”服务你可以把主流的LLM API如OpenAI的Chat Completions、Anthropic的Messages、DeepSeek的Chat Completions等理解为一个超级强大的“文本续写”黑盒。你给它一段文本即Prompt它基于海量训练数据预测并生成最可能接在这段文本后面的内容。因此API调用的核心就是精心构造这段“上文”Prompt并告诉模型你希望它如何续写。这与查询数据库API输入条件返回确定结果或计算API输入公式返回精确数值有根本区别。LLM的响应是概率性和创造性的没有唯一“正确”答案只有“更合适”或“更符合要求”的答案。这个认知是后续所有工作的基础。2.2 关键参数详解控制输出的“旋钮”调用一个Chat Completion类型的API通常需要关注以下几个核心参数。理解它们你就掌握了控制模型输出的主动权。1.model选择引擎这是指定使用哪个模型比如gpt-4o、claude-3-5-sonnet、deepseek-v4-flash等。不同模型在能力、速度、成本上差异巨大。能力更大、更新的模型通常理解力和创造力更强能处理更复杂的任务。速度与成本更小的模型如deepseek-v4-flash响应更快单价更低适合对实时性要求高或简单任务。deepseek-v4-pro则能力更强适合复杂推理。选择建议从轻量级模型开始测试你的Prompt和流程验证通过后再用更强模型做生产或关键任务。永远关注API文档中关于模型可用性的说明像The supported api model names are deepseek-v4-pro or deepseek-v4-flash这样的错误就是因为传入了不支持的模型名。2.messages对话的历史与结构这是Prompt的载体是一个消息对象的数组。每个对象通常包含role和content。role一般为system,user,assistant。system设定模型的角色、行为准则和整体目标。这是塑造模型“人设”的关键应简洁、明确。例如“你是一个专业的代码助手用中文回答代码部分用markdown代码块包裹。”user代表用户的输入即你的问题或指令。assistant代表模型之前的回复。在多轮对话中你需要将历史对话按顺序放入messages数组模型才能理解上下文。content对应角色的文本内容。 一个典型的结构如下[ {role: system, content: 你是一个翻译助手将用户输入的中文翻译成英文。}, {role: user, content: 今天的天气真好。} ]3.max_tokens控制生成长度这限制了模型本次生成内容的最大token数可以粗略理解为字数。必须设置且不能超过模型上下文窗口的上限。为什么重要防止模型生成过于冗长的内容消耗不必要的token费用和时间。如何估算你的输入Prompt本身也占token。你需要预留足够的max_tokens给输出。如果设置太小回复会被截断出现[输出被截断]的情况。如果设置超过模型上限会直接报错例如api error: 400 this models maximum context length is 1048565 tokens. however, your messages resulted in 1200000 tokens。经验值对于简短问答512或1024通常足够。对于长文生成可能需要2048或4096。务必查阅对应模型的上下文长度文档。4.temperature和top_p控制随机性这两个参数影响生成的“创造性”或“确定性”。temperature温度0.0~2.0值越低输出越确定、可重复倾向于选择最高概率的词值越高输出越随机、有创意。对于代码生成、事实问答建议较低0.1~0.3对于创意写作、头脑风暴可以调高0.7~1.0。top_p核采样0.0~1.0另一种控制随机性的方式。它从概率质量最高的token中采样直到累积概率超过top_p。通常与temperature二选一使用调整一个即可。默认值如0.7或1.0适用于大多数情况。5.stream流式传输设置为true时API会以Server-Sent Events (SSE) 的形式流式返回token即边生成边返回。这对于需要实时显示生成内容的应用如聊天界面至关重要能极大提升用户体验避免长时间等待。3. 实战从零完成一次API调用理论说再多不如动手试一次。我们以DeepSeek API为例展示一个完整的调用流程。选择DeepSeek是因为它目前提供了极具竞争力的免费额度非常适合学习和原型开发。3.1 环境准备与认证首先你需要一个API密钥。前往DeepSeek平台注册并创建API Key。接下来我们使用Python的requests库进行调用这是最通用、最直观的方式。# 安装必要的库 pip install requestsimport requests import json # 配置 API_KEY 你的-DeepSeek-API-KEY # 请替换为你的真实密钥 API_URL https://api.deepseek.com/chat/completions headers { Authorization: fBearer {API_KEY}, Content-Type: application/json }3.2 构造请求与处理响应现在我们构造一个简单的翻译请求。def call_deepseek_api(prompt_text, system_promptNone): 调用DeepSeek Chat Completions API messages [] if system_prompt: messages.append({role: system, content: system_prompt}) messages.append({role: user, content: prompt_text}) data { model: deepseek-v4-flash, # 使用轻量快速的模型 messages: messages, max_tokens: 512, temperature: 0.3, stream: False # 首次测试先关闭流式 } try: response requests.post(API_URL, headersheaders, jsondata, timeout30) response.raise_for_status() # 如果状态码不是200抛出HTTPError异常 result response.json() # 提取助手的回复 reply result[choices][0][message][content] return reply except requests.exceptions.HTTPError as http_err: # 重点处理HTTP错误如400 429等 error_detail response.json().get(error, {}).get(message, Unknown error) print(fHTTP错误 {response.status_code}: {error_detail}) return None except requests.exceptions.RequestException as req_err: print(f请求异常: {req_err}) return None except (KeyError, IndexError, json.JSONDecodeError) as parse_err: print(f解析响应失败: {parse_err}) print(f原始响应: {response.text}) return None # 测试调用 system_prompt 你是一个翻译助手将用户输入的中文准确、流畅地翻译成英文。 user_prompt 人工智能正在深刻改变每一个行业。 translation call_deepseek_api(user_prompt, system_prompt) if translation: print(翻译结果, translation)这段代码包含了几个关键实践结构化消息明确区分了system和user角色。错误处理重点捕获了HTTP错误如400 429限速并尝试从响应体中提取可读的错误信息这对于调试至关重要。超时设置网络请求必须设置超时避免程序无限期挂起。响应解析安全地访问嵌套的JSON结构避免因响应格式意外变化导致程序崩溃。3.3 处理流式响应对于需要实时显示的场景我们需要处理流式响应。这稍微复杂一点但能带来质的体验提升。def call_deepseek_api_stream(prompt_text, system_promptNone): messages [] if system_prompt: messages.append({role: system, content: system_prompt}) messages.append({role: user, content: prompt_text}) data { model: deepseek-v4-flash, messages: messages, max_tokens: 1024, temperature: 0.7, stream: True # 开启流式 } try: response requests.post(API_URL, headersheaders, jsondata, timeout60, streamTrue) response.raise_for_status() full_content print(模型回复流式: , end, flushTrue) for line in response.iter_lines(): if line: line_decoded line.decode(utf-8) if line_decoded.startswith(data: ): data_str line_decoded[6:] # 去掉 data: 前缀 if data_str [DONE]: break try: chunk json.loads(data_str) delta chunk[choices][0][delta] # 流式响应中内容在 delta.content 里 if content in delta: content_piece delta[content] print(content_piece, end, flushTrue) full_content content_piece except json.JSONDecodeError: continue print() # 换行 return full_content except requests.exceptions.RequestException as e: print(f流式请求失败: {e}) return None # 测试流式调用 stream_result call_deepseek_api_stream(请用一段话描述秋天的景色。)流式处理的核心是设置streamTrue和streamTrue参数。使用response.iter_lines()逐行读取服务器发送的事件流。每一行数据以data:开头有效数据是JSON结束标志是data: [DONE]。从choices[0].delta.content中获取当前生成的文本片段并实时拼接和显示。4. Prompt工程从“有效”到“高效”API调通只是第一步让模型产出符合预期的内容才是真正的挑战。这就是Prompt工程的用武之地。它不是魔法而是一种结构化的沟通技巧。4.1 核心原则清晰、具体、提供上下文一个糟糕的Prompt“写点关于机器学习的东西。” 一个优秀的Prompt“你是一位科技博客作者。请为初学者写一篇约500字的博客文章介绍机器学习中的‘监督学习’概念。要求定义清晰并提供一个现实生活中的类比比如教孩子识别水果。文章风格应通俗易懂充满热情。”两者的区别在于后者遵循了以下原则角色Role “科技博客作者” – 设定了语气和视角。任务Task “写一篇博客文章” – 明确输出格式。受众Audience “初学者” – 决定了内容的深度和术语使用。要求Requirements “约500字”、“定义清晰”、“提供一个现实生活中的类比”、“风格通俗易懂、充满热情” – 给出了具体、可衡量的约束和期望。上下文Context “机器学习中的‘监督学习’概念” – 限定了主题范围。4.2 结构化Prompt模板对于复杂任务使用模板能确保一致性。一个通用的模板可以如下# 角色 [明确模型扮演的角色如资深软件架构师、专业编辑、挑剔的客户等] # 背景/目标 [简要说明任务的背景和最终要达成的目标] # 任务 [清晰、分步骤地描述需要模型完成的具体任务] # 输出格式要求 [指定输出的格式如Markdown报告、JSON对象、带注释的代码、项目大纲列表等] # 约束与注意事项 [列出所有限制条件如必须使用中文、不能包含特定信息、必须引用某个概念、字数限制、风格要求等] # 输入/示例可选 [提供输入数据的示例或给出一个输入输出的范例供模型参考]实战示例代码评审助手# 角色 你是一位经验丰富的Python高级开发工程师擅长代码安全、性能和可读性评审。 # 背景/目标 我将给你一段Python函数代码。请对其进行全面的代码评审。 # 任务 1. 首先用一句话总结这个函数的功能。 2. 然后按以下类别列出发现的问题和改进建议 - 安全性如注入风险、硬编码密钥 - 性能如时间复杂度、不必要的循环 - 可读性与风格PEP 8遵守情况、命名、注释 - 健壮性异常处理、边界条件 3. 最后提供一个重构后的优化版本代码。 # 输出格式要求 请使用Markdown格式输出包含“功能总结”、“问题与建议”、“优化后代码”三个二级标题。 # 约束与注意事项 - 评审意见必须具体指出代码行号或片段。 - 优化后的代码必须保持原函数接口不变。 - 所有建议需以中文给出。 # 输入 python def process_data(user_input, config_fileconfig.json): import json with open(config_file) as f: config json.load(f) sql fSELECT * FROM users WHERE name {user_input} # ... 执行sql的代码省略使用这样的结构化Prompt模型返回的结果会非常有条理直接满足后续自动化处理或人工阅读的需求。 ### 4.3 进阶技巧思维链与少样本学习 对于逻辑推理或复杂任务可以引导模型“一步步思考”。 * **思维链Chain-of-Thought**在Prompt中明确要求模型展示推理过程。 * **Prompt**“小明有5个苹果他给了小红2个又买了3个橙子。请问他现在有多少个水果请一步步思考。” * **模型输出**“首先计算苹果数量5 - 2 3个苹果。然后计算水果总数苹果3个 橙子3个 6个水果。所以他现在有6个水果。” 这种方式不仅能让答案更可靠也便于我们检查模型的逻辑是否正确。 * **少样本学习Few-Shot Learning**在Prompt中提供几个输入输出的例子让模型模仿。 将情感分类为积极、消极或中性。 示例1 输入这部电影太精彩了我看了三遍 输出积极 示例2 输入服务很慢食物也凉了。 输出消极 示例3 输入包裹已于下午送达。 输出中性 现在请分类 输入这个新功能用起来还行没什么特别的。 输出 通过提供示例模型能快速理解你想要的输出格式和分类标准特别适用于格式固定或定义独特的任务。 ## 5. 避坑指南常见错误与优化策略 在实际调用中你一定会遇到各种错误和不如预期的结果。以下是典型问题的排查思路和解决方案。 ### 5.1 错误码解析与处理 * **400 Bad Request**这是最常见的错误意味着请求格式有问题。 * **invalid prompt: your prompt was flagged as potentially violating our usage policy**: 你的Prompt内容触发了内容安全策略。**不要尝试绕过**。应仔细检查Prompt中是否包含暴力、仇恨、违法或极端敏感内容并重新措辞专注于解决技术或合规问题。 * **‘type’ must be in [“enabled”, “disabled”, “auto”]**: 这表明你传入了一个API不支持的参数值。仔细核对API文档检查是否有参数名拼写错误或值不在允许范围内。 * **this model‘s maximum context length is ...**: 上下文超长。你需要减少 messages 中历史对话的总长度或者选择上下文窗口更大的模型。对于长文档处理可以考虑先进行摘要或分段。 * **通用排查**首先使用 print(json.dumps(data, indent2)) 打印出你发送的完整请求体与官方API文档示例逐字段对比。99%的400错误源于字段名错误、嵌套结构错误或值类型错误比如该传字符串的传了数字。 * **429 Too Many Requests**请求速率超限。所有API都有速率限制RPM-每分钟请求数 TPM-每分钟token数。 * **解决方案**实现请求重试逻辑并加入指数退避延迟。例如遇到429时等待 (2 ** retry_count) 秒后再重试并设置最大重试次数。 python import time def call_api_with_retry(data, max_retries3): for attempt in range(max_retries): try: response requests.post(API_URL, headersheaders, jsondata, timeout30) if response.status_code 429: wait_time 2 ** attempt # 指数退避 print(f速率限制等待 {wait_time} 秒后重试...) time.sleep(wait_time) continue response.raise_for_status() return response.json() except requests.exceptions.RequestException: if attempt max_retries - 1: raise time.sleep(1) return None * **5xx Server Error**服务器内部错误。通常是API服务提供方的问题。 * **解决方案**记录错误信息进行重试。如果持续发生需要查看服务状态页或联系支持。错误信息如 api error: connection closed mid-response. the response above may be incomplete 就属于此类可能是网络波动或服务端中断重试通常能解决。 ### 5.2 性能与成本优化 * **缓存重复请求**如果你的应用中有大量相似或重复的Prompt例如标准化的系统指令不同的用户查询可以考虑缓存模型的响应结果。但要注意对于 temperature 0 的请求输出可能不同缓存需谨慎。 * **精简Prompt**Prompt中的每一个token都计费且消耗上下文窗口。删除不必要的废话使用简洁明了的指令。将固定的系统指令存储在变量中复用而不是每次请求都重新拼接。 * **异步与非阻塞调用**对于需要批量处理或前端交互的应用使用异步请求如 aiohttp 库可以避免阻塞主线程提升吞吐量和响应速度。 * **合理设置 max_tokens**根据任务实际需要预估输出长度不要盲目设置一个很大的值。你可以先进行几次测试观察典型回复的长度然后设置一个略高于平均值的 max_tokens。 * **模型选型**如前所述在非关键路径或简单任务上使用更小、更快的模型如 deepseek-v4-flash能显著降低成本并提高响应速度。 ### 5.3 Prompt的迭代与评估 设计Prompt不是一个一蹴而就的过程而是一个“编写-测试-评估-修改”的循环。 1. **定义成功标准**在开始前就想清楚什么样的输出算合格是格式完全正确是包含了所有关键信息还是风格符合要求 2. **创建测试集**准备一组具有代表性的输入用例包括简单、复杂和边界情况。 3. **批量测试与评估**编写脚本用你的Prompt批量处理测试集将输出保存下来。 4. **人工分析**仔细阅读输出找出问题模式。是格式错误是遗漏信息还是理解了偏差 5. **迭代Prompt**根据分析结果有针对性地修改Prompt。可能是增加约束、提供示例、改变角色描述或拆分任务步骤。 6. **自动化评估可选**对于某些任务可以用规则或另一个LLM调用这被称为“LLM-as-a-Judge”来对输出进行评分加速迭代循环。 记住Prompt工程的目标是**减少歧义对齐意图**。你和模型之间的“沟通损耗”越小结果就越理想。 ## 6. 超越基础构建稳健的应用 当你掌握了单次调用后下一步就是思考如何将其融入一个真正的、稳健的应用中。 ### 6.1 设计健壮的客户端 一个生产级的API客户端不应只是简单的函数调用。它应该包含 * **配置管理**将API密钥、Base URL、默认模型等配置外置如环境变量、配置文件避免硬编码。 * **统一的错误处理与日志**对所有可能的异常网络、HTTP、解析、业务逻辑进行捕获、分类和记录并给出用户友好的提示或执行降级策略。 * **重试与退避机制**如前所述针对429、5xx等可重试错误实现策略。 * **连接池与超时管理**对于高频调用使用 requests.Session 或类似机制管理HTTP连接并合理设置连接、读取超时。 * **监控与度量**记录每次调用的延迟、消耗token数、成功率便于后续性能分析和成本核算。 ### 6.2 处理长上下文与复杂任务 对于超出模型上下文窗口的长文本或者需要多步骤推理的复杂任务单次API调用无法解决。 * **“Map-Reduce”策略**将长文档分割成有重叠的片段Chunk分别发送给模型处理Map最后再将所有结果汇总Reduce。例如总结一本电子书可以先分章节总结再对章节摘要进行总结。 * **使用Agent框架**对于需要工具调用如搜索、计算、查数据库、多轮规划和复杂决策的任务可以考虑使用LangChain、LangGraph等框架。它们提供了构建“智能体”的范式将LLM作为核心控制器协调一系列工具和步骤来完成目标。例如一个数据分析Agent可以接受自然语言问题然后自动编写SQL查询、执行、并对结果进行解释。 * **函数调用Function Calling**这是让LLM与外部工具交互的官方推荐方式。你可以在请求中定义一系列工具函数的schema模型在认为需要时会返回一个包含具体函数调用参数的JSON。你的代码再根据这个JSON去真正执行函数并将结果返回给模型进行下一步。这极大地增强了LLM的实操能力。 从简单的API调用到设计精良的Prompt再到构建稳健的应用集成这条路径上的每一步都需要清晰的思考和不断的实践。最关键的是开始动手从一个具体的、小规模的任务开始调用一次API分析返回结果调整你的Prompt再观察变化。这个快速反馈循环是掌握LLM应用开发最有效的方法。