Phi-3-Mini-128K调用API全指南：Python与Java客户端开发示例

Phi-3-Mini-128K调用API全指南Python与Java客户端开发示例你是不是已经部署好了Phi-3-Mini-128K模型看着那个API地址却不知道下一步该怎么把它用起来或者你正在开发一个应用想集成AI对话能力但面对HTTP请求、JSON格式、流式响应这些概念有点发怵别担心这篇文章就是为你准备的。我会用最直白的方式手把手带你搞定Python和Java两种语言的API调用。你不用是HTTP协议专家也不用对AI模型内部原理了如指掌只要会写基本的代码跟着步骤走就能让你的应用“开口说话”。我们的目标很简单让你能写个程序发一段话给模型然后稳稳当当地把模型的回复接回来用在你的网站、App或者任何需要智能对话的地方。1. 开始之前你需要准备什么在动手写代码之前我们先看看需要哪些“食材”。这样你检查一下自己的“厨房”缺什么补什么后面做起来就顺畅了。首先一个正在运行的Phi-3-Mini-128K模型服务。这是最核心的。通常这个服务会提供一个URL地址比如http://你的服务器地址:端口/v1/chat/completions。如果你是用一些现成的镜像或一键部署工具搭的这个地址应该已经告诉你了。如果还没部署你得先解决这个问题本指南假设你的模型服务已经就绪在等着接收请求了。其次选择你的编程武器。我们今天主打两门“语言”Python如果你做数据分析、快速原型开发或者喜欢语法简洁选它准没错。我们会用最常用的requests库。Java如果你在构建企业级后端服务、Android应用或者你的技术栈就是Java生态那么这部分就是为你写的。我们会介绍两种常用方式轻量级的OkHttp和 Spring框架里的RestTemplate。最后一点基本的编程知识。你需要知道怎么安装库pip install 或 Maven/Gradle配置怎么写一个简单的函数以及如何处理像字符串、列表、字典或Map这样的基本数据结构。放心代码都会给得很完整你甚至可以复制粘贴然后改改参数就能用。好了工具齐备我们正式开始。2. 核心概念一次API调用到底在干什么在写代码前花两分钟了解一下我们到底要让程序做什么这样你看代码就不会觉得是一堆莫名其妙的符号了。你可以把这次调用想象成一次“点餐”和“上菜”的过程。你点餐发送请求你的程序就是顾客。你需要准备一张“点菜单”JSON格式的数据告诉厨房模型服务你想要什么。这张菜单上至少要写清楚“我想聊什么”对话内容以及“我想要什么样的回答”一些参数比如别太长、别太啰嗦。厨房做菜模型推理厨房收到菜单开始生火做饭模型开始计算生成文字。这个过程可能需要几秒到十几秒。服务员上菜接收响应厨房做好后服务员网络把菜生成的文本端给你。菜可能是一下子全上来非流式也可能像吃火锅一样涮好一片肉就递给你一片流式响应。我们代码要做的就是规规矩矩地写好这张“点菜单”然后可靠地把它送出去最后妥妥地接住“服务员”端来的“菜”并且万一“服务员”说“今天厨房太忙了”服务器错误或者“这道菜没了”请求错误我们还得知道怎么处理。这个“点菜单”的固定格式通常遵循OpenAI API的兼容格式长这样{ model: phi-3-mini-128k-instruct, // 指定模型有时可省略 messages: [ {role: system, content: 你是一个乐于助人的助手。}, // 系统指令设定角色 {role: user, content: 你好请介绍一下你自己。} // 用户的问题 ], stream: false, // 是否开启流式响应 max_tokens: 512 // 限制回答的最大长度 }理解了这个流程和格式后面的代码你就看懂了八成。3. Python客户端实战用Requests库快速上手Python社区有句话叫“人生苦短我用Python”。在调用API这件事上requests库让它变得非常简单。3.1 安装与基础请求首先确保安装了requests库。没安装的话打开终端运行pip install requests接下来我们写一个最基础的调用函数import requests import json def call_phi3_simple(api_url, user_message): 一个最简单的Phi-3 API调用示例 :param api_url: 你的模型API地址例如 http://localhost:8000/v1/chat/completions :param user_message: 用户输入的消息 :return: 模型返回的完整响应文本 # 1. 准备请求头告诉服务器我们发送的是JSON数据 headers { Content-Type: application/json } # 2. 准备请求体就是我们的“点菜单” payload { model: phi-3-mini-128k-instruct, # 模型名称根据你的实际部署调整 messages: [ {role: user, content: user_message} ], stream: False, # 非流式一次性返回全部结果 max_tokens: 500 # 限制生成长度 } try: # 3. 发送POST请求 response requests.post(api_url, headersheaders, datajson.dumps(payload)) # 4. 检查请求是否成功HTTP状态码为200 response.raise_for_status() # 5. 解析返回的JSON数据 result response.json() # 从复杂的返回结构中提取出我们需要的回答文本 reply_content result[choices][0][message][content] return reply_content except requests.exceptions.RequestException as e: # 处理网络或请求错误 print(f请求出错: {e}) if response is not None: print(f响应状态码: {response.status_code}) print(f响应内容: {response.text}) return None except (KeyError, IndexError) as e: # 处理响应数据解析错误 print(f解析响应数据出错: {e}) print(f原始响应: {response.text}) return None # 使用示例 if __name__ __main__: API_URL http://你的服务器地址:端口/v1/chat/completions # 替换成你的真实地址 my_question Python是什么 answer call_phi3_simple(API_URL, my_question) if answer: print(模型回复, answer)把代码里的API_URL换成你自己的地址运行一下。如果一切顺利你就能看到模型对你问题的回答了。这个函数虽然简单但包含了核心步骤组包、发送、接收、解包。3.2 处理流式响应让回答“打字”出来上面是一次性拿到全部回答。如果你想实现像ChatGPT那样一个字一个字“蹦出来”的效果就需要使用流式响应。这不仅能提升用户体验在生成长文本时也能更快地看到开头部分。def call_phi3_stream(api_url, user_message): 流式调用Phi-3 API实时打印生成内容 headers {Content-Type: application/json} payload { model: phi-3-mini-128k-instruct, messages: [{role: user, content: user_message}], stream: True, # 关键开启流式 max_tokens: 500 } try: # 设置streamTrue让requests以流的方式接收数据 response requests.post(api_url, headersheaders, datajson.dumps(payload), streamTrue) response.raise_for_status() print(模型回复流式: , end, flushTrue) full_reply # 迭代接收到的数据流 for line in response.iter_lines(): if line: line_decoded line.decode(utf-8) # 流式数据每行以data: 开头且有一个空行表示结束 if line_decoded.startswith(data: ): data_str line_decoded[6:] # 去掉data: 前缀 if data_str [DONE]: # 结束标志 break try: data json.loads(data_str) # 提取流式返回中的文本片段 chunk_content data[choices][0][delta].get(content, ) if chunk_content: print(chunk_content, end, flushTrue) full_reply chunk_content except json.JSONDecodeError: # 忽略非JSON行如心跳包 continue print() # 换行 return full_reply except requests.exceptions.RequestException as e: print(f流式请求出错: {e}) return None # 使用示例 # answer_stream call_phi3_stream(API_URL, 讲一个简短的笑话。)运行这段代码你会看到模型的回答是一个词一个词地出现在屏幕上体验更棒。3.3 进阶技巧添加认证与重试机制在实际项目中你的API可能设置了密钥认证并且网络请求偶尔会失败我们需要更健壮的代码。import time class Phi3Client: 一个更健壮的Phi-3 API客户端类 def __init__(self, base_url, api_keyNone, max_retries3): self.base_url base_url.rstrip(/) self.headers {Content-Type: application/json} if api_key: self.headers[Authorization] fBearer {api_key} self.max_retries max_retries self.session requests.Session() # 使用Session可以复用TCP连接提升效率 def chat_completion(self, messages, streamFalse, **kwargs): 发送聊天补全请求支持重试 :param messages: 消息列表例如 [{role: user, content: 你好}] :param stream: 是否流式 :param kwargs: 其他API参数如max_tokens, temperature等 :return: 响应数据或生成器对于流式 payload { model: phi-3-mini-128k-instruct, messages: messages, stream: stream, **kwargs # 将其他参数合并进来 } for attempt in range(self.max_retries): try: if stream: response self.session.post( f{self.base_url}/chat/completions, headersself.headers, jsonpayload, streamTrue, timeout30 # 设置超时时间 ) response.raise_for_status() return self._handle_stream_response(response) else: response self.session.post( f{self.base_url}/chat/completions, headersself.headers, jsonpayload, timeout30 ) response.raise_for_status() return response.json() except (requests.exceptions.ConnectionError, requests.exceptions.Timeout) as e: # 如果是连接或超时错误进行重试 if attempt self.max_retries - 1: wait_time 2 ** attempt # 指数退避1秒2秒4秒... print(f请求失败{wait_time}秒后重试 ({attempt1}/{self.max_retries})。错误: {e}) time.sleep(wait_time) else: print(f重试{self.max_retries}次后仍失败。) raise except requests.exceptions.HTTPError as e: # HTTP错误如401 403 500通常重试无用直接抛出 print(fHTTP错误: {e.response.status_code} - {e.response.text}) raise except requests.exceptions.RequestException as e: # 其他请求异常 print(f请求异常: {e}) raise def _handle_stream_response(self, response): 处理流式响应返回一个生成器每次yield一个文本片段 for line in response.iter_lines(): if line: line_decoded line.decode(utf-8) if line_decoded.startswith(data: ): data_str line_decoded[6:] if data_str [DONE]: break try: data json.loads(data_str) chunk data[choices][0][delta].get(content, ) if chunk: yield chunk except json.JSONDecodeError: continue # 使用这个更健壮的客户端 if __name__ __main__: client Phi3Client( base_urlhttp://你的服务器地址:端口/v1, api_keyyour-api-key-here # 如果需要 ) # 非流式调用 messages [{role: user, content: 用Python写一个Hello World程序。}] result client.chat_completion(messages, max_tokens200, temperature0.7) if result: print(完整回复, result[choices][0][message][content]) # 流式调用 print(流式回复, end, flushTrue) for chunk in client.chat_completion(messages, streamTrue, max_tokens200): print(chunk, end, flushTrue) print()这个Phi3Client类就专业多了它包含了认证、错误重试、超时设置、连接复用等生产环境常用的功能。4. Java客户端实战OkHttp与RestTemplate任你选如果你工作在Java生态别担心调用API同样方便。这里给你两种主流选择轻量级的OkHttp和Spring生态的RestTemplate。4.1 使用OkHttp轻量级选择OkHttp是一个高效的HTTP客户端库非常适合移动端或简单的Java应用。首先添加依赖以Maven为例dependency groupIdcom.squareup.okhttp3/groupId artifactIdokhttp/artifactId version4.12.0/version !-- 请使用最新稳定版 -- /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.15.4/version !-- 用于JSON处理 -- /dependency然后编写调用代码import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ArrayNode; import com.fasterxml.jackson.databind.node.ObjectNode; import okhttp3.*; import java.io.IOException; import java.util.concurrent.TimeUnit; public class Phi3OkHttpClient { private final OkHttpClient client; private final ObjectMapper objectMapper; private final String apiUrl; private final String apiKey; // 可选 public Phi3OkHttpClient(String apiUrl, String apiKey) { this.apiUrl apiUrl; this.apiKey apiKey; this.objectMapper new ObjectMapper(); // 配置OkHttpClient设置超时等参数 this.client new OkHttpClient.Builder() .connectTimeout(10, TimeUnit.SECONDS) .writeTimeout(30, TimeUnit.SECONDS) // 模型生成可能需要时间 .readTimeout(60, TimeUnit.SECONDS) .build(); } public String callModel(String userMessage) throws IOException { // 1. 构建JSON请求体 ObjectNode requestBody objectMapper.createObjectNode(); requestBody.put(model, phi-3-mini-128k-instruct); ArrayNode messages objectMapper.createArrayNode(); ObjectNode userMsg objectMapper.createObjectNode(); userMsg.put(role, user); userMsg.put(content, userMessage); messages.add(userMsg); requestBody.set(messages, messages); requestBody.put(stream, false); requestBody.put(max_tokens, 500); String jsonBody objectMapper.writeValueAsString(requestBody); // 2. 构建请求 Request.Builder requestBuilder new Request.Builder() .url(apiUrl) .post(RequestBody.create(jsonBody, MediaType.get(application/json))); // 添加认证头如果需要 if (apiKey ! null !apiKey.isEmpty()) { requestBuilder.addHeader(Authorization, Bearer apiKey); } Request request requestBuilder.build(); // 3. 发送请求并处理响应 try (Response response client.newCall(request).execute()) { if (!response.isSuccessful()) { throw new IOException(Unexpected code response , body: response.body().string()); } // 4. 解析响应 String responseBody response.body().string(); ObjectNode responseJson (ObjectNode) objectMapper.readTree(responseBody); // 提取回复内容 String reply responseJson .path(choices) .path(0) .path(message) .path(content) .asText(); return reply; } } // 处理流式响应的示例概念性代码更复杂一些 public void callModelStream(String userMessage, StreamCallback callback) throws IOException { ObjectNode requestBody objectMapper.createObjectNode(); // ... 构建请求体注意 stream: true ... requestBody.put(stream, true); // 构建请求... Request request new Request.Builder() .url(apiUrl) .post(RequestBody.create( objectMapper.writeValueAsString(requestBody), MediaType.get(application/json))) .build(); // OkHttp对流式支持需要更底层的处理这里省略详细实现 // 通常使用client.newCall(request).enqueue并处理分块返回的响应体 System.out.println(流式调用实现较复杂建议参考OkHttp的SSE或WebSocket示例。); } // 一个简单的回调接口用于处理流式数据块 public interface StreamCallback { void onChunk(String contentChunk); void onComplete(); void onError(IOException e); } // 使用示例 public static void main(String[] args) { try { Phi3OkHttpClient phi3Client new Phi3OkHttpClient( http://你的服务器地址:端口/v1/chat/completions, null // 如果没有API密钥传null ); String reply phi3Client.callModel(Java和Python的主要区别是什么); System.out.println(模型回复: reply); } catch (IOException e) { e.printStackTrace(); } } }4.2 使用Spring RestTemplateSpring生态首选如果你的项目基于Spring Boot那么使用RestTemplate或新的WebClient会更方便它能很好地与Spring的配置、依赖注入整合。添加Spring Boot Web依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency编写Service类import org.springframework.http.*; import org.springframework.stereotype.Service; import org.springframework.web.client.RestTemplate; import org.springframework.web.client.HttpClientErrorException; import org.springframework.web.client.ResourceAccessException; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ArrayNode; import com.fasterxml.jackson.databind.node.ObjectNode; import java.util.*; Service public class Phi3SpringClient { private final RestTemplate restTemplate; private final ObjectMapper objectMapper; private final String apiUrl; // 可以通过Value从配置文件注入 public Phi3SpringClient(Value(${phi3.api.url}) String apiUrl, Value(${phi3.api.key:}) String apiKey) { this.apiUrl apiUrl; this.restTemplate new RestTemplate(); this.objectMapper new ObjectMapper(); // 可以在这里配置RestTemplate比如设置拦截器添加认证头 if (apiKey ! null !apiKey.isEmpty()) { this.restTemplate.getInterceptors().add((request, body, execution) - { request.getHeaders().add(Authorization, Bearer apiKey); return execution.execute(request, body); }); } } public String getChatCompletion(String userMessage) { // 1. 构建请求头 HttpHeaders headers new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); headers.setAccept(Collections.singletonList(MediaType.APPLICATION_JSON)); // 2. 构建请求体 ObjectNode requestBody objectMapper.createObjectNode(); requestBody.put(model, phi-3-mini-128k-instruct); ArrayNode messages objectMapper.createArrayNode(); ObjectNode userMsg objectMapper.createObjectNode(); userMsg.put(role, user); userMsg.put(content, userMessage); messages.add(userMsg); requestBody.set(messages, messages); requestBody.put(stream, false); requestBody.put(max_tokens, 512); requestBody.put(temperature, 0.7); // 控制随机性 HttpEntityString requestEntity; try { requestEntity new HttpEntity(objectMapper.writeValueAsString(requestBody), headers); } catch (Exception e) { throw new RuntimeException(构建请求JSON失败, e); } // 3. 发送请求 try { ResponseEntityJsonNode response restTemplate.postForEntity( apiUrl, requestEntity, JsonNode.class ); if (response.getStatusCode() HttpStatus.OK response.hasBody()) { JsonNode body response.getBody(); // 4. 提取回复 String reply body.path(choices).path(0).path(message).path(content).asText(); return reply; } else { throw new RuntimeException(API请求失败状态码: response.getStatusCode()); } } catch (HttpClientErrorException e) { // 处理4xx错误客户端错误 System.err.println(客户端错误: e.getStatusCode() - e.getResponseBodyAsString()); throw new RuntimeException(API客户端错误: e.getMessage(), e); } catch (ResourceAccessException e) { // 处理网络连接错误 throw new RuntimeException(网络连接失败请检查API地址和网络: e.getMessage(), e); } catch (Exception e) { throw new RuntimeException(调用API时发生未知错误, e); } } // 一个更健壮的方法支持重试可以使用Spring Retry注解 // Retryable(value {ResourceAccessException.class}, maxAttempts 3, backoff Backoff(delay 1000)) public String getChatCompletionWithRetry(String userMessage, int maxRetries) { int attempts 0; while (attempts maxRetries) { try { return getChatCompletion(userMessage); } catch (RuntimeException e) { attempts; if (attempts maxRetries) { throw e; // 重试次数用尽抛出异常 } System.out.println(调用失败第 attempts 次重试...); try { Thread.sleep(1000 * attempts); // 简单的指数退避 } catch (InterruptedException ie) { Thread.currentThread().interrupt(); throw new RuntimeException(重试被中断, ie); } } } throw new RuntimeException(重试逻辑异常); } } // 在Controller中使用 RestController RequestMapping(/api/chat) public class ChatController { Autowired private Phi3SpringClient phi3Client; PostMapping public ResponseEntityMapString, String chat(RequestBody MapString, String request) { String userMessage request.get(message); if (userMessage null || userMessage.trim().isEmpty()) { return ResponseEntity.badRequest().body(Collections.singletonMap(error, 消息不能为空)); } try { String reply phi3Client.getChatCompletionWithRetry(userMessage, 3); return ResponseEntity.ok(Collections.singletonMap(reply, reply)); } catch (Exception e) { return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR) .body(Collections.singletonMap(error, 处理请求时出错: e.getMessage())); } } }使用Spring的方式看起来代码量多一些但它和Spring生态无缝集成管理配置、依赖注入、异常处理、重试机制等都更规范适合中大型项目。5. 总结与最佳实践建议走完了Python和Java的调用之旅你应该已经能在自己的项目中让Phi-3模型“跑起来”了。最后我想分享几个从实际项目中总结出来的小建议希望能帮你少踩一些坑。首先关于API地址和密钥千万别硬编码在代码里。无论是Python还是Java都尽量用配置文件、环境变量或者云平台的密钥管理服务来存储这些敏感信息。比如在Python里可以用os.getenv(PHI3_API_KEY)在Spring Boot里用Value(${api.key})注入。这样既安全也方便在不同环境开发、测试、生产之间切换。其次网络请求一定要设置超时。模型生成文本的时间不确定如果网络慢或者服务器压力大没有超时设置的请求可能会一直挂起拖垮你的应用。Python的requests和Java的OkHttpClient、RestTemplate都提供了很方便的超时配置选项根据你的场景合理设置连接超时、读取超时和写入超时。第三错误处理要细致。代码里不能只期待成功响应。网络可能会波动服务器可能重启请求格式可能不对。像我们上面示范的那样至少区分一下网络错误可以重试和业务逻辑错误比如认证失败、请求格式错误重试也没用。给用户返回友好的错误信息同时记录详细的日志方便排查。第四流式响应用户体验更好。如果前端是网页或App并且模型生成的内容较长尽量使用流式接口。用户不用盯着空白页干等看到文字逐渐出现体验会好很多。处理流式数据时注意数据的拼接和最终完整内容的获取。最后也是最重要的从简单开始逐步完善。不要一开始就追求大而全的封装。先用最基础的代码跑通整个流程确保模型能正确响应。然后再慢慢加上认证、重试、连接池、监控这些高级功能。每加一层都测试一下这样出问题了你也知道大概是哪部分引入的。希望这份指南能成为你集成Phi-3模型的一个扎实起点。动手试试吧从最简单的“你好”开始看着模型回应你那种感觉还是挺奇妙的。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。