Skip to main content

结构化决策接口

介绍​

决策模型用于快速决策，不生成开放式内容。它不返回一段文字，而是针对你预先设置好的决策规则，返回最符合的答案、各候选答案的概率分布以及置信度。

典型场景：

  • 意图识别：判定用户消息属于哪一类咨询，用于路由到不同的处理流程
  • 内容分类 / 审核：对文本打标签，或判定是否命中某类风险
  • 是否判定：判定文本是否满足某个条件，并拿到「是」的概率
  • 打分评估：按自定义档位给内容打分，可用于回答质量评估、优先级排序

相比用通用对话模型写提示词做分类，决策模型的优势在于：输出结构固定、不会跑偏成一段解释，且直接给出概率分布，便于设置阈值和人工兜底。

注意： 该接口不是 OpenAI 兼容协议。决策模型没有对话补全能力，无法通过 /v1/chat/completions 调用。

除了直接调用本接口，决策模型也可以在工作流的意图分支节点中选用，以及在控制台的模型服务中直接体验：

Jev 决策模型在线体验

💻 立即体验：Jev 决策模型

接口定义​

接口地址​

POST https://api.link-ai.tech/v1/systemone

请求头​

参数取值说明
Content-Typeapplication/json请求体格式
AuthorizationBearer $LINKAI_API_KEY平台 API Key，与对话接口共用，在控制台「API Key」中创建

请求体​

参数类型是否必传说明
modelstring是决策模型名称，如 jev-latest
statestring / object / array是待处理的内容。可以是一段纯文本，也可以是结构化对象（如一条工单、一轮对话记录），模型会读取其中的全部字段
questionsobject是决策任务集合，键为自定义的任务 ID（响应中按同样的 ID 返回答案），值为任务定义。单次最多 64 个任务

questions 中每个任务的定义：

参数类型是否必传说明
typestring是任务类型，取值 choice / noul / score
instructionsstring是决策要求，用自然语言描述要模型决策什么，如「这条用户消息属于哪一类咨询？」
criteriaobject / array视类型而定决策依据，格式随 type 变化，见下方说明

任务类型​

choice — 单选

从给定的候选答案中选出一个，并返回每个候选答案的概率。criteria 为必传对象，键是答案名称，值是该答案的决策依据（模型实际读取的是这段描述，建议写清楚什么情况下选它）。单个任务最多 255 个候选答案。

{
  "type": "choice",
  "instructions": "这条用户消息属于哪一类咨询？",
  "criteria": {
    "售后退换": "退货、换货、退款相关的诉求",
    "产品使用": "咨询怎么用、怎么保养、参数如何",
    "订单物流": "查询订单状态或物流进度",
    "其他": "以上都不属于"
  }
}

noul — 是否

回答是或否，返回「是」的概率。criteria 选填，可分别说明什么情况算「是」、什么情况算「否」。

{
  "type": "noul",
  "instructions": "用户是否表达了退款意图？",
  "criteria": {
    "true": "明确提出退款、退钱、不想要了",
    "false": "只是咨询或抱怨，并没有要求退款"
  }
}

score — 评分

按自定义档位打分。criteria 为必传数组，顺序即档位，由低到高：第一项对应 0 分，往后每项加一分。支持 2 到 10 个档位。返回的分数是浮点数，可以落在两档之间。

{
  "type": "score",
  "instructions": "这条消息的紧急程度",
  "criteria": [
    "随口一问，不需要马上处理",
    "希望尽快得到答复",
    "已经影响使用，需要优先处理",
    "情绪强烈，可能升级为投诉"
  ]
}

响应结果​

成功响应​

{
  "model": "jev-latest",
  "answers": {
    "intent": {
      "choice": "售后退换",
      "confidence": 0.93,
      "probabilities": {
        "售后退换": 0.93,
        "产品使用": 0.04,
        "订单物流": 0.02,
        "其他": 0.01
      }
    },
    "refund": {
      "noul": 0.88
    },
    "urgency": {
      "score": 2.15,
      "confidence": 0.71,
      "legend": {
        "0": "随口一问，不需要马上处理",
        "1": "希望尽快得到答复",
        "2": "已经影响使用，需要优先处理",
        "3": "情绪强烈，可能升级为投诉"
      },
      "probabilities": {
        "0": 0.03,
        "1": 0.15,
        "2": 0.55,
        "3": 0.27
      }
    }
  },
  "usage": {
    "prompt_tokens": 312,
    "completion_tokens": 0,
    "total_tokens": 312
  }
}

