# 使用API调用预测大模型
#### 获取预测大模型推理API
1. 登录ModelArts Studio平台，在"我的空间"模块，单击进入所需空间。
   图1我的空间   
   ![](https://support.huaweicloud.com/usermanual-pangulm/zh-cn_image_0000002601606323.png) 
2. 在左侧导航栏中选择"模型开发 \> 模型部署"，单击"模型名称"在"详情"页面获取API请求地址。 只有处于"运行中"状态的模型才可以正常调用。预测大模型支持云上部署及边缘部署，以下内容将分别介绍两种部署方式如何获取API请求地址。
   - **云上部署**
     在模型部署工作区，选择您部署的大模型任务并进入部署任务。在部署模型的详情页面，直接可以找到API URL获取即可。
     注意：获取到URL后，还需要在URL末尾添加"/",否则可能出现调用失败。
     图2云上部署获取预测大模型API请求地址   
     ![](https://support.huaweicloud.com/usermanual-pangulm/zh-cn_image_0000002571206772.png) 
   
   - **边缘部署**
     **边缘部署** -**负载均衡** 访问方式，模型API组成方式为：**{访问协议}://{ELB IP}:{ELB负载端口}/{API URL}/{推理的调用URL}** ，如果详情页面API URL展示的是完全的http请求路径，则可以使用该url调用(url中如果ip为私网ip需替换为弹性ip)，具体内容参数说明参见[表1]。
      表1API参数说明 
     | 参数名称     | 说明                                                         |
     |:---|:---|
     | 访问协议     | 根据创建的ELB服务是HTTP还是HTTPS选择，也可根据部署详情页面指定的访问协议确定使用HTTP还是HTTPS。 |
     | ELB IP   | 弹性云服务器提供的公网IP。                                             |
     | ELB负载端口  | 模型部署任务完成后，部署详情页面显示的ELB 负载端口。                               |
     | API URL  | 模型部署任务完成后，部署详情页面显示的API URL。                                |
     | 推理的调用URL | 预测模型目前没有推理URL，在API URL后面添加/即可。                             |
        
     具体获取URL步骤如下：
     1. 在边缘部署任务详情页面，可以确认访问协议、ELB负载均衡端口和API URL，以及私有IP。私有IP无法直接访问，需要从提供ELB服务的ECS服务，找到私有IP和弹性IP的映射关系，通过弹性IP，才能访问到部署的模型。
        图3边缘部署任务详情   
        ![](https://support.huaweicloud.com/usermanual-pangulm/zh-cn_image_0000002571047136.png)
        图4API URL   
        ![](https://support.huaweicloud.com/usermanual-pangulm/zh-cn_image_0000002601606329.png) 
     
     2. 在华为云前端界面搜索ECS服务，进入弹性云服务器界面。
        图5搜索ECS服务   
        ![](https://support.huaweicloud.com/usermanual-pangulm/zh-cn_image_0000002571206780.png) 
     
     3. 在弹性云服务器界面，找到模型部署使用的私有IP和弹性IP的对应关系，如192.168.0.11-\>100.85.126.183
        图6获取弹性IP   
        ![](https://support.huaweicloud.com/usermanual-pangulm/zh-cn_image_0000002571206768.png) 
     
     4. 通过以上步骤，就可获取到所有部署模型的API信息，按照如上规则组合后，可调用部署模型。
      
    
 
#### 获取预测大模型API请求完整地址
参考《API参考》文档"API/模型推理接口/预测大模型"章节获取。
 #### 获取Token
参考《API参考》文档"如何调用REST API \> 认证鉴权"章节获取Token。
#### 使用API调用预测大模型
1. 在Postman中新建POST请求，并填入API请求地址完整地址。
2. 参考如图填写2个请求Header参数。
   - 参数名为Content-Type，参数值为application/json。
   
   - 参数名为X-Auth-Token，参数值为[获取Token]中获取的Token值。
     图7填写预测大模型API   
     ![](https://support.huaweicloud.com/usermanual-pangulm/zh-cn_image_0000002601726283.png) 
    
3. 在Postman中选择"Body \> raw"选项，参考以下代码填写请求Body。feature表示待预测数据中的特征名称，需要与训练数据中的特征名称保持一致，同时特征数量需要与训练数据保持一致。
   预测大模型在训练完成后，可以在训练日志页面，"模型训练"日志节点中获取推理api所用的示例数据。填写请求Body时可以参考该示例填写。
   图8获取推理api所用的示例数据   
   ![](https://support.huaweicloud.com/usermanual-pangulm/zh-cn_image_0000002601726279.png)
   ```
   {
     "data": [
       {
         "feature_1": xx,
         "feature_2": xx,
         ...
         "feature_n": xx
       },
       ...
       {
         "feature_1": xx,
         "feature_2": xx,
         ...
         "feature_n": xx
       }
     ]
   }
   ```
   
4. 单击Postman界面"Send"按钮，发送请求。
 
 #### 排列特征重要性
盘古融合推荐回归大模型和盘古融合推荐分类大模型在训练阶段提供训练特征重要性（模型[权重特征重要性](https://support.huaweicloud.com/usermanual-pangulm/pangulm_04_0257.html#pangulm_04_0257__table1412655612165)），还支持在推理阶段计算排列特征重要性，详见《API参考》"API \> 模型推理 \> 模型推理接口 \> 预测大模型 \>盘古融合推荐分类大模型 \> 排列特征重要性"和"API \> 模型推理 \> 模型推理接口 \> 预测大模型 \> 盘古融合推荐回归大模型 \> 排列特征重要性"章节。（注意，这两种特征重要性功能独立，即训练阶段的权重特征重要性是否打开，不影响推理阶段的排列特征重要性计算）
对于模型权重特征重要性（训练特征重要性）和排列特征重要性这两种特征重要性，说明如下：
1. 模型权重特征重要性（训练特征重要性） 使用方式：创建预测大模型训练任务时，打开"训练特征重要性"开关，训练完成后在"训练结果"\>"训练特征重要性"查看。
   原理简述：对于随机森林、XGBoost等基于树模型的模型，衡量每个特征对决策树构建的参与程度（具体而言，指该特征作为分裂特征的次数，以及作为分裂节点时的信息增益）。
   方法特点：计算快、效率高，使用简单。当特征为连续的数值数据，或为取值较多的类别特征数据时，获得的重要性分数可能偏高。此外，仅有部分基模型（ada，lgb，xgb，rf，et，gb）支持此重要性计算，最终重要性值为这些基模型的重要性均值，因此，当用户配置了较多其他基模型时，重要性值的准确度可能会下降。
   
2. 排列特征重要性 使用方式：准备一批包含目标列真值的数据，调用推理服务的排列特征重要性接口，在返回结果中查看。
   原理简述：衡量当某个特征的值被随机打乱后，模型效果下降的程度。模型效果下降越多，表明特征对模型效果影响越大，特征越重要。
   方法特点：可靠性更高，且不受特征是否是连续或多类别的影响，但如果特征之间存在高度相关性，可能会导致特征的重要性被低估。
   ![](https://support.huaweicloud.com/usermanual-pangulm/public_sys-resources/note_3.0-zh-cn.png)
   盘古融合推荐回归/分类大模型-极简模式在训练阶段提供的训练特征重要性为排列特征重要性，从用户数据中随机采样数据进行计算。在推理阶段不提供特征重要性的API接口。
   
 
#### 单条推理可解释（Shapley值分析）
支持用户传入一组能够代表训练数据分布的参考数据集，以及待解释的单条推理样本，基于 Shapley 值理论计算该样本中各特征对模型预测结果的贡献程度，输出特征重要性排序。
1. **表格预测单条推理可解释** （盘古融合推荐回归大模型、盘古融合推荐分类大模型、盘古统一编码表格预测回归大模型、盘古统一编码表格预测分类大模型）
   基本原理：Shapley 值源自合作博弈论，通过计算某特征在所有可能特征组合顺序下的平均边际贡献，公平地分配模型预测结果至各个输入特征。其具备数学上的严谨性与可加性，满足：
   - 贡献归因的公平性。
   
   - 所有特征 Shapley 值之和等于当前样本预测值与基准值（背景数据平均预测）的差。
   
   
   该方法可为任意模型提供局部可解释性，适用于复杂黑盒模型的决策归因分析。
   
2. **时序预测单条推理可解释** （盘古统一编码时序预测分类大模型、盘古统一编码时序预测回归大模型）
   基本原理：KernelShap 是一种基于 Shapley 值理论的模型解释方法，用于评估特征在预测结果中的重要性。其核心思想是利用核密度估计技术来近似计算 Shapley 值，从而为模型的预测提供可解释性。KernelShap 通过在特征空间中引入核函数来计算不同特征组合的权重，从而估计各个特征对模型预测结果的平均边际贡献。这种方法继承了 Shapley 值的公平性和可加性，确保在解释过程中，所有特征的 Shapley 值之和精确地等于模型预测值与基准值之间的差异。
   KernelShap 的优势在于：
   - 灵活性：适用于各种模型类型，包括黑盒模型，提供局部解释。
   
   - 数学严谨性：通过核函数的引入，能够更灵活地处理特征之间的复杂关系。
   
   - 公平性：确保每个特征的贡献程度是公平且准确的。
   
   
   与传统 Shapley 值计算方法相比，KernelShap 通过核密度估计有效降低了计算复杂度，同时保留了 Shapley 值理论的优点，使得特征重要性分析更为高效且可靠。
   
 
#### 预测置信度
盘古融合推荐异常检测大模型和盘古融合推荐分类大模型支持预测时输出置信度（即每种结果的概率值），详见《API参考》"API \> 模型推理 \> 模型推理接口 \> 预测大模型 \> 盘古融合推荐异常检测大模型"和"API \> 模型推理 \> 模型推理接口 \> 预测大模型 \> 盘古融合推荐分类大模型"。