Skip to content

Python SDK 开发指南 ​

Habitaxx 官方提供的 Python 服务端 SDK,封装了开放平台的全量 AI 能力与管理能力,采用类型安全的设计,内置自动序列化、分步凭证置换与统一错误码解析机制。

SDK 仓库与源码:sdk/habitaxx-python


1. 安装与准备 ​

安装方式 ​

bash
# 从源码或私有源安装
pip install habitaxx

依赖环境 ​

  • Python 3.8 及以上版本
  • 依赖 httpx、pydantic 等现代 HTTP 与数据校验库

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"
}

客户端初始化示例 ​

python
import os
from habitaxx import Habitaxx

# 平台颁发的 API Key 与项目信息(示例凭据已打码,请替换为真实凭证)
API_KEY = "qj_live_your_api_key"
PROJECT_NO = "prj_your_project_no"
USER_ID = "user_123456"
BASE_URL = "https://open-api.habitaxx.com"

# -------------------------------------------------------------
# 步骤 1:初始化认证客户端,换取 Access Token
# -------------------------------------------------------------
auth_client = Habitaxx(
    api_key="placeholder",  # 认证阶段占位符
    base_url=BASE_URL,
)

token_resp = auth_client.auth.token(
    x_api_key=API_KEY,
    project_no=PROJECT_NO,
    user_id=USER_ID,
)

if token_resp.code != 200:
    print(f"换取 Token 失败: code={token_resp.code}, error_code={token_resp.error_code}, call_id={token_resp.call_id}")
    exit(1)

access_token = token_resp.data.access_token
print(f"成功获取 Access Token: {access_token[:20]}...,call_id: {token_resp.call_id}")

# -------------------------------------------------------------
# 步骤 2:使用 access_token 初始化业务客户端
# -------------------------------------------------------------
client = Habitaxx(
    api_key=access_token,
    base_url=BASE_URL,
)

3. 鸟类多模态识别 (client.bird) ​

类:BirdResource / 异步类:AsyncBirdResource

提供高精度的鸟类物种多模态检测与细粒度分类算法,支持输入各种常见鸟类图片,输出物体检测定位边框(BBox)、顶级 Top-5 置信度分类以及中英文物种名。

核心方法签名 ​

python
def detect(
    self,
    *,
    file: FileTypes,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: float | httpx.Timeout | None | NotGiven = not_given,
) -> BirdDetectResponse

参数说明 ​

参数名类型是否必填描述
fileFileTypes (bytes, IO[bytes], PathLike, tuple)是待识别的鸟类图片,支持 JPG、PNG、WebP 等格式的二进制流或打开的文件对象。
timeoutfloat否单次请求超时时间(秒)。

返回结构 (BirdDetectResponse) ​

  • code (int): 状态码,200 表示处理成功。
  • message (str): 响应描述信息。
  • call_id (str): 本次调用的平台全链路追踪 ID。
  • data (BirdDetectData):
    • height (int): 图像高度。
    • width (int): 图像宽度。
    • device (str): 模型推理计算设备(如 mps、cuda、cpu)。
    • annotated_image (str): 标注渲染后的 Base64 编码图片(带 Data URI 前缀)。
    • detections (list[BirdDetection]): 识别到的目标列表:
      • box (list[int]): 矩形边框坐标 [ymin, xmin, ymax, xmax]。
      • detector_confidence (float): 目标检测器置信度 (0~1)。
      • class_zh (str): 鸟类中文学名。
      • class_en (str): 鸟类英文学名。
      • class_key (str): 物种标识编码。
      • top5 (list[BirdTop5Item]): 置信度最高的前 5 个细粒度分类候选。

调用代码示例 ​

python
# 识别本地鸟类图片
with open("bird.jpg", "rb") as f:
    resp = client.bird.detect(file=f)

if resp.code == 200 and resp.data:
    print(f"图像尺寸: {resp.data.width}x{resp.data.height},检测到 {len(resp.data.detections)} 个目标")
    for det in resp.data.detections:
        print(f"物种: {det.class_zh} ({det.class_en}), 置信度: {det.classification_confidence:.4f}")
        print(f"边框坐标: {det.box}")
else:
    print(f"识别失败: {resp.message}, call_id={resp.call_id}")

4. IMU 姿态行为预测 (client.imu) ​

类:IMUResource / 异步类:AsyncIMUResource

基于项圈或可穿戴设备搭载的 6 轴 IMU 惯性测量单元时序数据,实时推断宠物的当前行为状态(如站立、坐姿、趴卧、行走、奔跑、喘息等)。

