aardio 文档

web.rest.aiSystemOne

web.rest.aiSystemOne 是纯 aardio 的 AI 结构化决策客户端,实现 Jev System One(POST .../systemone)兼容协议。

定位与安装位置

快速开始

import web.rest.aiSystemOne;

var client = web.rest.aiSystemOne({
    url = "https://api.modelink.ai"; // 或 "https://openrouter.ai/api/v1" 等兼容接口基址
    key = "你的 API Key";
    model = "typesafe/jev-latest"; // 当前指向 Jev 1.14;中文仍应先用业务样本验收
});

var questions = {
    department = ["choice", "这条工单应由哪个团队处理?", {
        ["财务"] = "付款、发票和退款问题";
        ["技术"] = "软件故障、服务中断和系统集成问题";
        ["销售"] = "价格咨询、套餐升级和购买意向";
        ["其他"] = "不属于以上类别或信息不足";
    }];
    urgent = ["noul", "这条工单是否需要立即处理?"];
    severity = ["score", "当前问题对业务造成的影响有多严重?", [
        "轻微影响,主要功能正常",
        "部分功能受影响,业务仍可继续",
        "核心业务完全中断,无法继续工作"
    ]];
};

var result,err,errCode = client.evaluate({
    state = {
        message = "生产系统从今天早上起完全无法登录,所有员工都无法开展工作,请立即修复!";
    };
    questions = questions;
});

if(!result){
    print("请求失败:",err,errCode);
    return;
}

print("实际模型:",result.model);
print("负责团队:",result.answers.department.choice);
print("需要立即处理的概率:",result.answers.urgent.noul);
print("业务影响评分(0~2):",result.answers.severity.score);
print("输入、输出用量:",result.usage.input_tokens,result.usage.output_tokens);

后面的代码片段沿用这里的 client。协议字段、类型名与程序标识符保留原样。

问题声明

questions 是按问题 ID 命名的表,每项可使用以下两种数据形式,并允许混用:

例如,同一请求中可以混用:

var questions = {
    urgent = ["noul", "这条工单是否需要立即处理?"];
    department = {
        type = "choice";
        instructions = "这条工单应由哪个团队处理?";
        criteria = {
            ["财务"] = "付款、发票和退款问题";
            ["技术"] = "软件故障、服务中断和系统集成问题";
            ["销售"] = "价格咨询、套餐升级和购买意向";
            ["其他"] = "不属于以上类别或信息不足";
        };
    };
    outage = {type="noul";instructions="当前核心业务是否完全中断?";criteria={
        ["true"] = "无法继续开展核心业务";
        ["false"] = "核心业务仍然可以继续";
    }};
};

声明只是数据,不会请求模型。 evaluate 调用 buildPayload 时,才将问题的纯数组 [] 转换为接口要求的对象。不要把数组简写直接传给底层 post。

仅转换 questions 的直接成员;不转换 state 中的数组、choice 选项说明或 score 等级数组。不修改调用者的声明,原生问题对象中的扩展字段会保留。数组简写必须有 2~3 项且前两项为字符串,否则 buildPayload / evaluate 返回 null,err,不会发送请求;其他协议约束由服务端检查。

noul.criteria 可省略;指定时使用字符串键 "true" 与 "false",不要改为中文键或布尔键。它们的说明可以是中文。需要结构化 instructions 或服务支持的扩展字段时,使用原生问题对象;数组简写仍要求前两项为字符串。

两种调用方式

(state, questions)

var result = client.evaluate(
    "同一订单扣了两次款,请退回重复扣款。",
    {
        refund = ["noul", "客户是否要求退回款项?"];
        team = ["choice", "这条工单应由哪个团队处理?", {
            ["财务"] = "付款和退款问题";
            ["客服"] = "一般使用咨询或其他问题";
        }];
    }
);

完整请求表

var result = client.evaluate({
    state = "这笔付款是正常消费,不需要退款,只想补开发票。";
    questions = {
        refund = {type="noul";instructions="客户是否要求退回款项?"};
    };
    session_id = "中文工单演示";
});

完整请求表保留 state 和其他扩展字段(如单次指定 model)。questions 同样支持原生对象和数组简写,发送前统一为对象形式。

配置

var client = web.rest.aiSystemOne({
    url = "https://api.modelink.ai";
    key = "你的 API Key";
    model = "typesafe/jev-latest";
    extraHeaders = {
        ["HTTP-Referer"] = "https://example.com";
    };
});

答案读取

客户端不把决策答案转换成文本,也不按厂商重新包装,返回值保持 System One 协议原始结构:

也可以使用:

var answer = client.answer(result,"department");
var probability = client.noulValue(result,"urgent");

读取答案时,缺失问题或类型不符应进入错误处理/人工复核,不要当作“否”或安全放行。特别注意 aardio 中 0 是假值,判断数值是否缺失应使用 ===null,不要使用 if(!probability)。

Jev 1.14 图像与 Box 扩展(实验能力)

TypeSafe Jev 1.14 支持图像输入,并提供 box 问题类型。它们是 TypeSafe 的实验性扩展,不属于所有 System One 服务都支持的通用字段;客户端会原样透传 assets 与 box 问题。

下面的 imageAsset 使用 JSON + Base64 方式构造资产;图像引用必须同时出现在 state、问题的 instructions 或 criteria 中,且每个资产都必须被引用:

client.setHeaders({["TypeSafe-Danger-Zone-Images"] = "true"});

var photo,photoErr = client.imageAsset("/res/photo.jpg");
if(!photo) return null,photoErr;

var result,err = client.evaluate({
    model = "typesafe/jev-latest";
    state = {photo = "photo-1"};
    assets = {["photo-1"] = photo};
    questions = {
        visible = {type="noul";instructions="图片 `photo` 中是否有一辆汽车?"};
        location = {type="box";instructions="定位图片 `photo` 中的汽车。"};
    };
});

imageAsset 也接受二进制 string 或 buffer,但必须另行指定 "png"、"jpg" 或 "jpeg" 格式。TypeSafe 当前图像接口只接受 PNG/JPEG 静态图像,并有图像尺寸、文件大小、请求大小和实验性准确率限制;正式使用前应按目标模型和中文/图像业务样本进行验收。

imageAsset 会自动添加 HTTP 头 TypeSafe-Danger-Zone-Images: true(使用图像或 box 时需要指定)。若服务端不支持该扩展,不要发送 assets 或 box。

协议兼容与模型切换

参考

Markdown 格式