C++

Name: Darra AI Studio
Author: Darra

C++ 与 C 共用同一份 C ABI 头 darra_ai.h。头文件用 extern "C" 包住全部导出，永不导出 C++ 类型 / STL / 异常。全部推理唯一入口：

会话：darra_session_open / open_plain  →  darra_session_infer_image  →  darra_session_close
池：  darra_pool_open / open_plain     →  darra_pool_submit → darra_pool_wait → darra_pool_close

GUI、PLC、客户应用同一路径，无第二套。权威契约 = darra_ai.h，语义冲突以头文件为准。

公开 runtime 构建只含解密、验票、推理分发、诊断、运行时包管理；物理上没有 darra_encrypt_ / darra_issue_ / darra_fingerprint_ 符号。仓库 Darra.AI.Studio.SDK/C++/ 是空目录：没有 *.hpp、没有 darra::ai 命名空间、没有官方 RAII 类。

当前版本

本文档对应 C++ SDK v1.0.0（与 darra_ai.h 的 DARRA_VERSION_MAJOR/MINOR/PATCH 同一组数字）。加载后第一件事核对 ABI：DARRA_VERSION_DECODE_MAJOR(darra_version()) == DARRA_VERSION_MAJOR，不等 = 装错了库，禁止继续。运行时字符串用 darra_version_string()，客户机必须看到 1.0.0+runtime。

与 C API 的对比

特性	C API	C++ 消费方
头文件	darra_ai.h	同一份（extern C）
资源管理	darra_session_close / darra_string_free	同左。SDK 不提供析构封装
类型	C 结构体 + darra_session* 不透明句柄	同左。ABI 纪律禁止导出 C++ 类
错误	int32_t + 线程局部 darra_last_error	同左。不抛异常
字符串	char*，堆串必须 darra_string_free	同左。禁止 delete[] / 跨 CRT free
空指针	NULL	nullptr（语义相同）
示例	Core/tools/example_c/main.c	无独立 C++ 示例工程；本页用同一 ABI 的 C++ 写法

#include "darra_ai.h"

int main() {
    if (DARRA_VERSION_DECODE_MAJOR(darra_version()) != DARRA_VERSION_MAJOR) {
        return 1;
    }
    darra_session* session = nullptr;
    int32_t rc = darra_session_open("model.darmodel", nullptr,
                                    nullptr, nullptr, &session);
    if (rc != DARRA_OK) {
        darra_error_t err{};
        err.size = sizeof(err);
        darra_last_error(&err);
        return static_cast<int>(rc);
    }
    darra_session_close(session);
    return 0;
}

应用侧若要用 RAII，只能自己包，不是 SDK 类型：

#include "darra_ai.h"
#include <memory>

struct SessionClose {
    void operator()(darra_session* p) const noexcept { darra_session_close(p); }
};
using SessionPtr = std::unique_ptr<darra_session, SessionClose>;

安装

从下载页面获取内核包或 darra-ai-c-sdk.zip（头文件 + import lib + 示例）。C 与 C++ 不是两套包。

Windows x64
Linux x64
Linux ARM64
CMake

包：darra-ai-core-windows-x64.zip（DarraAI.Core.dll、darra_ai.h、DarraAI.Core.lib、darra-selftest）。

cl /utf-8 /EHsc /Fe:my_app.exe main.cpp DarraAI.Core.lib /I include

运行目录必须带 DarraAI.Core.dll。MSVC 加 /utf-8（头文件 UTF-8 无 BOM，注释全中文）。

包：darra-ai-core-linux-x64.tar.gz（libCore.so + 头文件）。

g++ -o my_app main.cpp -I include -L. -ldarraai_core -Wl,-rpath,'$ORIGIN'

包：darra-ai-core-linux-arm64.tar.gz（RK3588 板端与客户板共用）。edge-rknn 只在此平台运行。Windows 上没有 RKNN。

g++ -o my_app main.cpp -I include -L. -ldarraai_core -Wl,-rpath,'$ORIGIN'

add_executable(my_app main.cpp)
target_include_directories(my_app PRIVATE ${SDK_PATH}/include)
if(WIN32)
    target_link_libraries(my_app PRIVATE DarraAI.Core)
    target_compile_options(my_app PRIVATE /utf-8)
else()
    target_link_libraries(my_app PRIVATE darraai_core)
endif()

#include "darra_ai.h"

只交付 x64 / ARM64，两平台均单调用约定，无 __stdcall 变体。ORT / CUDA / TensorRT / OpenVINO / RKNN 等重依赖不链进本库，由 Studio 或客户部署流程按平台和版本提前准备。

