@formio/uag-sdk (英语)

_{表格.io UAG › 发动机 › 此页}

为 Form.io Universal Agent Gateway (UAG) 构建引擎包. 此套件包含:

• 发动机合同的类型,以及 ENGINE_API_VERSION· ;
• defineEngine,以声明引擎类型及其设置;
• EngineError,用于向API呼叫者显示安全的信息;
• 装货机,即UAG, uag-eval 和引擎服务器用于查找、配置和创建引擎;
• 共享具有结构化产出的模型API的助手;
• 任何试跑者都要检查是否合格.

一个引擎包只依赖于这个包. 它从不需要 @formio/uag。 。 。 .

npm install @formio/uag-sdk

SDK需要节点.js 22或更后,没有依赖性. 完全参考了两个完整的引擎及其测试 引擎 SDK。 。 。 .

一个引擎包

命名软件包 @formio/uag-<type> (官方发动机)或 uag-engine-<type> (谁的). 导出一个引擎类型定义 。 它是类型插件 "engine"数字 : name 是所使用的类型名称 UAG_ENGINES, (中文(简体) ), title (默认 : name向人们展示, description 是运算符的可选摘要,并且 version 默认您的软件包的版本 :

const { defineEngine, EngineError, ENGINE_API_VERSION, requiredSchema } = require('@formio/uag-sdk');

module.exports = defineEngine({
    type: 'engine',
    name: 'acme',
    title: 'Acme',
    kinds: ['agent'],
    apiVersion: ENGINE_API_VERSION,
    description: 'Acme models: structured extraction.',
    settings: {
        apiKey: { env: 'ACME_API_KEY', required: true, secret: true },
        model: { env: 'ACME_MODEL', default: 'acme-large-2026-09-01' },
        maxTokens: { env: 'ACME_MAX_TOKENS', type: 'number', default: 4000 },
    },
    create({ name, settings, options }) {
        const client = options.client || new AcmeClient({ apiKey: settings.apiKey });
        return {
            name,
            kind: 'agent',
            apiVersion: ENGINE_API_VERSION,
            model: settings.model,
            async extract(request) {
                request.signal?.throwIfAborted();
                const { schema, decode } = requiredSchema(request.schema);
                const answer = await client.complete({ schema, signal: request.signal /* ... */ });
                if (answer.quotaExceeded) throw new EngineError('Quota exceeded for this API key.');
                return { model: answer.model, values: decode(answer.json) };
            },
        };
    },
});

引擎必须使用实例 name 它被授予, 和其中之一 kinds 它声明。 一个决策引擎 decide 财务报告和审定财务报表 maxOptions; 代理引擎已经 extract设置 toolUse: true 何时 extract 接受只读研究工具。 见 contract.d.ts 每一份请求和答复.

以2.0发布候选人的外形定义,引擎名称包含在内 type (单位:千美元){ type: 'acme', kinds, ... }),以显示上方形状的信息拒绝.

在文档上生成文本

代理引擎也可以执行 generate(request),哪个文档插件会调用在上传文档上写入免费文本,并声明 accepts,文档的本地读取类型(默认) ['text']; 列表 'pdf' 只有当您的模型将 PDF 读取为文档时 :

accepts: ['text', 'pdf'],
async generate({ instructions, system, attachments, format, maxTokens, signal, onProgress }) {
    // attachments: { kind: 'pdf', data: Buffer, label, pages? } or { kind: 'text', text, label, textFormat? }
    // Put the documents before the instructions; report progress as the answer streams.
    return { text, model, stopReason: 'end' /* or 'max_tokens' when cut off */, usage };
},

generate 必须尊重 signal中,从不记录文档,并报告一个简短的答案为 stopReason: 'max_tokens' 而不是失败.

create 接收 { name, settings, options, config, requireSetting }数字 :

• settings: 实例对每个已声明设置的值为 1.
• options:实例的选项如配置中给出的,包括非设置的选项。 在此接受测试双倍( E)options.client,如上例),所以测试,以及下面的符合性检查,从不叫真正的API.
• config: 主机的配置, 例如只读 routing.timeouts[name]。 。 。 .
• requireSetting(key):一个设置的值,或标准"需要它的设置"出错,对于一个只是有时需要的设置.

create 可能会是同步的.

设置

每个设置从其中第一个设置中解析:

