1# tensor.h 2 3<!--Kit: MindSpore Lite Kit--> 4<!--Subsystem: AI--> 5<!--Owner: @zhuguodong8--> 6<!--Designer: @zhuguodong8; @jjfeing--> 7<!--Tester: @principal87--> 8<!--Adviser: @ge-yafang--> 9 10## 概述 11 12提供了张量相关的接口，可用于创建和修改张量信息，该接口是非线程安全的。 13 14**引用文件：** <mindspore/tensor.h> 15 16**库：** libmindspore_lite_ndk.so 17 18**系统能力：** SystemCapability.Ai.MindSpore 19 20**起始版本：** 9 21 22**相关模块：** [MindSpore](capi-mindspore.md) 23 24## 汇总 25 26### 结构体 27 28| 名称 | typedef关键字 | 描述 | 29|----|------------------------------------------------------------|----| 30| void * | [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) | 指向张量对象句柄。 | 31| void * | [OH_AI_AllocatorHandle](capi-mindspore-oh-ai-allocatorhandle.md) | 指向内存分配器对象句柄。 | 32 33### 函数 34 35| 名称 | 描述 | 36| -- | -- | 37| [OH_AI_API OH_AI_TensorHandle OH_AI_TensorCreate(const char *name, OH_AI_DataType type, const int64_t *shape,size_t shape_num, const void *data, size_t data_len)](#oh_ai_tensorcreate) | 创建一个张量对象。 | 38| [OH_AI_API void OH_AI_TensorDestroy(OH_AI_TensorHandle *tensor)](#oh_ai_tensordestroy) | 释放张量对象。 | 39| [OH_AI_API OH_AI_TensorHandle OH_AI_TensorClone(OH_AI_TensorHandle tensor)](#oh_ai_tensorclone) | 深拷贝一个张量。 | 40| [OH_AI_API void OH_AI_TensorSetName(OH_AI_TensorHandle tensor, const char *name)](#oh_ai_tensorsetname) | 设置张量的名称。 | 41| [OH_AI_API const char *OH_AI_TensorGetName(const OH_AI_TensorHandle tensor)](#oh_ai_tensorgetname) | 获取张量的名称。 | 42| [OH_AI_API void OH_AI_TensorSetDataType(OH_AI_TensorHandle tensor, OH_AI_DataType type)](#oh_ai_tensorsetdatatype) | 设置张量的数据类型。 | 43| [OH_AI_API OH_AI_DataType OH_AI_TensorGetDataType(const OH_AI_TensorHandle tensor)](#oh_ai_tensorgetdatatype) | 获取张量类型。 | 44| [OH_AI_API void OH_AI_TensorSetShape(OH_AI_TensorHandle tensor, const int64_t *shape, size_t shape_num)](#oh_ai_tensorsetshape) | 设置张量的形状。 | 45| [OH_AI_API const int64_t *OH_AI_TensorGetShape(const OH_AI_TensorHandle tensor, size_t *shape_num)](#oh_ai_tensorgetshape) | 获取张量的形状。 | 46| [OH_AI_API void OH_AI_TensorSetFormat(OH_AI_TensorHandle tensor, OH_AI_Format format)](#oh_ai_tensorsetformat) | 设置张量数据的排列方式。 | 47| [OH_AI_API OH_AI_Format OH_AI_TensorGetFormat(const OH_AI_TensorHandle tensor)](#oh_ai_tensorgetformat) | 获取张量数据的排列方式。 | 48| [OH_AI_API void OH_AI_TensorSetData(OH_AI_TensorHandle tensor, void *data)](#oh_ai_tensorsetdata) | 设置张量的数据。 | 49| [OH_AI_API const void *OH_AI_TensorGetData(const OH_AI_TensorHandle tensor)](#oh_ai_tensorgetdata) | 获取张量数据的指针。 | 50| [OH_AI_API void *OH_AI_TensorGetMutableData(const OH_AI_TensorHandle tensor)](#oh_ai_tensorgetmutabledata) | 获取可变的张量数据指针。如果数据为空则会开辟内存。 | 51| [OH_AI_API int64_t OH_AI_TensorGetElementNum(const OH_AI_TensorHandle tensor)](#oh_ai_tensorgetelementnum) | 获取张量元素数量。 | 52| [OH_AI_API size_t OH_AI_TensorGetDataSize(const OH_AI_TensorHandle tensor)](#oh_ai_tensorgetdatasize) | 获取张量中的数据的字节数大小。 | 53| [OH_AI_API OH_AI_Status OH_AI_TensorSetUserData(OH_AI_TensorHandle tensor, void *data, size_t data_size)](#oh_ai_tensorsetuserdata) | 设置张量为用户自行管理的数据。此接口常用于复用用户数据作为模型输入，可减少一次数据拷贝。<br> 注意：此数据对于张量来说是外部数据，张量销毁时不会主动释放，由调用者负责释放。另外，在此张量使用过程中，调用者须确保此数据有效。 | 54| [OH_AI_API OH_AI_AllocatorHandle OH_AI_TensorGetAllocator(OH_AI_TensorHandle tensor)](#oh_ai_tensorgetallocator) | 获取内存分配器。此接口主要是提供一种获取张量的内存分配器的方法。 | 55| [OH_AI_API OH_AI_Status OH_AI_TensorSetAllocator(OH_AI_TensorHandle tensor, OH_AI_AllocatorHandle allocator)](#oh_ai_tensorsetallocator) | 设置内存分配器。此接口主要是提供一种设置内存分配器的方法，tensor的内存将由这个分配器分配。 | 56 57## 函数说明 58 59### OH_AI_TensorCreate() 60 61``` 62OH_AI_API OH_AI_TensorHandle OH_AI_TensorCreate(const char *name, OH_AI_DataType type, const int64_t *shape,size_t shape_num, const void *data, size_t data_len) 63``` 64 65**描述** 66 67创建一个张量对象。 68 69**起始版本：** 9 70 71 72**参数：** 73 74| 参数项 | 描述 | 75| -- | -- | 76| const char *name | 张量名称。字符串长度跟随系统限制。 | 77| [OH_AI_DataType](capi-data-type-h.md#oh_ai_datatype) type | 张量的数据类型。 | 78| const int64_t *shape | 张量的维度数组。 | 79| size_t shape_num | 张量维度数组长度。 | 80| const void *data | 指向数据的指针。 | 81| size_t data_len | 数据的长度。 | 82 83**返回：** 84 85| 类型 | 说明 | 86|----------------------------------| -- | 87| OH_AI_API [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) | 指向张量对象句柄。 | 88 89### OH_AI_TensorDestroy() 90 91``` 92OH_AI_API void OH_AI_TensorDestroy(OH_AI_TensorHandle *tensor) 93``` 94 95**描述** 96 97释放张量对象。 98 99**起始版本：** 9 100 101 102**参数：** 103 104| 参数项 | 描述 | 105| -- | -- | 106| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) *tensor | 指向张量句柄的二级指针。 | 107 108### OH_AI_TensorClone() 109 110``` 111OH_AI_API OH_AI_TensorHandle OH_AI_TensorClone(OH_AI_TensorHandle tensor) 112``` 113 114**描述** 115 116深拷贝一个张量。 117 118**起始版本：** 9 119 120 121**参数：** 122 123| 参数项 | 描述 | 124| -- | -- | 125| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 126 127**返回：** 128 129| 类型 | 说明 | 130| -- | -- | 131| OH_AI_API [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) | 指向新张量对象句柄。 | 132 133### OH_AI_TensorSetName() 134 135``` 136OH_AI_API void OH_AI_TensorSetName(OH_AI_TensorHandle tensor, const char *name) 137``` 138 139**描述** 140 141设置张量的名称。 142 143**起始版本：** 9 144 145 146**参数：** 147 148| 参数项 | 描述 | 149| -- | -- | 150| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 151| const char *name | 张量名称。字符串长度跟随系统限制。 | 152 153### OH_AI_TensorGetName() 154 155``` 156OH_AI_API const char *OH_AI_TensorGetName(const OH_AI_TensorHandle tensor) 157``` 158 159**描述** 160 161获取张量的名称。 162 163**起始版本：** 9 164 165 166**参数：** 167 168| 参数项 | 描述 | 169| -- | -- | 170| const [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 171 172**返回：** 173 174| 类型 | 说明 | 175| -- | -- | 176| OH_AI_API const char * | 张量的名称。 | 177 178### OH_AI_TensorSetDataType() 179 180``` 181OH_AI_API void OH_AI_TensorSetDataType(OH_AI_TensorHandle tensor, OH_AI_DataType type) 182``` 183 184**描述** 185 186设置张量的数据类型。 187 188**起始版本：** 9 189 190 191**参数：** 192 193| 参数项 | 描述 | 194| -- | -- | 195| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 196| [OH_AI_DataType](capi-data-type-h.md#oh_ai_datatype) type | 数据类型，具体见[OH_AI_DataType](capi-data-type-h.md#oh_ai_datatype)。 | 197 198### OH_AI_TensorGetDataType() 199 200``` 201OH_AI_API OH_AI_DataType OH_AI_TensorGetDataType(const OH_AI_TensorHandle tensor) 202``` 203 204**描述** 205 206获取张量类型。 207 208**起始版本：** 9 209 210 211**参数：** 212 213| 参数项 | 描述 | 214| -- | -- | 215| const [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 216 217**返回：** 218 219| 类型 | 说明 | 220|----------------------------------------------------------------| -- | 221| OH_AI_API [OH_AI_DataType](capi-data-type-h.md#oh_ai_datatype) | 张量的数据类型。 | 222 223### OH_AI_TensorSetShape() 224 225``` 226OH_AI_API void OH_AI_TensorSetShape(OH_AI_TensorHandle tensor, const int64_t *shape, size_t shape_num) 227``` 228 229**描述** 230 231设置张量的形状。 232 233**起始版本：** 9 234 235 236**参数：** 237 238| 参数项 | 描述 | 239| -- | -- | 240| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 241| const int64_t *shape | 形状数组。 | 242| size_t shape_num | 张量形状数组长度。 | 243 244### OH_AI_TensorGetShape() 245 246``` 247OH_AI_API const int64_t *OH_AI_TensorGetShape(const OH_AI_TensorHandle tensor, size_t *shape_num) 248``` 249 250**描述** 251 252获取张量的形状。 253 254**起始版本：** 9 255 256 257**参数：** 258 259| 参数项 | 描述 | 260| -- | -- | 261| const [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 262| size_t *shape_num | 该参数是输出参数，形状数组的长度会写入该变量。 | 263 264**返回：** 265 266| 类型 | 说明 | 267| -- | -- | 268| OH_AI_API const int64_t * | 形状数组。 | 269 270### OH_AI_TensorSetFormat() 271 272``` 273OH_AI_API void OH_AI_TensorSetFormat(OH_AI_TensorHandle tensor, OH_AI_Format format) 274``` 275 276**描述** 277 278设置张量数据的排列方式。 279 280**起始版本：** 9 281 282 283**参数：** 284 285| 参数项 | 描述 | 286| -- | -- | 287| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 288| [OH_AI_Format](capi-format-h.md#oh_ai_format) format | 张量数据排列方式。 | 289 290### OH_AI_TensorGetFormat() 291 292``` 293OH_AI_API OH_AI_Format OH_AI_TensorGetFormat(const OH_AI_TensorHandle tensor) 294``` 295 296**描述** 297 298获取张量数据的排列方式。 299 300**起始版本：** 9 301 302 303**参数：** 304 305| 参数项 | 描述 | 306| -- | -- | 307| const [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 308 309**返回：** 310 311| 类型 | 说明 | 312|---------------------------------------------------------| -- | 313| OH_AI_API [OH_AI_Format](capi-format-h.md#oh_ai_format) | 张量数据的排列方式。 | 314 315### OH_AI_TensorSetData() 316 317``` 318OH_AI_API void OH_AI_TensorSetData(OH_AI_TensorHandle tensor, void *data) 319``` 320 321**描述** 322 323设置张量的数据。 324 325**起始版本：** 9 326 327 328**参数：** 329 330| 参数项 | 描述 | 331| -- | -- | 332| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 333| void *data | 指向数据的指针。 | 334 335### OH_AI_TensorGetData() 336 337``` 338OH_AI_API const void *OH_AI_TensorGetData(const OH_AI_TensorHandle tensor) 339``` 340 341**描述** 342 343获取张量数据的指针。 344 345**起始版本：** 9 346 347 348**参数：** 349 350| 参数项 | 描述 | 351| -- | -- | 352| const [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 353 354**返回：** 355 356| 类型 | 说明 | 357| -- | -- | 358| OH_AI_API const void * | 张量数据的指针。 | 359 360### OH_AI_TensorGetMutableData() 361 362``` 363OH_AI_API void *OH_AI_TensorGetMutableData(const OH_AI_TensorHandle tensor) 364``` 365 366**描述** 367 368获取可变的张量数据指针。如果数据为空则会开辟内存。 369 370**起始版本：** 9 371 372 373**参数：** 374 375| 参数项 | 描述 | 376| -- | -- | 377| const [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 378 379**返回：** 380 381| 类型 | 说明 | 382| -- | -- | 383| OH_AI_API void * | 张量数据的指针。 | 384 385### OH_AI_TensorGetElementNum() 386 387``` 388OH_AI_API int64_t OH_AI_TensorGetElementNum(const OH_AI_TensorHandle tensor) 389``` 390 391**描述** 392 393获取张量元素数量。 394 395**起始版本：** 9 396 397 398**参数：** 399 400| 参数项 | 描述 | 401| -- | -- | 402| const [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 403 404**返回：** 405 406| 类型 | 说明 | 407| -- | -- | 408| OH_AI_API int64_t | 张量的元素数量。 | 409 410### OH_AI_TensorGetDataSize() 411 412``` 413OH_AI_API size_t OH_AI_TensorGetDataSize(const OH_AI_TensorHandle tensor) 414``` 415 416**描述** 417 418获取张量中的数据的字节数大小。 419 420**起始版本：** 9 421 422 423**参数：** 424 425| 参数项 | 描述 | 426| -- | -- | 427| const [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 428 429**返回：** 430 431| 类型 | 说明 | 432| -- | -- | 433| OH_AI_API size_t | 张量数据的字节数大小。 | 434 435### OH_AI_TensorSetUserData() 436 437``` 438OH_AI_API OH_AI_Status OH_AI_TensorSetUserData(OH_AI_TensorHandle tensor, void *data, size_t data_size) 439``` 440 441**描述** 442 443设置张量为用户自行管理的数据。此接口常用于复用用户数据作为模型输入，可减少一次数据拷贝。<br>注意：此数据对于张量来说是外部数据，张量销毁时不会主动释放，由调用者负责释放。另外，在此张量使用过程中，调用者须确保此数据有效。 444 445**起始版本：** 10 446 447 448**参数：** 449 450| 参数项 | 描述 | 451| -- | -- | 452| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 453| void *data | 用户数据首地址。 | 454| size_t data_size | 用户数据长度。 | 455 456**返回：** 457 458| 类型 | 说明 | 459|---------------------------------------------------------| -- | 460| OH_AI_API [OH_AI_Status](capi-status-h.md#oh_ai_status) | 执行状态码。若成功返回OH_AI_STATUS_SUCCESS，否则返回具体错误码。 | 461 462### OH_AI_TensorGetAllocator() 463 464``` 465OH_AI_API OH_AI_AllocatorHandle OH_AI_TensorGetAllocator(OH_AI_TensorHandle tensor) 466``` 467 468**描述** 469 470获取内存分配器。此接口主要是提供一种获取张量的内存分配器的方法。 471 472**起始版本：** 12 473 474 475**参数：** 476 477| 参数项 | 描述 | 478| -- | -- | 479| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 480 481**返回：** 482 483| 类型 | 说明 | 484|-------------------------------------| -- | 485| OH_AI_API [OH_AI_AllocatorHandle](capi-mindspore-oh-ai-allocatorhandle.md) | 内存分配器的句柄。 | 486 487### OH_AI_TensorSetAllocator() 488 489``` 490OH_AI_API OH_AI_Status OH_AI_TensorSetAllocator(OH_AI_TensorHandle tensor, OH_AI_AllocatorHandle allocator) 491``` 492 493**描述** 494 495设置内存分配器。此接口主要是提供一种设置内存分配器的方法，tensor的内存将由这个分配器分配。 496 497**起始版本：** 12 498 499 500**参数：** 501 502| 参数项 | 描述 | 503| -- | -- | 504| [OH_AI_TensorHandle](capi-mindspore-oh-ai-tensorHandle.md) tensor | 张量对象句柄。 | 505| [OH_AI_AllocatorHandle](capi-mindspore-oh-ai-allocatorhandle.md) allocator | 内存分配器对象句柄。 | 506 507**返回：** 508 509| 类型 | 说明 | 510|---------------------------------------------------------| -- | 511| OH_AI_API [OH_AI_Status](capi-status-h.md#oh_ai_status) | 执行状态码。若成功返回OH_AI_STATUS_SUCCESS，否则返回具体错误码。 |