Go SDK 开发指南
Habitaxx 官方提供的 Go 服务端 SDK,封装了开放平台的全量 AI 能力与管理能力,提供强类型参数构建器、上下文(context.Context)支持及统一的响应与错误处理机制。
SDK 源码目录:sdk/habitaxx-go
1. 安装与准备
安装方式
bash
go get -u github.com/habitaxx/habitaxx-go依赖环境
- Go 1.18 及以上版本
2. 认证体系与调用规范
开放平台采用两阶段凭证安全模型:
- 第一阶段(换取 Access Token):使用开发者 API Key(持久凭据)和项目/终端用户标识,调用
/v1/auth/token接口换取短效access_token(JWT,有效期通常为 24 小时)。 - 第二阶段(调用业务能力):使用获取到的
access_token初始化业务客户端,调用具体 AI 能力接口。网关将对 Token 进行鉴权与限流计量。
统一响应与错误排查
开放平台对外接口统一响应 HTTP 200 状态码,实际调用结果由响应体的 code 与业务字段呈现:
json
{
"code": 200,
"message": "success",
"data": { ... },
"call_id": "call_6a96d6bda27ff05dee01244b314e5662"
}当接口鉴权失败、参数错误或限流时,HTTP 状态码依然保持 200,并返回平台标准错误码结构:
json
{
"code": 10002,
"error_code": "INVALID_API_KEY",
"message": "API Key 无效",
"data": null,
"call_id": "call_6a96d6bda27ff05dee01244b314e5662"
}所有系统级与业务级异常均已收敛脱敏,客户端可直接通过 call_id 向平台技术支持反馈追踪。
3. 完整调用示例
go
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/habitaxx/habitaxx-go"
"github.com/habitaxx/habitaxx-go/option"
)
func main() {
ctx := context.Background()
// 开发者凭据(示例已脱敏)
apiKey := "qj_live_your_api_key_here"
projectNo := "prj_your_project_no_here"
userID := "user_unique_identifier_123"
// 1. 初始化认证客户端
authClient := habitaxx.NewClient(
option.WithAPIKey("placeholder"),
option.WithBaseURL("https://open-api.habitaxx.com"),
)
// 2. 换取短效 Access Token
tokenResp, err := authClient.Auth.Token(ctx, habitaxx.AuthTokenParams{
XAPIKey: habitaxx.F(apiKey),
ProjectNo: habitaxx.F(projectNo),
UserID: habitaxx.F(userID),
})
if err != nil {
log.Fatalf("换取 Token 失败: %v", err)
}
accessToken := tokenResp.Data.AccessToken
fmt.Printf("成功获取 Access Token: %s
", accessToken)
// 3. 使用 Access Token 初始化业务客户端
client := habitaxx.NewClient(
option.WithAPIKey(accessToken),
option.WithBaseURL("https://open-api.habitaxx.com"),
)
// 4. 调用 IMU 行为预测
imuResult, err := client.IMU.Predict(ctx, habitaxx.IMUPredictParams{
Samples: habitaxx.F([][]float64{
{-0.322, -0.498, -0.657, -32.217, -21.967, 1.33},
// 推荐连续传入 100 组 6 轴采样点 (1 秒时序数据)
}),
TopK: habitaxx.F(int64(5)),
})
if err != nil {
log.Fatalf("IMU 预测调用失败: %v", err)
}
fmt.Printf("预测行为: %s (置信度: %.2f)
", imuResult.Data.Prediction.NameZH, imuResult.Data.Prediction.Confidence)
// 5. 调用鸟类多模态识别
f, err := os.Open("./sample_bird.jpg")
if err != nil {
log.Fatalf("打开图像失败: %v", err)
}
defer f.Close()
birdResult, err := client.Bird.Detect(ctx, habitaxx.BirdDetectParams{
File: habitaxx.F(f),
})
if err != nil {
log.Fatalf("鸟类检测失败: %v", err)
}
fmt.Printf("检测到目标数量: %d
", len(birdResult.Data.Detections))
}4. 模块详细参考 (API Reference)
Habitaxx 客户端实例 client 包含以下资源模块对象:
| 模块属性 | 对应资源服务 | 描述 |
|---|---|---|
client.Auth | AuthService | 凭证交换与鉴权管理 |
client.IMU | IMUService | 智能项圈 IMU 行为时序多轴传感器算法识别 |
client.Bird | BirdService | 鸟类与野生动物多模态目标检测与细粒度物种识别 |
client.PetProfiles | PetProfilesService | 宠物档案管理(增删改查、品种列表与基本信息) |
client.Consultation | ConsultationService | 智能健康问诊与问答交互全流程 |
client.ImageRecognition | ImageRecognitionService | 宠物图像病症多模态识别与诊断总结 |
client.Multimedia | MultimediaService | 宠物视频行为理解、吠声意图翻译与音频多模态分析 |
client.OSS | OSSService | 开放平台媒体资源直传与转存对象存储服务 |
4.1 认证模块 (client.Auth)
用于凭据转换与短效令牌签发。
方法:Auth.Token(ctx, params, opts...)
- 方法签名:
Token(ctx context.Context, params AuthTokenParams, opts ...option.RequestOption) (*AuthTokenResponse, error) - 参数说明:
参数字段 类型 是否必填 描述 params.XAPIKeyparam.Field[string]是 平台颁发的永久 API Key(以 qj_live_开头)params.ProjectNoparam.Field[string]是 关联的项目编号(例如 prj_xxx)params.UserIDparam.Field[string]是 终端用户或设备唯一标识字符串 - 响应体结构:go
type AuthTokenResponse struct { Code int64 `json:"code"` Message string `json:"message"` Data AuthTokenResponseData `json:"data"` CallID string `json:"call_id"` }
4.2 IMU 行为预测模块 (client.IMU)
处理来自穿戴设备(如智能宠物项圈)的高频时序 6 轴加速度计与陀螺仪传感器数据,智能识别趴卧、行走、奔跑、玩耍等精细行为姿态。
方法 1:IMU.Predict(ctx, params, opts...)
通用 IMU 时序数据姿态预测。
- 方法签名:
Predict(ctx context.Context, params IMUPredictParams, opts ...option.RequestOption) (*IMUPredictResponse, error) - 参数说明:
参数字段 类型 是否必填 描述 params.Samplesparam.Field[[][]float64]是 6 轴传感器采样矩阵,格式为 [[ax, ay, az, gx, gy, gz], ...],通常建议 100 组(1 秒窗口)params.TopKparam.Field[int64]否 返回置信度前 K 个分类概率,默认 5params.Partparam.Field[string]否 佩戴部位(如 neck、back),默认neck - 响应字段: 包含输入统计
InputStatistics、主预测类别Prediction(ClassIndex,Name,NameZH,Confidence)、TopK概率列表及计算延迟等。
方法 2:IMU.PredictForDevice(ctx, deviceID, params, opts...)
指定硬件设备 ID 的 IMU 数据推理。
- 方法签名:
PredictForDevice(ctx context.Context, deviceID string, params IMUPredictParams, opts ...option.RequestOption) (*IMUPredictResponse, error) - 参数说明:
参数字段 类型 是否必填 描述 deviceIDstring是 硬件设备标识(如设备出厂 SN 码) paramsIMUPredictParams是 同 IMU.Predict参数
4.3 鸟类多模态识别模块 (client.Bird)
支持对野外或家庭环境拍摄的鸟类图像进行目标检测、边界框定位、物种精细分类(支持数百种常见鸟类)与 top-5 置信度评估。
方法:Bird.Detect(ctx, params, opts...)
上传并识别鸟类图像。
- 方法签名:
Detect(ctx context.Context, params BirdDetectParams, opts ...option.RequestOption) (*BirdDetectResponse, error) - 参数说明:
参数字段 类型 是否必填 描述 params.Fileparam.Field[io.Reader]是 图像文件流输入,支持 JPEG / PNG 格式 - 响应体结构:go
type BirdDetectResponse struct { Code int64 `json:"code"` Message string `json:"message"` Data BirdDetectResponseData `json:"data"` CallID string `json:"call_id"` }
4.4 宠物档案模块 (client.PetProfiles)
管理用户名下的宠物健康与基础生物档案(支持犬、猫及其他常见品种)。
| 方法名 | 签名与参数 | 描述 |
|---|---|---|
Create | Create(ctx, params PetProfileCreateParams, opts...) | 创建新宠物档案(含姓名、物种、品种、出生日期、绝育状态、体重等) |
List | List(ctx, params PetProfileListParams, opts...) | 分页查询当前用户/项目绑定的宠物列表 |
Get | Get(ctx, petID string, opts...) | 获取指定宠物的详细健康资料与档案 |
Update | Update(ctx, petID string, params PetProfileUpdateParams, opts...) | 修改并更新指定宠物档案字段 |
Delete | Delete(ctx, petID string, opts...) | 软删除或注销指定宠物档案 |
ListBreeds | ListBreeds(ctx, params PetProfileListBreedsParams, opts...) | 查询系统支持的标准宠物物种与细分品种字典 |
GetPetInfo | GetPetInfo(ctx, petID string, opts...) | 便捷获取宠物精简基础信息 |
4.5 智能问诊模块 (client.Consultation)
全流程智能宠物健康咨询与多轮对话系统。
| 方法名 | 签名与参数 | 描述 |
|---|---|---|
CreateSession | CreateSession(ctx, params ConsultationCreateSessionParams, opts...) | 开启新的问诊会话,获取 session_id |
Analysis | Analysis(ctx, params ConsultationAnalysisParams, opts...) | 主会话深度分析与问答回复 |
Keywords | Keywords(ctx, params ConsultationKeywordsParams, opts...) | 提取症状核心关键词与关联特征 |
PreQuestion | PreQuestion(ctx, params ConsultationPreQuestionParams, opts...) | 会话初期的预设追问与引导问题生成 |
ReasonInfo | ReasonInfo(ctx, params ConsultationReasonInfoParams, opts...) | 获取 AI 推理逻辑、鉴别诊断思路及医学依据 |
RelatedQuestion | RelatedQuestion(ctx, params ConsultationRelatedQuestionParams, opts...) | 生成用户可能感兴趣的延伸就诊建议与相关问题 |
IfContinueAsk | IfContinueAsk(ctx, params ConsultationIfContinueAskParams, opts...) | 评估当前病情描述是否完备,判断是否需要继续追问 |
IfNeedImage | IfNeedImage(ctx, params ConsultationIfNeedImageParams, opts...) | 判断当前体征是否需要引导用户拍摄并上传患处图像 |
PicResult | PicResult(ctx, params ConsultationPicResultParams, opts...) | 结合患处图像进行多模态综合病情判定 |
Summary | Summary(ctx, params ConsultationSummaryParams, opts...) | 生成咨询阶段总结与初步病情研判 |
Report | Report(ctx, params ConsultationReportParams, opts...) | 生成结构化完整电子病历与诊疗建议报告 |
GetTask | GetTask(ctx, taskID string, opts...) | 轮询异步问诊报告生成任务的执行进度 |
GetMedicalRecord | GetMedicalRecord(ctx, recordID string, opts...) | 获取归档病历报告的详情内容 |
SaveMessage | SaveMessage(ctx, params ConsultationSaveMessageParams, opts...) | 手动持久化问诊过程中的历史消息记录 |
ListMessages | ListMessages(ctx, params ConsultationListMessagesParams, opts...) | 检索指定问诊会话的历史完整对话记录 |
4.6 图像病症识别模块 (client.ImageRecognition)
面向宠物皮肤病、眼科、口腔及常见体表异状的多模态图像识别能力。
| 方法名 | 签名与参数 | 描述 |
|---|---|---|
Summary | Summary(ctx, params ImageRecognitionSummaryParams, opts...) | 针对上传病灶图像生成多模态诊断与风险评估总结 |
SummaryStream | SummaryStream(ctx, params ImageRecognitionSummaryStreamParams, opts...) | 以流式(Server-Sent Events)逐步输出诊断与病理分析文本 |
CreateReportTask | CreateReportTask(ctx, params ImageRecognitionCreateReportTaskParams, opts...) | 提交深度图像识别与结构化病症报告异步生成任务 |
GetReportTask | GetReportTask(ctx, taskID string, opts...) | 轮询异步图像识别任务的执行状态 |
GetMedicalRecord | GetMedicalRecord(ctx, recordID string, opts...) | 获取由图像识别生成的完整医疗报告记录 |
4.7 多媒体与音频模块 (client.Multimedia)
覆盖宠物视频动作识别、吠叫意图音频分析与长音频多模态理解。
| 方法名 | 签名与参数 | 描述 |
|---|---|---|
UnderstandVideo | UnderstandVideo(ctx, params MultimediaUnderstandVideoParams, opts...) | 提交宠物长/短视频行为理解与事件抽取异步任务 |
GetVideoResult | GetVideoResult(ctx, taskID string, opts...) | 获取视频理解任务分析结果与关键帧事件段落 |
TranslateSound | TranslateSound(ctx, params MultimediaTranslateSoundParams, opts...) | 提交犬吠、猫鸣等音频意图分析与情绪翻译任务 |
GetVoiceResult | GetVoiceResult(ctx, taskID string, opts...) | 查询宠物叫声翻译分析任务的执行结果 |
StreamVoiceAnalysis | StreamVoiceAnalysis(ctx, params MultimediaStreamVoiceAnalysisParams, opts...) | 流式获取音频声学特征识别与情绪反馈结果 |
4.8 资源直传模块 (client.OSS)
为多模态识别、音频分析和图像诊断提供便捷的对象存储凭据与文件直传。
| 方法名 | 签名与参数 | 描述 |
|---|---|---|
UploadImage | UploadImage(ctx, params OSSUploadParams, opts...) | 上传图片文件并返回合规的公网或签名访问 URL |
UploadAudio | UploadAudio(ctx, params OSSUploadParams, opts...) | 上传音频文件并返回可用访问 URL |
UploadVideo | UploadVideo(ctx, params OSSUploadParams, opts...) | 上传视频文件并返回可用访问 URL |
5. 错误处理与规范
SDK 将所有响应体统一按规范映射。当返回 code != 200 时,可从响应体中获取具体错误信息:
go
result, err := client.IMU.Predict(ctx, habitaxx.IMUPredictParams{
Samples: habitaxx.F([][]float64{}),
})
if err != nil {
// 处理网络传输、连接超时或 HTTP 协议级别异常
log.Fatalf("请求网络异常: %v", err)
}
// 业务状态码判断
if result.Code != 200 {
log.Printf("平台业务异常 [代码 %d / %s]: %s (call_id: %s)
",
result.Code, result.ErrorCode, result.Message, result.CallID)
}