核心方法签名 ​

1. 全局行为预测 predict ​

python
def predict(
    self,
    *,
    samples: list[list[float]],
    top_k: int | NotGiven = not_given,
    device: str | NotGiven = not_given,
    model_version: str | NotGiven = not_given,
    part: str | NotGiven = not_given,
    window_seconds: int | NotGiven = not_given,
    ...
) -> PredictCreateResponse

2. 设备专属行为预测 predict_for_device ​

python
def predict_for_device(
    self,
    device_id: str,
    *,
    samples: list[list[float]],
    top_k: int | NotGiven = not_given,
    ...
) -> PredictForDeviceResponse

参数说明 ​

参数名类型是否必填描述
sampleslist[list[float]]是必须为 100 行 x 6 列的时序二维数组。每行包含 6 个浮点数,通道顺序严格要求为:[ANeck_x, ANeck_y, ANeck_z, GNeck_x, GNeck_y, GNeck_z]。
top_kint否返回候选置信度排名的数量,默认 5。
device_idstr是(仅限 predict_for_device)设备唯一序列号,用于设备级上下文追踪与行为校准。
partstr否佩戴部位,默认 neck(颈部)。
window_secondsint否采样时间窗秒数,默认 1。

返回结构说明 ​

  • code (int): 200 表示预测成功。
  • data:
    • latency_ms (float): 模型计算耗时(毫秒)。
    • prediction (object): 最高置信度行为结果:
      • class_index (int): 动作类别 ID。
      • name (str): 行为英文名称(如 Lying chest, Sitting, Standing, Walking)。
      • name_zh (str): 行为中文名(如 趴卧, 坐姿, 站立, 行走)。
      • confidence (float): 置信度 (0~1)。
    • top_k (list[object]): 置信度最高的前 K 个预测动作列表。
    • input_statistics (list[object]): 各轴最大值、最小值与均值统计。

调用代码示例 ​

python
# 构建 1 秒 100Hz 6 轴时序数据 (100 行 x 6 列)
mock_imu_samples = [
    [-0.3224, -0.4983, -0.6575, -32.2179, -21.9678, 1.3306]
] * 100

# 调用预测
res = client.imu.predict(
    samples=mock_imu_samples,
    top_k=5,
)

if res.code == 200:
    pred = res.data.prediction
    print(f"推断行为: {pred.name_zh} ({pred.name}), 置信度: {pred.confidence:.4f}")
    print(f"推理耗时: {res.data.latency_ms:.2f} ms")

5. 宠物档案管理 (client.pet_profiles) ​

类:PetProfilesResource / 异步类:AsyncPetProfilesResource

提供宠物生命周期与健康画像的建立、维护、查询与档案同步。

核心方法列表 ​

方法名HTTP 路径功能说明核心参数
list_breedsGET /v1/ms-ai-fast/pet-breeds查询支持的宠物种类及细分品种字典pet_type: int | str (1: 狗, 2: 猫, 3: 鸟类)
createPOST /v1/ms-ai-fast/pet-profiles创建新的宠物档案body: { pet_name, pet_type, breed, gender, birth_date, weight, is_sterilized, avatar_url }
listGET /v1/ms-ai-fast/pet-profiles分页查询当前名下的宠物档案列表page: int, page_size: int, pet_type: str
getGET /v1/ms-ai-fast/pet-profiles/{id}获取指定 ID 宠物的详细档案pet_id: str
updatePATCH /v1/ms-ai-fast/pet-profiles/{id}更新宠物基本信息或生理体征pet_id: str, body: dict
deleteDELETE /v1/ms-ai-fast/pet-profiles/{id}软删除或注销指定宠物档案pet_id: str
get_pet_infoGET /v1/ms-ai-fast/pets/pet-info快捷获取宠物的健康信息与医疗画像pet_id: int | str

调用代码示例 ​

python
# 1. 查询品种字典
breeds = client.pet_profiles.list_breeds(pet_type=1)
print("犬类支持品种:", breeds)

# 2. 创建宠物档案
new_pet = client.pet_profiles.create(
    body={
        "pet_name": "麦克",
        "pet_type": "dog",
        "breed": "金毛寻回犬",
        "gender": "male",
        "birth_date": "2023-05-12",
        "weight": 28.5,
        "is_sterilized": True,
    }
)
pet_id = new_pet.get("data", {}).get("id")
print("宠物档案创建成功, ID:", pet_id)

