一、python-damas包概述

python-damas（实际为damas-client）是DAMAS（Distributed Asset Management And Search）分布式资产管理系统的Python客户端库，用于与DAMAS服务器交互，实现数字资产元数据管理、分布式存储索引、跨平台数据检索等核心功能。DAMAS由PRIMCODE公司开发，广泛应用于影视动画制作（如《疯狂动物城》）、游戏开发、科研数据管理等领域。

核心功能

• 元数据CRUD：创建、读取、更新、删除JSON格式的元数据节点（Node）。
• 高级检索：支持键值对搜索、MongoDB查询语法、图遍历（关联节点查询）。
• 分布式连接：HTTP/HTTPS连接远程DAMAS服务器，支持认证（JWT）。
• 批量操作：批量创建/更新节点，提升数据处理效率。
• 时间戳与审计：自动记录创建时间、作者，支持版本追溯。

二、安装方法

1. 依赖安装

damas-client依赖requests库，先安装依赖：

pip install requests
# 或系统级安装（Debian/Ubuntu）
sudo apt install python-requests

2. 安装damas-client

注意：PyPI无官方python-damas包，需从源码安装：

# 克隆仓库
git clone https://github.com/remyla/damas-core.git
cd damas-core/py
# 安装
python setup.py install

3. 验证安装

import damas_client
print(damas_client.__version__)  # 输出版本号即成功

三、核心语法与参数

1. 连接服务器

import damas_client

# 连接公共演示服务器（无认证）
project=damas_client.http_connection("https://demo.damas.io")

# 连接私有服务器（带认证）
# project=damas_client.http_connection("https://your-damas-server.com", token="your-jwt-token")

参数：

• url：DAMAS服务器地址（必填）。
• token：JWT认证令牌（可选，私有服务器需提供）。

2. 核心方法

（1）create()：创建节点

# 创建单个节点
node=project.create({"name": "asset1", "type": "model", "size": 1024})

# 批量创建节点
nodes=project.create([
    {"name": "asset2", "type": "texture"},
    {"name": "asset3", "type": "animation"}
])

参数：

• elements：字典或字典列表（必填），元数据键值对。
• 保留键：_id（自定义ID，自动生成）、time（时间戳）、author（作者）。

（2）read()：读取节点

# 通过ID读取单个节点
node=project.read("55ae0b1ed81e88357d77d0e9")

# 批量读取节点
nodes=project.read(["id1", "id2", "id3"])

参数：

• ids：字符串或字符串列表（必填），节点ID。

（3）update()：更新节点

# 更新单个节点
updated_node=project.update({"_id": "55ae0b1ed81e88357d77d0e9", "size": 2048})

参数：

• element：字典（必填），必须包含_id键。

（4）upsert()：创建或更新节点

# 存在则更新，不存在则创建
node=project.upsert({"_id": "custom_id", "name": "asset4"})

（5）delete()：删除节点

# 删除单个节点
project.delete("55ae0b1ed81e88357d77d0e9")

# 批量删除节点
project.delete(["id1", "id2"])

（6）search()：搜索节点

# 键值对搜索（返回ID列表）
ids=project.search("name:asset1")

# 多条件搜索
ids=project.search("type:model AND size:>1000")

（7）search_mongo()：MongoDB语法搜索

# 复杂查询（返回节点列表）
nodes=project.search_mongo({"type": "model", "size": {"$gt": 1000}})

四、8个实际应用案例

案例1：影视资产元数据管理

场景：动画工作室管理3D模型、贴图、动画文件元数据。

import damas_client
import time

# 连接服务器
proj=damas_client.http_connection("https://demo.damas.io")

# 定义资产元数据
assets = [
    {"name": "character_model", "type": "3d_model", "format": "fbx", "size": 5242880, "project": "film_a"},
    {"name": "character_texture", "type": "texture", "format": "png", "size": 2097152, "project": "film_a"},
    {"name": "scene_animation", "type": "animation", "format": "bvh", "size": 10485760, "project": "film_a"}
]

# 批量创建资产节点
created_assets=proj.create(assets)
print("创建资产：", created_assets)

# 搜索film_a项目的所有3D模型
model_ids=proj.search("project:film_a AND type:3d_model")
print("找到3D模型ID：", model_ids)

案例2：科研数据索引与检索

场景：实验室管理实验数据文件，支持按实验类型、日期检索。

import damas_client
from datetime import datetime

proj=damas_client.http_connection("https://demo.damas.io")

# 录入实验数据元数据
exp_data = [
    {"exp_id": "exp_001", "type": "chemistry", "date": "2026-05-01", "file_path": "/data/exp001.csv", "size": 102400},
    {"exp_id": "exp_002", "type": "physics", "date": "2026-05-02", "file_path": "/data/exp002.npy", "size": 204800}
]
proj.create(exp_data)

# 检索2026-05-01的化学实验数据
result=proj.search_mongo({
    "type": "chemistry",
    "date": "2026-05-01"
})
print("检索结果：", result)

案例3：游戏资源版本控制

场景：游戏开发中管理角色皮肤、场景道具的多版本元数据。

import damas_client

proj=damas_client.http_connection("https://demo.damas.io")

# 创建v1版本皮肤
v1_skin=proj.create({
    "name": "hero_skin",
    "version": "v1",
    "type": "skin",
    "status": "published"
})

# 更新为v2版本（upsert自动处理）
v2_skin=proj.upsert({
    "_id": v1_skin["_id"],
    "version": "v2",
    "status": "beta"
})

# 查询所有beta状态的皮肤
beta_skins=proj.search("status:beta AND type:skin")
print("Beta皮肤ID：", beta_skins)

