输入——文本、JSON、图片、音频和文档
决策可以读取什么——文本、结构化 JSON、图片、语音消息和文档(PDF、Word、Excel、PowerPoint、CSV 等)——以及每种输入如何到达 Jev、Laya 或 OpenAI Decisions。
决策读取的是它的 state。除了文本和 JSON,对象 state 还可以携带文件:把字段声明为 image、audio 或 file,然后在其中发送文件。在调用引擎之前,Dcision 会把每个文件转换成引擎能够读取的内容——文本,或者对能看图的引擎而言是图片——因此同一个决策可以在任何引擎上运行。
| 你发送 | 声明 | 引擎得到什么 |
|---|---|---|
| 文本 | text state,或 string 字段 | 文本 |
| 结构化 JSON | 带类型字段的 object state,或 list | JSON |
| 图片 | image 字段——PNG、JPEG、GIF 或 WebP | OpenAI Decisions:图片本身。Jev 和 Laya:由 OpenAI 撰写的图片描述,包括其中可见的文字 |
| 文本 + 图片 | 带一个 string 字段和一个 image 字段的 object state | 二者并列 |
| 语音 / 音频 | audio 字段——MP3、WAV、OGG/Opus(WhatsApp 语音消息)、M4A、WebM、FLAC、AAC、AMR | 转写文本(OpenAI 语音转文字) |
| 文档或任意文件 | file 字段 | 其文本:PDF、Word(.docx)、PowerPoint(.pptx)、Excel(.xlsx、.xls)、OpenDocument(.odt、.ods、.odp)、CSV、RTF、HTML、XML、EPUB、Markdown 和纯文本由 Dcision 读取;扫描版 PDF、旧版 .doc/.ppt 及其他格式由 OpenAI 读取。在 file 字段中发送的图片和音频按上述方式处理 |
声明文件字段
{
"kind": "object",
"fields": [
{ "key": "message", "type": "string" },
{ "key": "photo", "type": "image" },
{ "key": "voice", "type": "audio" },
{ "key": "invoice", "type": "file", "required": true }
]
}发送文件
文件字段接受以下任意形式:
| 形式 | 示例 |
|---|---|
data: URL(base64) | "data:image/png;base64,iVBORw0KGgo…" |
| 带 base64 的对象 | { "data": "JVBERi0xLjQK…", "filename": "nf-1042.pdf", "mime_type": "application/pdf" }——filename 和 mime_type 可选 |
https:// URL | "https://files.example.com/nf-1042.pdf" 或 { "url": "…", "filename": "nf-1042.pdf" }——由 Dcision 下载 |
curl -X POST https://api.dcision.io/v1/decisions/invoice-triage \
-H "Authorization: Bearer $DCISION_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"state\": {\"message\": \"Can we pay this?\", \"invoice\": {\"data\": \"$(base64 -w0 nf-1042.pdf)\", \"filename\": \"nf-1042.pdf\"}}}"通过 SDK 和 CLI:
import { readFile } from "node:fs/promises";
import { Dcision, fileFromBytes, fileFromUrl } from "@dcision/sdk";
const decision = await new Dcision().decide("invoice-triage", {
message: "Can we pay this?",
invoice: fileFromBytes(await readFile("nf-1042.pdf"), "nf-1042.pdf"),
photo: fileFromUrl("https://files.example.com/receipt.jpg"),
});from dcision import Dcision, file_from_path
decision = Dcision().decide("voice-routing", {"voice": file_from_path("note.ogg")})dcision decide invoice-triage --state '{"message":"Can we pay this?"}' --file invoice=./nf-1042.pdf从表单、n8n、Make 或 Zapier 发送时,webhook 触发器也接受以 multipart/form-data 形式发送的文件:
curl https://api.dcision.io/v1/hooks/whk_… \
-F state='{"message":"Can we pay this?"}' \
-F invoice=@nf-1042.pdf在 Playground 中,文件字段会有一个文件选择器——音频字段还会有一个用于录制语音消息的录音按钮。
格式由文件的字节决定,而不是由文件名或 mime_type 决定:一个实际上是 PNG 的 .pdf 会被当作图片读取。image 字段只接受图片,audio 字段只接受音频(否则返回 422 INVALID_STATE);file 字段接受任意格式。
URL 必须是返回 200 和文件内容的公网 https:// 地址——不跟随重定向,私有或保留地址会被拒绝,与目的地相同。
引擎读取什么
每个文件字段都会被替换为从中读取的内容,引擎——以及你的目的地和执行日志——看到的是这些内容,而不是原始字节:
{
"message": "Can we pay this?",
"invoice": { "kind": "document", "file": "nf-1042.pdf", "content_type": "application/pdf", "bytes": 48213, "text": "NOTA FISCAL Nº 1042 … Total R$ 380,00" },
"voice": { "kind": "audio", "file": "note.ogg", "content_type": "audio/ogg", "bytes": 21877, "text": "I want to cancel order 1042 and get a refund." },
"photo": { "kind": "image", "file": "receipt.jpg", "content_type": "image/jpeg", "bytes": 90311, "text": "", "image": 1 }
}在 OpenAI Decisions 上,"image": 1 指向随调用发送的第一张图片;编写指令时可以自然地引用它("Does the photo show damage?")。在 Jev 和 Laya 上,text 中保存的则是图片的描述。
在指令中按字段名指向文本:"Does the `invoice` total exceed R$ 1,000?"、"Does `voice` ask for a refund?"。在目的地中,用 {{state.voice.text}} 转发转写文本。
过长的文件会被截断,以适应引擎的 token 预算:所有文件的文本共享约 96,000 个字符——较短的文件保持完整——被截断的文本以 … 结尾,并带有 "truncated": true。
谁读取每个文件——以及谁付费
| 文件 | 读取方 | 费用 |
|---|---|---|
| Dcision 能够解析的文档(带文本的 PDF、Office、OpenDocument、电子表格、CSV、RTF、HTML、文本) | Dcision | 无 |
| OpenAI Decisions 上的图片 | 引擎 | 包含在引擎调用中 |
| 音频;Jev 或 Laya 上的图片;扫描版 PDF 及其他格式 | OpenAI | 你的 OpenAI 账户 |
需要 OpenAI 的文件使用工作区的 OpenAI 密钥(设置 → 引擎 → OpenAI 密钥),或在当前环境提供时使用 Dcision 的密钥。两者都没有时,这些运行会返回 424 ENGINE_NOT_CONFIGURED——Dcision 自行解析的文档从不需要密钥。OpenAI 读取文件时出现的故障属于引擎错误(ENGINE_*):设置 onEngineError: "fallback" 后,决策会以其 fallback 行动作答。
读取文件需要时间——一分钟的音频需要几秒钟来转写——这是在引擎调用之外额外的时间。对于带音频的决策,请给客户端设置 60 秒的超时。
响应中的成本
当 state 中包含文件时,响应的 metrics 会显示读取这些文件的开销:
| 字段 | 含义 |
|---|---|
metrics.input_files | 读取的文件数量。 |
metrics.input_processing_ms | 下载和读取文件所用的时间,包含在 latency_ms 中。 |
metrics.input_cost_usd | 通过 OpenAI 读取文件的估算成本——由 Dcision 自行读取全部文件时为 0。 |
metrics.estimated_cost_usd——以及执行日志和概览中的估算成本——包含 input_cost_usd。该估算使用 OpenAI 对默认读取文件的模型的标价:音频使用 gpt-4o-transcribe(每 100 万输入 token 2.50 美元,每 100 万输出 token 10 美元),图片描述和文件读取使用 gpt-5-mini(0.25 美元和 2 美元)。这只是估算;以你的 OpenAI 账单为准。没有文件时,这些字段不会出现。参见运行决策。
限制
| 限制 | 值 |
|---|---|
| 单个文件 | 20 MB |
| 一个 state 中的所有文件 | 24 MB,最多 10 个文件 |
| 一次运行的请求体 | API、Playground 和 webhook 触发器为 32 MB(超过则返回 413 PAYLOAD_TOO_LARGE);不含文件的 state 仍限制为 128 KB |
| 读入 state 的文件文本 | 合计约 96,000 个字符,均匀截断 |
| 读取一次运行的文件 | 60 秒 |
执行日志保留每个文件的名称、类型、大小及其文本的前 4,000 个字符——从不保留文件本身。设置 storeInput: false 后则什么都不保留。
MCP 请求限制为 1 MB:向 MCP 服务器发送文件时请使用 https:// URL。