使用 TypeSafe System One API 查询模型

TypeSafe 的 System One API 是一种请求和响应格式,用于根据类型化问题评估应用状态并返回结构化答案。 在 Azure Databricks 上,你通过 Unity Gateway 向 Unity Catalog 模型服务发送 System One 请求。 该服务背后的模型可以由Databricks或TypeSafe AI, Inc.托管:

  • OpenJev(Qwen3.5 4B) 是一个基于Qwen3.5的开放模型,由Databricks托管。

  • TypeSafe AI Jev 1.14.0 由 TypeSafe AI, Inc. 托管,通过 Unity Gateway 提供服务。 要使用该功能,账户管理员必须在账户控制台中开启 TypeSafe AI模型 预览。 TypeSafe AI 的使用受其条款约束。

    参见 ADI Services。

当应用需要简洁、结构化的决策而非生成的散文时,可以使用System One API。 当响应时间重要时,比如决定请求是否需要升级、选择路由标签或根据评分标准对其进行评分,这类方法可能更合适。 响应时间取决于模型服务和请求负载。

关于 SQL 中表行的决策,请参见ai_decide函数。

要求

  • 一个支持 Unity 目录和 Unity Gateway 的工作区。
  • 一个由与 System One 兼容的模型支持的 Unity 目录模型服务。 示例中使用 openjev-qwen35-4b 了模型服务,其完全限定的名称为 system.ai.openjev-qwen35-4b。
  • 执行模型服务的权限
  • 要使用 TypeSafe AI Jev 1.14.0,账户管理员必须在账户控制台中开启 TypeSafe AI Models 预览。 请参阅 “管理帐户级预览”。

System One 路由需要 Unity Catalog 模型服务。 它不支持模型提供者服务或非 Unity Catalog 服务端点。

查询模型服务

请求体包含完全限定的模型服务名称、要评估的状态以及一个或多个指定问题。 每个问题都属于 noul、choice 或 score 类型之一。

以下请求包含每种类型的一个问题:

curl \
-u token:$DATABRICKS_TOKEN \
-X POST \
-H "Content-Type: application/json" \
-d '{
  "model": "system.ai.openjev-qwen35-4b",
  "state": {
    "message": "My card was charged twice for the same order and I need a refund.",
    "channel": "support"
  },
  "questions": {
    "is_billing": {
      "type": "noul",
      "instructions": "Is this a billing-related request?",
      "criteria": {
        "true": "The message concerns a charge, payment, invoice, or refund.",
        "false": "The message does not concern billing."
      }
    },
    "intent": {
      "type": "choice",
      "instructions": "Which intent best matches the message?",
      "criteria": {
        "refund": "The customer requests a refund.",
        "duplicate_charge": "The customer reports being charged more than once.",
        "other": "Another request."
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is the request?",
      "criteria": [
        "Can wait",
        "Needs attention soon",
        "Urgent"
      ]
    }
  }
}' \
https://<workspace_host>/ai-gateway/typesafe/v1/systemone

在请求的 model 字段中使用完全限定的 Unity Catalog 模型服务名称 system.ai.openjev-qwen35-4b。

请求字段

领域 类型 Description
model String 完全限定的 Unity Catalog 模型服务名称,例如 system.ai.openjev-qwen35-4b。
state 字符串、对象或数组 内容需要评估。 使用字符串表示文本,或使用结构化数据表示记录、对话或应用状态。
questions Object 一个将问题 ID 映射到问题定义的非空映射。 响应在 answers 对象中使用相同的 ID。

每个问题都有 type、可选的 instructions 和特定于类型的 criteria:

Noul 问题

一个noul问题返回答案是“是”的概率。 可选criteria对象描述了true和false的含义。 提供 instructions,或者提供 true 或 false 的描述。 回复中包含 noul 一个从0(否)到1(是)的数字。

选择题

choice 问题从 criteria 对象中选择一个选项。 每个选项对应到描述,或在不需要额外描述时对应到 null。 定义 1 到 255 个选项。 响应包含选中的 choice、每个选项的概率和一个 confidence 值。

给问题评分

一个 score 问题根据有序的 criteria 数组对状态进行评级。 该响应包含一个概率加权的 score、一个将层级索引映射到各层级标准的 legend、每个层级的概率,以及一个 confidence 值。 定义1到10级。

响应格式

该响应包含模型标识符以及 answers 中每个问题的一个答案。 令牌用量显示在 usage 中,包括 input_tokens 和 output_tokens:

{
  "model": "<returned-model-id>",
  "answers": {
    "is_billing": {
      "type": "noul",
      "noul": 0.98
    },
    "intent": {
      "type": "choice",
      "choice": "duplicate_charge",
      "confidence": 0.965,
      "probabilities": {
        "refund": 0.023,
        "duplicate_charge": 0.977,
        "other": 0.0002
      }
    },
    "urgency": {
      "type": "score",
      "score": 1.902,
      "confidence": 0.852,
      "legend": {
        "0": "Can wait",
        "1": "Needs attention soon",
        "2": "Urgent"
      },
      "probabilities": {
        "0": 0.0069,
        "1": 0.0845,
        "2": 0.9086
      }
    }
  },
  "usage": {
    "input_tokens": 238,
    "output_tokens": 0
  }
}

此回复基于上述请求,数值为四舍五入。 答案、概率、置信度值、令牌计数和返回的模型标识符会根据请求和后端而异。 响应 model 值标识后端报告的模型,且可能与请求的完全限定模型服务名称不同。

请求错误

对于请求验证错误,路由返回 HTTP 422,并附带一个 detail 数组,用于描述无效请求。

其他资源