# 3. 分页查询宠物列表
pet_list = client.pet_profiles.list(page=1, page_size=10)
print(f"当前宠物总数: {pet_list.get('data', {}).get('total')}")

6. 宠物智能问诊 (client.consultation) ​

类:ConsultationResource / 异步类:AsyncConsultationResource

基于大语言模型与宠物医疗专家知识库,提供全流程智能导诊、多轮主诉问询、患处图片诊断、关联症状追问与最终医疗健康报告生成。

核心方法列表 ​

方法名HTTP 路径功能说明核心入参说明
pre_questionGET /v1/ms-ai-fast/ai-consultation/pre-question获取预问诊指引与推荐问题模板pet_type: int | str (宠物种类)
create_sessionPOST /v1/ms-ai-fast/ai-consultation/sessions初始化新一轮智能问诊会话body: { pet_id, source }
keywordsPOST /v1/ms-ai-fast/ai-consultation/keywords提取用户主诉文本中的医疗核心症状词body: { question }
reason_infoPOST /v1/ms-ai-fast/ai-consultation/reason-info查询当前症状可能的潜在病因与生理背景body: { question, pet_type }
analysisPOST /v1/ms-ai-fast/ai-consultation/analysis核心对话推理,返回 AI 医生诊断与医疗建议body: { session_id, question, image_urls }
related_questionPOST /v1/ms-ai-fast/ai-consultation/related-question生成建议宠主进一步了解的关联延伸问题body: { session_id, question }
if_continue_askPOST /v1/ms-ai-fast/ai-consultation/if-continue-ask评估病情是否需要引导用户继续深入追问body: { session_id, question }
if_need_imagePOST /v1/ms-ai-fast/ai-consultation/if-need-image智能判定当前症状是否建议上传患处图片辅诊body: { session_id, question }
pic_resultPOST /v1/ms-ai-fast/ai-consultation/pic-result对宠主上传的患处局部图片进行图文会诊body: { session_id, image_url }
summaryPOST /v1/ms-ai-fast/ai-consultation/summary对当前多轮问诊对话生成病情总结body: { session_id }
reportPOST /v1/ms-ai-fast/ai-consultation/report触发异步生成正式电子问诊分析报告body: { session_id }
get_taskGET /v1/ms-ai-fast/ai-consultation/tasks/{task_id}查询异步报告生成任务的执行进度与结果task_id: str
get_medical_recordGET /v1/ms-ai-fast/ai-consultation/medical-records获取已归档的历史电子病历记录session_id: str 或 record_id: int
save_messagePOST /v1/ms-ai-fast/ai-consultation/messages归档单条问答交互消息记录body: { session_id, role, content }
list_messagesGET /v1/ms-ai-fast/ai-consultation/messages获取会话内完整历史对话上下文session_id: str

完整会话调用示例 ​

python
# 1. 开启问诊会话
session = client.consultation.create_session(body={"pet_id": 1, "source": "api"})
session_id = session["data"]["session_id"]
print(f"会话创建成功: {session_id}")

# 2. 宠主陈述病情并进行 AI 推理分析
analysis_result = client.consultation.analysis(
    body={
        "session_id": session_id,
        "question": "我家金毛今天早上吐了两次黄色泡沫,精神不太好,不肯吃狗粮",
        "image_urls": []
    }
)
reply = analysis_result.get("data", {}).get("reply")
print(f"AI 医生回答:\n{reply}\n")

# 3. 判断是否需要引导拍照片
need_img = client.consultation.if_need_image(
    body={"session_id": session_id, "question": "呕吐物里没有明显异物"}
)
print("是否需要上传患处/呕吐物照片:", need_img.get("data", {}).get("need_image"))

# 4. 生成电子健康报告
report_res = client.consultation.report(body={"session_id": session_id})
print("报告生成任务已提交:", report_res)

7. 宠物图像多模态分析 (client.image_recognition) ​

类:ImageRecognitionResource / 异步类:AsyncImageRecognitionResource

专门针对宠物皮肤病、眼部疾病、耳道红肿、粪便形态等视觉表征提供快速分类总结、流式报告生成与病历归档。

核心方法列表 ​

