华为云盘古大模型多语言对接完全指南：PHP、Java、Python 从入门到实战
一、盘古大模型对接概述
华为云盘古大模型作为国内领先的AI大模型体系，凭借其分层解耦架构和行业深度适配能力，已成为企业智能化转型的核心工具。对于开发者而言，将盘古大模型的能力集成到现有业务系统中，最直接的方式就是通过华为云提供的REST API或推理SDK进行调用。盘古大模型推理SDK是对REST API的封装，通过该SDK可以处理用户的输入，生成模型的回复，从而实现自然流畅的对话体验。
目前盘古推理SDK支持Java、Python、Go、.NET、NodeJs等多种编程语言。其中，对话问答功能（/chat/completions）支持Java、Python、Go、.NET、NodeJs；通用文本功能（/text/completions）额外支持PHP。本文将重点围绕PHP、Java、Python三种语言，系统讲解盘古大模型的对接流程与实战技巧。
需要先登录华为云控制台，点击：华为云控制台，还没有账号，点击：注册并关联，已有账号点击：登录后关联
二、对接前的准备工作
2.1 账号注册与环境准备
调用盘古大模型API之前，需要完成以下基础准备工作：注册华为账号并开通华为云，完成实名认证，确保账号不处于欠费或冻结状态。检查本地开发环境是否满足SDK的运行要求：Java SDK需要JDK 1.8及以上版本；Python SDK需要Python 3及以上版本。
2.2 开通盘古大模型服务
登录盘古大模型套件平台，在左侧导航栏中选择“服务管理”，在相应服务的操作列单击“查看详情”，可在服务列表中申请需要开通的服务。盘古大模型提供了多种服务类型，主要包括：通用文本（文本补全）接口提供单轮文本能力，常用于文本生成、文本摘要、闭卷问答等任务；对话问答（多轮对话）接口提供多轮文本能力，常用于多轮对话、聊天任务。
部分高阶模型（如718B参数的NLP深度思考模型）需要提交应用场景说明并通过审核后方可使用。
2.3 获取模型调用路径与部署ID
模型开通后，需要获取调用路径和部署ID。若调用部署后的模型，可在左侧导航栏中选择“模型开发 > 模型部署”，在“我的服务”页签中单击模型名称，在“详情”页签中获取模型的部署ID。若调用预置模型，可在“预置服务”页签中单击“调用路径”获取部署ID。
API的访问路径根据接口版本有所不同：V1推理接口的路径格式为 /v1/{project_id}/deployments/{deployment_id}/chat/completions；V2推理接口的路径格式为 /api/v2/chat/completions。V1接口和V2接口的鉴权方式不同，请求体和返回体也略有差异。
三、认证鉴权方式详解
调用盘古大模型API有两种认证方式：Token认证和API Key认证。
3.1 Token认证
Token认证是在调用API时将Token加到请求消息头，从而通过身份认证获得操作API的权限。Token的有效期为24小时，使用时可以先缓存Token，避免频繁调用。如果华为云账号已升级为华为账号，将不支持获取账号Token，建议创建一个IAM用户来获取Token。
获取Token需要调用IAM接口，以中国-香港区域为例，接口地址为 https://iam.ap-southeast-1.myhuaweicloud.com/v3/auth/tokens。请求体需要包含IAM用户名、密码、账号名以及项目区域信息。
3.2 API Key认证
当用户部署的模型服务需要开放给其他用户调用时，原有的Token认证需要进行动态认证鉴权和凭证管理，操作较为繁杂。此时可以使用API Key认证方式。API Key认证指调用API时在HTTP请求头部增加X-Apig-AppCode参数，参数值为API Key值，API服务仅校验API Key即可实现快速响应。
获取API Key的步骤如下：登录ModelArts Studio平台进入所需空间，在左侧导航栏中选择“系统管理与统计 > 应用接入”，单击“创建应用接入”，在应用配置中选择已部署的大模型，创建完成后即可在应用接入列表的“API Key”列获取值。V2推理接口使用API Key认证时，需要在Authorization头中拼接“Bearer ”前缀。
四、Python语言对接实战
4.1 安装SDK
Python语言使用pip安装SDK，需要安装核心库和盘古服务库两个包：
# 安装核心库
pip install huaweicloudsdkcore
# 安装盘古服务库
pip install huaweicloudsdkpangulargemodels4.2 Token认证方式调用
以下示例演示了如何通过Token认证方式调用盘古NLP大模型的文本对话API：
import requests
import json
# 1. 获取Token
url = "https://iam.ap-southeast-1.myhuaweicloud.com/v3/auth/tokens"
payload = json.dumps({
"auth": {
"identity": {
"methods": ["password"],
"password": {
"user": {
"name": "your_iam_username",
"password": "your_password",
"domain": {"name": "your_domain_name"}
}
}
},
"scope": {
"project": {"name": "ap-southeast-1"}
}
}
})
headers = {'Content-Type': 'application/json'}
response = requests.post(url, headers=headers, data=payload)
token = response.headers["X-Subject-Token"]
# 2. 调用盘古模型API
api_url = "https://{endpoint}/v1/{project_id}/deployments/{deployment_id}/chat/completions"
headers = {
"Content-Type": "application/json",
"X-Auth-Token": token
}
data = {
"messages": [{"content": "介绍下长江，以及长江中典型的鱼类"}],
"temperature": 0.9,
"max_tokens": 600
}
response = requests.post(api_url, headers=headers, json=data)
print(response.json())4.3 API Key认证方式调用
API Key认证方式更为简便：
import requests
headers = {
"X-Apig-AppCode": "your_api_key",
"Content-Type": "application/json"
}
data = {
"messages": [{"content": "分析新能源电池技术发展趋势"}],
"max_tokens": 500
}
response = requests.post(
"https://{endpoint}/v1/{project_id}/deployments/{deployment_id}/chat/completions",
headers=headers,
json=data
)
print(response.json()["text"])五、Java语言对接实战
5.1 安装SDK
Java语言通过Maven管理依赖，在pom.xml中加入以下依赖：
<dependency>
<groupId>com.huaweicloud.sdk</groupId>
<artifactId>huaweicloud-sdk-core</artifactId>
<version>3.1.103</version>
</dependency>
<dependency>
<groupId>com.huaweicloud.sdk</groupId>
<artifactId>huaweicloud-sdk-pangulargemodels</artifactId>
<version>3.1.103</version>
</dependency>5.2 使用API Explorer生成代码
华为云API Explorer可根据需要动态生成SDK代码。在API Explorer中具体API页面的“代码示例”页签可以查看对应编程语言类型的SDK代码，填入相应内容后右侧代码示例会自动完成参数的组装。
5.3 Java SDK调用示例
以下是通过Java SDK调用盘古模型的示例代码：
import com.huaweicloud.sdk.core.auth.BasicCredentials;
import com.huaweicloud.sdk.core.exception.ConnectionException;
import com.huaweicloud.sdk.core.exception.RequestTimeoutException;
import com.huaweicloud.sdk.core.exception.ServiceResponseException;
import com.huaweicloud.sdk.pangulargemodels.v1.PanguLargeModelsClient;
import com.huaweicloud.sdk.pangulargemodels.v1.model.*;
public class PanguDemo {
public static void main(String[] args) {
String ak = "your_ak";
String sk = "your_sk";
String projectId = "your_project_id";
String endpoint = "your_endpoint";
BasicCredentials auth = new BasicCredentials()
.withAk(ak)
.withSk(sk)
.withProjectId(projectId);
PanguLargeModelsClient client = PanguLargeModelsClient.newBuilder()
.withCredential(auth)
.withEndpoint(endpoint)
.build();
ChatCompletionsRequest request = new ChatCompletionsRequest();
request.setDeploymentId("your_deployment_id");
ChatCompletionsRequestBody body = new ChatCompletionsRequestBody();
body.setMessages(Arrays.asList(
new Message().withContent("介绍一下华为云盘古大模型")
));
body.setTemperature(0.7);
body.setMaxTokens(500);
request.setBody(body);
try {
ChatCompletionsResponse response = client.chatCompletions(request);
System.out.println(response.toString());
} catch (ConnectionException | RequestTimeoutException | ServiceResponseException e) {
e.printStackTrace();
}
}
}六、PHP语言对接实战
6.1 PHP调用概述
PHP调用盘古大模型必须通过华为云API，需要使用AK/SK签名、专属endpoint、正确的请求头与JSON格式。盘古系列大模型不提供直接的HTTP接口或开源模型权重，PHP实际调用的是华为云ModelArts平台封装的推理服务，本质上是HTTPS POST请求。
PHP原生cURL不自带签名逻辑，需要自己实现签名或使用社区轻量封装（如huaweicloud-sdk-php-core的Signer类）。请求URL不是固定域名，而是模型部署后生成的专属endpoint，形如 https://xxxxx.modelarts.cn-north-1.myhuaweicloud.com/v1/{project_id}/inference。
6.2 PHP cURL调用示例
以下是通过PHP cURL方式调用盘古模型的完整示例：
<?php
function callPanguModel($prompt, $apiUrl, $token) {
$headers = [
'Content-Type: application/json',
'X-Auth-Token: ' . $token
];
$data = [
'messages' => [
['content' => $prompt]
],
'temperature' => 0.9,
'max_tokens' => 600
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (curl_errno($ch)) {
echo 'cURL Error: ' . curl_error($ch);
}
curl_close($ch);
if ($httpCode == 200) {
return json_decode($response, true);
} else {
return ['error' => 'HTTP Code: ' . $httpCode, 'response' => $response];
}
}
// 使用示例
$token = 'your_iam_token';
$apiUrl = 'https://xxxxx.modelarts.cn-north-1.myhuaweicloud.com/v1/{project_id}/inference';
$result = callPanguModel('请生成一份关于人工智能发展趋势的简要报告', $apiUrl, $token);
print_r($result);
?>6.3 PHP流式响应处理
华为云盘古API支持流式（stream=true）和非流式两种模式。PHP默认使用curl_exec()获取完整响应，但如果后端开启了流式输出，收到的可能是chunked编码的多段JSON，直接json_decode()会失败。处理流式响应时，需要先检查响应头中的Content-Type，如果包含“text/event-stream”则按流式协议逐段解析。
6.4 PHP常见错误与排查
PHP调用盘古API时常见错误包括：cURL error 60（SSL证书问题）、401 Unauthorized（签名鉴权失败）、400 InvalidParameter（请求体格式不对）。请求头必须包含X-Auth-Token和Content-Type: application/json。请求体JSON中的model_name必须与控制台部署时填写的名称完全一致（注意大小写和下划线），填错会返回“Model not found”。
七、对接最佳实践与进阶技巧
7.1 Prompt工程的核心技巧
盘古大模型对长文本摘要和结构化输出支持良好，但模型本身不会主动分章节或按特定格式归类，这些完全取决于Prompt指令是否明确。在实际使用中，不要只传原文，必须拼接system prompt来约束输出格式。例如：{"system": "你是一名资深行业分析师，请严格按以下格式输出：一、xxx；二、xxx；每部分不超过200字，禁用markdown，禁用列表符号。"}。
避免使用模糊指令如“请总结”，盘古容易自由发挥。应换成明确指令如“请提取出文中提到的三个主要政策文件名称，并说明各自影响范围”。如果返回内容超长或被截断，通常不是模型限制，而是max_tokens参数设置太小，需要显式调大该值。
7.2 流式与非流式输出选择
流式输出适用于需要实时展示生成内容的场景（如聊天应用），用户体验更流畅。非流式输出适用于批处理任务或对实时性要求不高的场景。选择哪种模式应根据业务需求决定，同时注意两种模式下响应解析方式的差异。
7.3 限流与性能优化
盘古API调用存在QPS限制（默认每秒10次）与输入长度约束（NLP模型单次输入不超过2048个token）。开发者需要通过异步队列或批处理来优化调用效率。对于高并发场景，建议使用消息队列对请求进行削峰填谷，避免触发限流导致429错误。
7.4 错误码解读与应对
常见的HTTP状态码及其含义：200表示调用成功；400表示请求参数错误，需检查请求体格式和参数；401表示认证失败，需检查Token或API Key是否有效；429表示请求过于频繁，触发了限流，需降低请求频率或使用批处理；503表示服务暂时不可用，可实现指数退避重试策略。
八、总结
本文系统介绍了华为云盘古大模型在PHP、Java、Python三种语言下的对接方案。从账号注册、服务开通、认证鉴权到具体的SDK安装与代码实现，提供了完整的操作指引。在实际开发中，建议开发者根据业务场景选择合适的认证方式——内部系统推荐使用Token认证，对外开放的服务推荐使用API Key认证。同时注意Prompt工程对输出质量的决定性影响，以及限流策略对系统稳定性的保障作用。盘古大模型推理SDK是对REST API的封装，通过该SDK可以快速实现模型能力的集成。希望本文能帮助开发者顺利完成盘古大模型的业务对接。
常见问题解答
问1：盘古大模型支持哪些编程语言的SDK？
答：盘古推理SDK目前支持Java、Python、Go、.NET、NodeJs等语言。其中对话问答功能支持Java、Python、Go、.NET、NodeJs；通用文本功能额外支持PHP。
问2：Token认证和API Key认证有什么区别？
答：Token认证需要先调用IAM接口获取临时Token，Token有效期为24小时，适合内部系统调用。API Key认证通过X-Apig-AppCode头传递固定密钥，无需动态获取，适合对外开放的服务调用。
问3：调用盘古API时返回“Model not found”是什么原因？
答：通常是因为请求体中的model_name与控制台部署时填写的模型名称不一致，需要注意大小写和下划线的精确匹配。另外也需要确认deployment_id是否正确。
问4：PHP调用盘古API时如何处理流式响应？
答：先检查响应头的Content-Type，如果包含“text/event-stream”则按流式协议逐段解析。可以使用curl的CURLOPT_WRITEFUNCTION回调函数逐块处理数据，而非一次性获取完整响应。
问5：如何提高盘古大模型输出内容的结构化程度？
答：关键在于Prompt工程。应在system prompt中明确输出格式要求，如“请严格按以下格式输出：一、xxx；二、xxx”。避免使用“请总结”这类模糊指令，换成明确的格式约束指令。
问6：盘古API调用有频率限制吗？如何应对？
答：盘古API调用存在QPS限制，默认每秒10次。应对方案包括：使用异步队列削峰填谷、合并多个请求为批处理、实现指数退避重试策略。
