参数模式

本页描述了在GenAIScripts中定义参数签名的方式。 GenAIScript中的各种实体都可以参数化，PromptParametersSchema 提供了一种灵活的方式来定义参数模式，结合了内置类型推断功能。

// parameters of a script
script({
    parameters: {
        city: "",
        year: NaN,
    },
})
// parameters of a tool
defTool("...", "...", { city: "", year: NaN }, ...)

在内部，GenAIScript将parameters对象(PromptParametersSchema)转换为JSON模式(JSONSchema)用于各种用途。例如，OpenAI工具API使用JSONSchema来定义工具的签名。

JSONSchema虽然表达能力更强，但对于简单用例来说编写起来更冗长，手动编写可能会很繁琐。

defTool("weather", "current weather", { city: "" }, ...)

语法

以下转换规则被应用于将参数数据转换为JSONSchema：

如果该值是一个对象并且具有type属性，则将其视为JSONSchema对象（并转换嵌套对象）

{ type: "string" } => { type: "string" }

如果该值是字符串，则转换为{ type: "string" }。如果字符串是'""'，则必填；否则该值将作为default。

"" => { type: "string" }
"San Francisco" => { type: "string", default: "San Francisco" }

如果该值是数字，则转换为{ type: "number" }。如果数字是NaN，则将被设为必填项。

NaN => { type: "number" }
42 => { type: "number", default: 42 }

如果值为布尔值，则转换为{ type: "boolean" }。目前还没有针对必填布尔值的编码方式。

true => { type: "boolean", default: true }

如果该值是一个数组，则数组项的类型将从第一个数组元素推断出来。

[""] => { type: "array", items: { type: "string" } }

如果该值是一个对象，则转换为type: 'object'模式。值为""或NaN的字段是必填项。

{ city: "" } => {
    type: "object",
    properties: { city: { type: "string" } },
    required: ["city"]
}
{ price: 42 } => {
    type: "object",
    properties: { price: { type: "number", default: 42 } },
    required: []
}

界面提示

一些额外的非标准属性用于向用户界面提供附加信息:

uiType textarea 表示该字段应呈现为文本区域。

{
    "type": "string",
    "uiType": "textarea"
}

uiSuggestions 用于为 string 类型提供建议列表。这些建议会填充用户界面中的下拉选项，但也允许输入其他值。

{
    "type": "string",
    "uiSuggestions": ["San Francisco", "New York"]
}

uiType: runOption 对于布尔值，将复选框放置在Run按钮下方。

{
    "type": "boolean",
    "uiType": "runOption"
}

`accept`

你可以为env.files变量指定支持的文件扩展名的逗号分隔列表。

script({
    accept: ".md,.txt",
})

如果移除所有文件支持，将accept设置为none。

script({
    accept: "none",
})

脚本和系统脚本

script条目中的parameters用于填充env.vars条目。参数模式在Visual Studio Code启动脚本时使用，在playground中用于填充表单字段。

顶级脚本参数名称在env.vars中按原样使用

script({
    parameters: {
        city: "",
        year: NaN,
    },
})
const city = env.vars.city // city is a string
const year = env.vars.year // year is a number

system script的parameters参数会以系统脚本ID作为前缀。

system({
    parameters: {
        value: "",
    },
})
export default function (ctx: ChatGenerationContext) {
    const { env } = ctx
    const value = env.vars["system.something.value"]
    ...
}

运行时推断

您可以通过使用JSONSchema.infer函数来运行转换助手。