方法名HTTP 路径功能说明核心入参说明
summaryPOST /v1/ms-ai-fast/ai-pic/summary单张患处图片快速识别与病情总结(同步)body: { image_url, pet_type }
summary_streamPOST /v1/ms-ai-fast/ai-pic/summary-stream图像多模态推理并以 SSE 流式输出逐字回答body: { image_url, pet_type }
submit_report_taskPOST /v1/ms-ai-fast/ai-pic/sessions/report-tasks提交生成图文健康诊断报告的异步任务body: { record_id, report_type }
create_sessionPOST /v1/ms-ai-fast/ai-pic/sessions创建图片识别专属会话body: { pet_id, category }
get_questionPOST /v1/ms-ai-fast/ai-pic/question根据视觉初筛结果获取定向排查问题body: { record_id }
get_optionsPOST /v1/ms-ai-fast/ai-pic/options获取症状选择题选项,辅助宠主精确定位body: { question_id }
validatePOST /v1/ms-ai-fast/ai-pic/validate校验上传图片清晰度、拍摄部位是否合规body: { image_url }
get_recordGET /v1/ms-ai-fast/medical-records/{record_id}查询图像识别生成的医疗报告档案record_id: str

调用代码示例 ​

python
# 快速识别患处照片
summary_resp = client.image_recognition.summary(
    body={
        "image_url": "https://cdn.example.com/pet_skin_problem.jpg",
        "pet_type": "dog"
    }
)
print("视觉诊断总结:", summary_resp)

8. 音视频多模态分析 (client.multimedia) ​

类:MultimediaResource / 异步类:AsyncMultimediaResource

支持视频与音频等多媒体深度分析,包括宠物行为与异常姿态视频理解、宠物声音与叫声情绪识别等。

核心方法列表 ​

方法名HTTP 路径功能说明核心入参说明
submit_video_taskPOST /v1/ms-ai-fast/ai-video/analysis-tasks提交视频异常姿态与行为分析异步任务body: { video_url, pet_type, detect_types }
get_video_resultGET /v1/ms-ai-fast/ai-video/result轮询/获取视频分析任务的报告与时序事件task_id: str
submit_voice_taskPOST /v1/ms-ai-fast/ai-voice/analysis-tasks提交宠物音频情绪与叫声翻译异步任务body: { audio_url, pet_type }
get_voice_resultGET /v1/ms-ai-fast/ai-voice/result查询声音分析报告与情绪指数task_id: str
stream_voice_analysisPOST /v1/ms-ai-fast/ai-voice/analysis宠物声音即时分析(流式推理)body: { audio_url, pet_type }

调用代码示例 ​

python
# 提交宠物步态视频分析任务
task = client.multimedia.submit_video_task(
    body={
        "video_url": "https://cdn.example.com/pet_running.mp4",
        "pet_type": "dog"
    }
)
task_id = task.get("data", {}).get("task_id")
print("视频任务已提交,Task ID:", task_id)

# 轮询获取结果
result = client.multimedia.get_video_result(task_id=task_id)
print("分析状态:", result.get("data", {}).get("status"))

9. 媒体与文件存储 (client.oss) ​

类:OssResource / 异步类:AsyncOssResource

为便于开发者快速上传大体积图片、声音录音或监控视频片段,SDK 提供了直传对象存储服务。

核心方法列表 ​

方法名HTTP 路径描述参数
upload_imagePOST /v1/ms-ai-fast/oss/images上传图像文件,返回公网 CDN 访问 URLfile: FileTypes, prefix: str (可选存储目录前缀)
upload_audioPOST /v1/ms-ai-fast/oss/audios上传音频文件 (WAV, MP3 等)file: FileTypes, prefix: str
upload_videoPOST /v1/ms-ai-fast/oss/videos上传视频文件 (MP4, MOV 等)file: FileTypes, prefix: str

调用代码示例 ​

python
# 上传图片并直接用于问诊或视觉识别
with open("skin_lesion.jpg", "rb") as img:
    upload_res = client.oss.upload_image(file=img, prefix="consultation")

img_url = upload_res.get("data", {}).get("url")
print("上传完成, 访问 URL:", img_url)

10. 异步客户端支持 (AsyncHabitaxx) ​

所有同步方法均有完全一致的异步版本,适用于 FastAPI、Tornado、Sanic 等异步高并发 Web 框架:

python
import asyncio
from habitaxx import AsyncHabitaxx

async def main():
    async with AsyncHabitaxx(api_key="your_access_token") as client:
        with open("bird.jpg", "rb") as f:
            res = await client.bird.detect(file=f)
            print("异步调用鸟类识别结果:", res.data.detections)

asyncio.run(main())
最近更新

栖界开放平台 · API Documentation