环境要求

项目	要求
操作系统	Windows x64 / Linux x86_64 / Linux ARM64（RK3588）。macOS 不在 v1
编译器	MSVC（/utf-8）/ GCC / Clang，C++11 或更高
头文件	darra_ai.h（UTF-8 无 BOM，extern "C" 导出）
运行库	Windows：DarraAI.Core.dll + DarraAI.Core.lib；Linux：libCore.so，链接 darraai_core
权限	装运行时包到系统目录时可能需要管理员；SDK 不代装 NVIDIA / RK3588 NPU 等系统驱动
重依赖	ORT / CUDA / TensorRT / OpenVINO 等依赖由 Studio 或部署人员提前部署为 Provider；SDK 打开模型不下载或安装

诚实边界

不承诺 dump 免疫。 授权机 + 管理员级调试器在会话存活期暂停 dump，挡不住。本 SDK 防的是静态拷走、转发、无授权运行、常规 dump 工具、逆向授权算法。
加密单向。 官方不提供解回明文的通道。永久密码只用于无限次推理。公开 runtime 不能加密 / 签发。
环境提前部署。 SDK 只验证和加载本地 Provider；下载、安装与系统驱动由 Studio 或部署流程处理，darra_diag_collect 提供只读诊断。
macOS 不在 v1。 不是「即将支持」。
Windows 无 RKNN。 rknn 载荷只在 linux-arm64 板端运行；Windows 收到即 DARRA_UNSUPPORTED_PAYLOAD。
不承诺硬实时。 推理是阻塞调用。PLC 侧必须在扫描周期外进程 / 线程调用。
诊断 JSON 不含密钥 / 密码 / token / 机器指纹字节。

快速开始

生产路径：加密容器

客户现场加载 .darmodel（新分发钥匙内嵌，key_path 传 nullptr）。导出格式即加载格式，用户零配置。打开前用 darra_session_unlock_info 决定要不要一次激活码。

#include "darra_ai.h"
#include <cstdio>
#include <fstream>
#include <vector>

int main() {
    if (DARRA_VERSION_DECODE_MAJOR(darra_version()) != DARRA_VERSION_MAJOR) {
        std::fprintf(stderr, "ABI 不匹配: %s\n", darra_version_string());
        return 1;
    }

    darra_session* session = nullptr;
    int32_t rc = darra_session_open("model.darmodel", nullptr,
                                    nullptr, nullptr, &session);
    if (rc != DARRA_OK) {
        darra_error_t err{};
        err.size = sizeof(err);
        darra_last_error(&err);
        std::fprintf(stderr, "[%d] %s\n建议: %s\n", err.code, err.message, err.hint);
        return static_cast<int>(rc);
    }

    std::ifstream in("photo.jpg", std::ios::binary);
    std::vector<uint8_t> jpeg((std::istreambuf_iterator<char>(in)),
                              std::istreambuf_iterator<char>());

    darra_image_desc desc{};
    desc.size = sizeof(desc);
    desc.format = DARRA_IMAGE_AUTO;

    char* results = nullptr;
    rc = darra_session_infer_image(session, jpeg.data(), jpeg.size(), &desc, &results);
    if (rc == DARRA_OK) {
        std::printf("%s\n", results);
        darra_string_free(results);
    }
    darra_session_close(session);
    return static_cast<int>(rc);
}

对应包未部署时返回缺包错误，请先准备环境再重试。环境准备的进度在 Studio 右上角下载中心查看。失败码与 hint 见错误码。

明文模型（Studio 试跑 / 客户自有无需加密模型）与加密入口同一推理路径，只跳过容器解码与验票：

darra_session* session = nullptr;
int32_t rc = darra_session_open_plain("model.onnx", nullptr, &session);

open_plain 的路径可以是 .onnx、.pdmodel（同目录须有 .pdiparams）、或含二者的目录。Paddle 是运行时载荷（PayloadKind=paddle）。.pt / .pth 仍拒，返回 DARRA_UNSUPPORTED_PAYLOAD。

何时用哪种

.darmodel + 激活码（未绑机）/ nullptr（已绑机） — 生产环境，推荐。
darra_session_open_plain — Studio 试跑 / 客户自有明文模型。
darra_pool_open — 同模型突发 / 流式；max_workers 硬顶 8。

与 C API 的对比​

安装​

环境要求​

快速开始​

与 C API 的对比

安装

环境要求

快速开始