案例4：分布式文件系统索引

场景：跨服务器文件共享，通过元数据索引快速定位文件位置。

import damas_client

proj=damas_client.http_connection("https://demo.damas.io")

# 记录分布式文件位置
files = [
    {"file_name": "report.pdf", "server": "server_01", "path": "/shared/report.pdf", "size": 524288},
    {"file_name": "data.zip", "server": "server_02", "path": "/shared/data.zip", "size": 10485760}
]
proj.create(files)

# 查找report.pdf的存储服务器
report_ids=proj.search("file_name:report.pdf")
report=proj.read(report_ids[0])
print("报告存储服务器：", report["server"])

案例5：用户行为日志存储与分析

场景：网站用户行为日志（如登录、点击）元数据存储，支持快速统计。

import damas_client
import random

proj=damas_client.http_connection("https://demo.damas.io")

# 模拟用户行为日志
logs = []
for i in range(100):
    logs.append({
        "user_id": random.randint(1, 10),
        "action": random.choice(["login", "click", "purchase"]),
        "timestamp": time.time(),
        "page": random.choice(["home", "product", "cart"])
    })
proj.create(logs)

# 统计用户1的所有购买行为
purchase_count=len(proj.search_mongo({
    "user_id": 1,
    "action": "purchase"
}))
print("用户1购买次数：", purchase_count)

案例6：IoT设备数据管理

场景：物联网设备（传感器、摄像头）采集数据的元数据管理。

import damas_client
import time

proj=damas_client.http_connection("https://demo.damas.io")

# 模拟传感器数据元数据
sensor_data = [
    {"device_id": "sensor_001", "type": "temperature", "value": 25.6, "timestamp": time.time(), "location": "room_01"},
    {"device_id": "sensor_002", "type": "humidity", "value": 60.2, "timestamp": time.time(), "location": "room_01"}
]
proj.create(sensor_data)

# 查询room_01的所有温度数据
temp_data=proj.search_mongo({
    "location": "room_01",
    "type": "temperature"
})
print("温度数据：", temp_data)

案例7：文档协作管理

场景：团队文档（Word、Excel）协作，记录文档作者、版本、修改时间。

import damas_client
from datetime import datetime

proj=damas_client.http_connection("https://demo.damas.io")

# 创建文档元数据
doc=proj.create({
    "title": "project_plan",
    "type": "document",
    "format": "docx",
    "author": "user_01",
    "version": "v1.0",
    "modified": datetime.now().strftime("%Y-%m-%d %H:%M:%S")
})

# 更新文档版本
updated_doc=proj.upsert({
    "_id": doc["_id"],
    "version": "v1.1",
    "modified": datetime.now().strftime("%Y-%m-%d %H:%M:%S")
})

# 查询user_01的所有文档
user_docs=proj.search("author:user_01 AND type:document")
print("用户文档ID：", user_docs)

案例8：媒体内容管理

场景：短视频平台管理视频、音频、图片元数据，支持按标签、时长检索。

import damas_client

proj=damas_client.http_connection("https://demo.damas.io")

# 媒体元数据
media = [
    {"name": "video_001", "type": "video", "duration": 60, "tags": ["funny", "short"], "size": 52428800},
    {"name": "audio_001", "type": "audio", "duration": 180, "tags": ["music", "pop"], "size": 10485760}
]
proj.create(media)

# 检索时长<120秒的搞笑视频
funny_videos=proj.search_mongo({
    "type": "video",
    "duration": {"$lt": 120},
    "tags": "funny"
})
print("搞笑视频：", funny_videos)

五、常见错误与解决方法

1. 连接错误：requests.exceptions.SSLError

• 原因：服务器SSL证书无效或未配置HTTPS。
• 解决：
  • 私有服务器配置有效SSL证书（使用Let’s Encrypt生成）。
  • 测试环境可关闭SSL验证（不推荐生产环境）：

    import requests
    requests.packages.urllib3.disable_warnings(requests.exceptions.InsecureRequestWarning)
    

2. 认证错误：401 Unauthorized

• 原因：JWT令牌过期、无效或未提供。
• 解决：
  • 重新生成有效JWT令牌（联系服务器管理员）。
  • 连接时正确传入token参数。

3. 节点不存在错误：404 Not Found

• 原因：读取/更新/删除的节点ID不存在。
• 解决：
  • 检查节点ID是否正确（通过search方法确认ID存在）。
  • 使用upsert替代update避免不存在报错。

4. 批量创建失败：500 Internal Server Error

• 原因：批量数据过大（超过服务器限制）或格式错误。
• 解决：
  • 拆分批量数据（每次不超过100条）。
  • 检查数据格式（确保为JSON可序列化字典）。

5. 搜索无结果

• 原因：搜索语法错误、键名大小写不匹配、数据未创建。
• 解决：
  • 检查搜索语法（键名:值，如name:asset1）。
  • 确认键名大小写（DAMAS区分大小写）。
  • 先调用create确保数据已存入服务器。

六、使用注意事项

1. 数据格式规范：元数据必须为JSON可序列化字典，避免特殊字符（如\n、\t）。
2. ID管理：自定义_id建议使用唯一路径式（如/project/asset1），避免重复。
3. 性能优化：
   • 批量操作优先使用create/upsert批量接口，减少请求次数。
   • 复杂查询使用search_mongo（MongoDB索引优化）。
4. 安全建议：
   • 生产环境必须使用HTTPS连接，配置有效SSL证书。
   • 敏感数据（如密码）禁止存入元数据，使用JWT认证控制访问权限。
5. 服务器部署：私有DAMAS服务器需配置MongoDB（默认后端），确保数据库正常运行。

《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。