1. 实例的配置选项;
2. UAG_ENGINE_<NAME>_<SETTING>,从实例名称和设置名称(fast 财务报告和审定财务报表 apiKey 给 UAG_ENGINE_FAST_API_KEY(三);
3. 设置列表中的变量 env,顺序;
4. 联合国 default。 。 。 .

实例

主机启用引擎为一类命名实例 :

UAG_ENGINES=jev,fast:claude,deep:claude,x:@acme/uag-engine-x

• 裸入( A)jev)在实例类型后命名.
• <name>:<type> 自己命名它,所以一个类型可以作为多个不同设置的例运行.
• 开始的类型 @ 或者说 uag-engine-,或包含 /,是一个软件包名称。 空包项取出包的类型名.
• 名称使用小写字母、数字和 -,从字母开始,最多为63个字符。 在装入任何物品之前,任何其它东西,包括任何路径,都会被拒绝.

在配置中,条目是这样的字符串,或者 { name, type, options }时 type 也可能是一个引擎类型定义.

正在装入

const { engineInstances } = require('@formio/uag-sdk');
const { enginePaths, loadEngines } = require('@formio/uag-sdk/loader');

const engines = await loadEngines(engineInstances(config, process.env), {
    types: { remote: RemoteEngine },        // built-in and embedded types, tried first
    paths: enginePaths(__dirname, process.env),
    env: process.env,
    config,
});

查找类型名称 types,然后作为 @formio/uag-<type>,然后作为 uag-engine-<type>。软件包在 node_modules ,然后在 <dir>/node_modules 每个绝对目录中 UAG_ENGINE_PATH。在工作目录中从来没有, NODE_PATH 或节点的全局文件夹,以及一个其入口在自己的目录外解决的软件包被拒绝. 无所安设. 装入引擎包 require(): commonJS,或指节点22.12上或后期的ES模块. 每个结果都是 { engine, type, title, kinds, typeVersion, package, version } (单位:千美元)typeVersion 当定义设定时 version· ; package 财务报告和审定财务报表 version 当类型来自一个软件包时),这就是什么 Formflow.engineRegistry 拿着.

planEngines(instances, options) 使用相同的参数并进行相同的解析和检查,但不会产生任何结果:对于每个实例,它返回结果的字段,而不返回 engine附加时 name, (中文(简体) ), definition, (中文(简体) ), args (如何将定义传递给 create和 failure(err),该词与加载器一样不能开始,而忽略了秘密值。 它是一个主机 创建引擎本身. createEngine(definition, { name, options, env, config }) 解析设置并创建一个实例,就像 UAG 所做的那样.

每个定义都被从结构上检查过,所以一个用这个SDK的另一个拷贝所建的包,或者没有,负载也一样. 为另一个引擎合同版本所构建的软件包被拒绝,而错误名称为两个版本.

错误

掷出 EngineError 对于被调用者可能看到的消息的失败,例如"这个API密钥超过了配额". 向API调用者报告的任何其他出错仅作为"引擎失败(请参见X请求日志)"(在引擎服务器上,"引擎失败(请参见引擎服务器日志)"),因为供应商SDK出错可以携带URL和账户细节.

帮助者

• requiredSchema(schema):每个字段的提取计划,用于严格的结构化产出,以及 decode(answer) 将答案映射回来。 空值表示"未声明"而被忽略. 数字和是/否字段作为字符串出行,保留字段的标题和描述;数字作为数量($4,250)解码为4250,其他非数字的则被忽略. 一个被键入的enum保留其值,而其外的答案被丢弃.
• parseJsonObject(text):文本答案中的第一个 JSON 对象,或 EngineError。 。 。 .
• toolResultText(result):一个工具调用的结果作为模型的文本.

遵约

const { checkEngine } = require('@formio/uag-sdk/conformance');

it('meets the engine contract', async () => {
    const report = await checkEngine(require('..'), { options: { client: fakeClient } });
    assert.deepStrictEqual(report.failures, []);
});

支票创造了一个实例并称它。 传递选项,如假客户端,或让其回答的环境变量. 它检查:

• 定义和引擎具有合同形状;
• 引擎使用实例名称和 model 选项;
• extract 只返回所询问的字段,或 decide 只问过它的问题;
• accepts,设定时仅列出列表 text 财务报告和审定财务报表 pdf· ; generate,当存在时,返回文本、其模式和有效 stopReason· ;
• 研究停止时间 maxIterations,并报告每一个工具称之为它制作的;
• 中止的信号停止引擎,包括在研究期间 generate。 。 。 .

一个研究回合是模型一起发出的呼叫;一个接一个地发出的呼叫作为单独的回合计算.

驾照:麻省理工.