answers 的键与请求中 questions 的键一一对应。不同任务类型返回的字段不同：

任务类型字段类型说明
choicechoicestring选中的答案名称
choiceprobabilitiesobject每个候选答案的概率，合计为 1
choiceconfidencefloat本次决策的置信度，取值 0~1
noulnoulfloat「是」的概率，取值 0~1，大于 0.5 可视为「是」
scorescorefloat得分，可落在两档之间
scoreprobabilitiesobject各档位的概率，键为档位下标（从 0 开始）
scorelegendobject档位下标与档位描述的对照，便于展示
scoreconfidencefloat本次决策的置信度，取值 0~1

关于 confidence 与 probabilities： probabilities 表示模型在各候选答案之间的分布，confidence 表示模型对这次决策整体的把握程度。建议的用法是设一个阈值，低于阈值时转人工或走兜底分支，而不是无条件采信最高概率的那一项。

错误说明​

错误以 HTTP 状态码返回，响应体为：

{
  "detail": "错误描述"
}
HTTP状态码描述
401未携带 API Key，或 Key 无效
422请求参数有误（缺少 model / state / questions、任务类型不合法、缺少 instructions、任务数超过 64 个），或积分余额不足，或所选模型不是决策模型
429请求过于频繁，建议退避后重试
500服务内部错误
529上游服务繁忙，建议退避后重试

示例代码​

1. CURL 请求​

curl https://api.link-ai.tech/v1/systemone \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LINKAI_API_KEY" \
  -d '{
    "model": "jev-latest",
    "state": "这个吹风机用了两天就不出热风了，我要退货",
    "questions": {
      "intent": {
        "type": "choice",
        "instructions": "这条用户消息属于哪一类咨询？",
        "criteria": {
          "售后退换": "退货、换货、退款相关的诉求",
          "产品使用": "咨询怎么用、怎么保养、参数如何",
          "订单物流": "查询订单状态或物流进度",
          "其他": "以上都不属于"
        }
      },
      "refund": {
        "type": "noul",
        "instructions": "用户是否表达了退款意图？"
      }
    }
  }'

2. Python 代码请求​

import os
import requests

resp = requests.post(
    "https://api.link-ai.tech/v1/systemone",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {os.environ['LINKAI_API_KEY']}",
    },
    json={
        "model": "jev-latest",
        # state 也可以传结构化对象，模型会读取其中的全部字段
        "state": {
            "user_query": "这个吹风机用了两天就不出热风了，我要退货",
            "order_status": "已签收 3 天",
        },
        "questions": {
            "intent": {
                "type": "choice",
                "instructions": "这条用户消息属于哪一类咨询？",
                "criteria": {
                    "售后退换": "退货、换货、退款相关的诉求",
                    "产品使用": "咨询怎么用、怎么保养、参数如何",
                    "订单物流": "查询订单状态或物流进度",
                    "其他": "以上都不属于",
                },
            },
        },
    },
    timeout=30,
)
resp.raise_for_status()
answer = resp.json()["answers"]["intent"]

# 低置信度时转人工，不要无条件采信
if answer["confidence"] < 0.6:
    print("置信度不足，转人工处理")
else:
    print(answer["choice"], answer["probabilities"])

计费说明​

决策模型只按输入 token 计费，输出不计费。响应 usage 中的 completion_tokens 恒为 0，total_tokens 等于 prompt_tokens。

输入 token 包含 state 与 questions 两部分，因此候选答案的描述写得越详细，单次调用的消耗越高。若需要对同一批内容跑多个决策任务，建议合并到一次请求的 questions 中——同一份 state 只会计费一次。

模型列表​

模型名称说明
jev-latestTypeSafe Jev 决策模型，支持 choice / noul / score 三种任务类型，上下文长度 64k