Skip to content

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. 认证体系与调用规范 ​

开放平台采用两阶段凭证安全模型:

  1. 第一阶段(换取 Access Token):使用开发者 API Key(持久凭据)和项目/终端用户标识,调用 /v1/auth/token 接口换取短效 access_token(JWT,有效期通常为 24 小时)。
  2. 第二阶段(调用业务能力):使用获取到的 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.AuthAuthService凭证交换与鉴权管理
client.IMUIMUService智能项圈 IMU 行为时序多轴传感器算法识别
client.BirdBirdService鸟类与野生动物多模态目标检测与细粒度物种识别
client.PetProfilesPetProfilesService宠物档案管理(增删改查、品种列表与基本信息)
client.ConsultationConsultationService智能健康问诊与问答交互全流程
client.ImageRecognitionImageRecognitionService宠物图像病症多模态识别与诊断总结
client.MultimediaMultimediaService宠物视频行为理解、吠声意图翻译与音频多模态分析
client.OSSOSSService开放平台媒体资源直传与转存对象存储服务

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 个分类概率,默认 5
    params.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) ​

管理用户名下的宠物健康与基础生物档案(支持犬、猫及其他常见品种)。

方法名签名与参数描述
CreateCreate(ctx, params PetProfileCreateParams, opts...)创建新宠物档案(含姓名、物种、品种、出生日期、绝育状态、体重等)
ListList(ctx, params PetProfileListParams, opts...)分页查询当前用户/项目绑定的宠物列表
GetGet(ctx, petID string, opts...)获取指定宠物的详细健康资料与档案
UpdateUpdate(ctx, petID string, params PetProfileUpdateParams, opts...)修改并更新指定宠物档案字段
DeleteDelete(ctx, petID string, opts...)软删除或注销指定宠物档案
ListBreedsListBreeds(ctx, params PetProfileListBreedsParams, opts...)查询系统支持的标准宠物物种与细分品种字典
GetPetInfoGetPetInfo(ctx, petID string, opts...)便捷获取宠物精简基础信息

4.5 智能问诊模块 (client.Consultation) ​

全流程智能宠物健康咨询与多轮对话系统。

方法名签名与参数描述
CreateSessionCreateSession(ctx, params ConsultationCreateSessionParams, opts...)开启新的问诊会话,获取 session_id
AnalysisAnalysis(ctx, params ConsultationAnalysisParams, opts...)主会话深度分析与问答回复
KeywordsKeywords(ctx, params ConsultationKeywordsParams, opts...)提取症状核心关键词与关联特征
PreQuestionPreQuestion(ctx, params ConsultationPreQuestionParams, opts...)会话初期的预设追问与引导问题生成
ReasonInfoReasonInfo(ctx, params ConsultationReasonInfoParams, opts...)获取 AI 推理逻辑、鉴别诊断思路及医学依据
RelatedQuestionRelatedQuestion(ctx, params ConsultationRelatedQuestionParams, opts...)生成用户可能感兴趣的延伸就诊建议与相关问题
IfContinueAskIfContinueAsk(ctx, params ConsultationIfContinueAskParams, opts...)评估当前病情描述是否完备,判断是否需要继续追问
IfNeedImageIfNeedImage(ctx, params ConsultationIfNeedImageParams, opts...)判断当前体征是否需要引导用户拍摄并上传患处图像
PicResultPicResult(ctx, params ConsultationPicResultParams, opts...)结合患处图像进行多模态综合病情判定
SummarySummary(ctx, params ConsultationSummaryParams, opts...)生成咨询阶段总结与初步病情研判
ReportReport(ctx, params ConsultationReportParams, opts...)生成结构化完整电子病历与诊疗建议报告
GetTaskGetTask(ctx, taskID string, opts...)轮询异步问诊报告生成任务的执行进度
GetMedicalRecordGetMedicalRecord(ctx, recordID string, opts...)获取归档病历报告的详情内容
SaveMessageSaveMessage(ctx, params ConsultationSaveMessageParams, opts...)手动持久化问诊过程中的历史消息记录
ListMessagesListMessages(ctx, params ConsultationListMessagesParams, opts...)检索指定问诊会话的历史完整对话记录

4.6 图像病症识别模块 (client.ImageRecognition) ​

面向宠物皮肤病、眼科、口腔及常见体表异状的多模态图像识别能力。

方法名签名与参数描述
SummarySummary(ctx, params ImageRecognitionSummaryParams, opts...)针对上传病灶图像生成多模态诊断与风险评估总结
SummaryStreamSummaryStream(ctx, params ImageRecognitionSummaryStreamParams, opts...)以流式(Server-Sent Events)逐步输出诊断与病理分析文本
CreateReportTaskCreateReportTask(ctx, params ImageRecognitionCreateReportTaskParams, opts...)提交深度图像识别与结构化病症报告异步生成任务
GetReportTaskGetReportTask(ctx, taskID string, opts...)轮询异步图像识别任务的执行状态
GetMedicalRecordGetMedicalRecord(ctx, recordID string, opts...)获取由图像识别生成的完整医疗报告记录

4.7 多媒体与音频模块 (client.Multimedia) ​

覆盖宠物视频动作识别、吠叫意图音频分析与长音频多模态理解。

方法名签名与参数描述
UnderstandVideoUnderstandVideo(ctx, params MultimediaUnderstandVideoParams, opts...)提交宠物长/短视频行为理解与事件抽取异步任务
GetVideoResultGetVideoResult(ctx, taskID string, opts...)获取视频理解任务分析结果与关键帧事件段落
TranslateSoundTranslateSound(ctx, params MultimediaTranslateSoundParams, opts...)提交犬吠、猫鸣等音频意图分析与情绪翻译任务
GetVoiceResultGetVoiceResult(ctx, taskID string, opts...)查询宠物叫声翻译分析任务的执行结果
StreamVoiceAnalysisStreamVoiceAnalysis(ctx, params MultimediaStreamVoiceAnalysisParams, opts...)流式获取音频声学特征识别与情绪反馈结果

4.8 资源直传模块 (client.OSS) ​

为多模态识别、音频分析和图像诊断提供便捷的对象存储凭据与文件直传。

方法名签名与参数描述
UploadImageUploadImage(ctx, params OSSUploadParams, opts...)上传图片文件并返回合规的公网或签名访问 URL
UploadAudioUploadAudio(ctx, params OSSUploadParams, opts...)上传音频文件并返回可用访问 URL
UploadVideoUploadVideo(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)
}
最近更新

栖界开放平台 · API Documentation