Python SDK 开发指南
Habitaxx 官方提供的 Python 服务端 SDK,封装了开放平台的全量 AI 能力与管理能力,采用类型安全的设计,内置自动序列化、分步凭证置换与统一错误码解析机制。
SDK 仓库与源码:sdk/habitaxx-python
1. 安装与准备
安装方式
# 从源码或私有源安装
pip install habitaxx依赖环境
- Python 3.8 及以上版本
- 依赖
httpx、pydantic等现代 HTTP 与数据校验库
2. 认证体系与调用规范
开放平台采用两阶段凭证安全模型:
- 第一阶段(换取 Access Token):使用开发者 API Key(持久凭据)和项目/终端用户标识,调用
/v1/auth/token接口换取短效access_token(JWT,有效期通常为 24 小时)。 - 第二阶段(调用业务能力):使用获取到的
access_token初始化业务客户端,调用具体 AI 能力接口。网关将对 Token 进行鉴权与限流计量。
统一响应与错误排查
开放平台对外接口统一响应 HTTP 200 状态码,实际调用结果由响应体的 code 与业务字段呈现:
{
"code": 200,
"message": "success",
"data": { ... },
"call_id": "call_6a96d6bda27ff05dee01244b314e5662"
}当接口鉴权失败、参数错误或限流时,HTTP 状态码依然保持 200,并返回平台标准错误码结构:
{
"code": 10002,
"error_code": "INVALID_API_KEY",
"message": "API Key 无效",
"data": null,
"call_id": "call_6a96d6bda27ff05dee01244b314e5662"
}客户端初始化示例
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 置信度分类以及中英文物种名。
核心方法签名
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参数说明
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
file | FileTypes (bytes, IO[bytes], PathLike, tuple) | 是 | 待识别的鸟类图片,支持 JPG、PNG、WebP 等格式的二进制流或打开的文件对象。 |
timeout | float | 否 | 单次请求超时时间(秒)。 |
返回结构 (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 个细粒度分类候选。
调用代码示例
# 识别本地鸟类图片
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
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,
...
) -> PredictCreateResponse2. 设备专属行为预测 predict_for_device
def predict_for_device(
self,
device_id: str,
*,
samples: list[list[float]],
top_k: int | NotGiven = not_given,
...
) -> PredictForDeviceResponse参数说明
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
samples | list[list[float]] | 是 | 必须为 100 行 x 6 列的时序二维数组。每行包含 6 个浮点数,通道顺序严格要求为:[ANeck_x, ANeck_y, ANeck_z, GNeck_x, GNeck_y, GNeck_z]。 |
top_k | int | 否 | 返回候选置信度排名的数量,默认 5。 |
device_id | str | 是(仅限 predict_for_device) | 设备唯一序列号,用于设备级上下文追踪与行为校准。 |
part | str | 否 | 佩戴部位,默认 neck(颈部)。 |
window_seconds | int | 否 | 采样时间窗秒数,默认 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]): 各轴最大值、最小值与均值统计。
调用代码示例
# 构建 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_breeds | GET /v1/ms-ai-fast/pet-breeds | 查询支持的宠物种类及细分品种字典 | pet_type: int | str (1: 狗, 2: 猫, 3: 鸟类) |
create | POST /v1/ms-ai-fast/pet-profiles | 创建新的宠物档案 | body: { pet_name, pet_type, breed, gender, birth_date, weight, is_sterilized, avatar_url } |
list | GET /v1/ms-ai-fast/pet-profiles | 分页查询当前名下的宠物档案列表 | page: int, page_size: int, pet_type: str |
get | GET /v1/ms-ai-fast/pet-profiles/{id} | 获取指定 ID 宠物的详细档案 | pet_id: str |
update | PATCH /v1/ms-ai-fast/pet-profiles/{id} | 更新宠物基本信息或生理体征 | pet_id: str, body: dict |
delete | DELETE /v1/ms-ai-fast/pet-profiles/{id} | 软删除或注销指定宠物档案 | pet_id: str |
get_pet_info | GET /v1/ms-ai-fast/pets/pet-info | 快捷获取宠物的健康信息与医疗画像 | pet_id: int | str |
调用代码示例
# 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_question | GET /v1/ms-ai-fast/ai-consultation/pre-question | 获取预问诊指引与推荐问题模板 | pet_type: int | str (宠物种类) |
create_session | POST /v1/ms-ai-fast/ai-consultation/sessions | 初始化新一轮智能问诊会话 | body: { pet_id, source } |
keywords | POST /v1/ms-ai-fast/ai-consultation/keywords | 提取用户主诉文本中的医疗核心症状词 | body: { question } |
reason_info | POST /v1/ms-ai-fast/ai-consultation/reason-info | 查询当前症状可能的潜在病因与生理背景 | body: { question, pet_type } |
analysis | POST /v1/ms-ai-fast/ai-consultation/analysis | 核心对话推理,返回 AI 医生诊断与医疗建议 | body: { session_id, question, image_urls } |
related_question | POST /v1/ms-ai-fast/ai-consultation/related-question | 生成建议宠主进一步了解的关联延伸问题 | body: { session_id, question } |
if_continue_ask | POST /v1/ms-ai-fast/ai-consultation/if-continue-ask | 评估病情是否需要引导用户继续深入追问 | body: { session_id, question } |
if_need_image | POST /v1/ms-ai-fast/ai-consultation/if-need-image | 智能判定当前症状是否建议上传患处图片辅诊 | body: { session_id, question } |
pic_result | POST /v1/ms-ai-fast/ai-consultation/pic-result | 对宠主上传的患处局部图片进行图文会诊 | body: { session_id, image_url } |
summary | POST /v1/ms-ai-fast/ai-consultation/summary | 对当前多轮问诊对话生成病情总结 | body: { session_id } |
report | POST /v1/ms-ai-fast/ai-consultation/report | 触发异步生成正式电子问诊分析报告 | body: { session_id } |
get_task | GET /v1/ms-ai-fast/ai-consultation/tasks/{task_id} | 查询异步报告生成任务的执行进度与结果 | task_id: str |
get_medical_record | GET /v1/ms-ai-fast/ai-consultation/medical-records | 获取已归档的历史电子病历记录 | session_id: str 或 record_id: int |
save_message | POST /v1/ms-ai-fast/ai-consultation/messages | 归档单条问答交互消息记录 | body: { session_id, role, content } |
list_messages | GET /v1/ms-ai-fast/ai-consultation/messages | 获取会话内完整历史对话上下文 | session_id: str |
完整会话调用示例
# 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 路径 | 功能说明 | 核心入参说明 |
|---|---|---|---|
summary | POST /v1/ms-ai-fast/ai-pic/summary | 单张患处图片快速识别与病情总结(同步) | body: { image_url, pet_type } |
summary_stream | POST /v1/ms-ai-fast/ai-pic/summary-stream | 图像多模态推理并以 SSE 流式输出逐字回答 | body: { image_url, pet_type } |
submit_report_task | POST /v1/ms-ai-fast/ai-pic/sessions/report-tasks | 提交生成图文健康诊断报告的异步任务 | body: { record_id, report_type } |
create_session | POST /v1/ms-ai-fast/ai-pic/sessions | 创建图片识别专属会话 | body: { pet_id, category } |
get_question | POST /v1/ms-ai-fast/ai-pic/question | 根据视觉初筛结果获取定向排查问题 | body: { record_id } |
get_options | POST /v1/ms-ai-fast/ai-pic/options | 获取症状选择题选项,辅助宠主精确定位 | body: { question_id } |
validate | POST /v1/ms-ai-fast/ai-pic/validate | 校验上传图片清晰度、拍摄部位是否合规 | body: { image_url } |
get_record | GET /v1/ms-ai-fast/medical-records/{record_id} | 查询图像识别生成的医疗报告档案 | record_id: str |
调用代码示例
# 快速识别患处照片
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_task | POST /v1/ms-ai-fast/ai-video/analysis-tasks | 提交视频异常姿态与行为分析异步任务 | body: { video_url, pet_type, detect_types } |
get_video_result | GET /v1/ms-ai-fast/ai-video/result | 轮询/获取视频分析任务的报告与时序事件 | task_id: str |
submit_voice_task | POST /v1/ms-ai-fast/ai-voice/analysis-tasks | 提交宠物音频情绪与叫声翻译异步任务 | body: { audio_url, pet_type } |
get_voice_result | GET /v1/ms-ai-fast/ai-voice/result | 查询声音分析报告与情绪指数 | task_id: str |
stream_voice_analysis | POST /v1/ms-ai-fast/ai-voice/analysis | 宠物声音即时分析(流式推理) | body: { audio_url, pet_type } |
调用代码示例
# 提交宠物步态视频分析任务
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_image | POST /v1/ms-ai-fast/oss/images | 上传图像文件,返回公网 CDN 访问 URL | file: FileTypes, prefix: str (可选存储目录前缀) |
upload_audio | POST /v1/ms-ai-fast/oss/audios | 上传音频文件 (WAV, MP3 等) | file: FileTypes, prefix: str |
upload_video | POST /v1/ms-ai-fast/oss/videos | 上传视频文件 (MP4, MOV 等) | file: FileTypes, prefix: str |
调用代码示例
# 上传图片并直接用于问诊或视觉识别
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 框架:
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())