文档 / 通过 API/SDK 打分

通过 API/SDK 打分

你可以使用 Langfuse SDK 或 API 向 traces、observations、sessions 和 dataset runs 添加分数。这是一种评估方法,让你能够设置自定义评估工作流并扩展 Langfuse 的打分能力。关于分数对象的完整细节,参见数据模型。

如果你想让 Langfuse 为你运行确定性的 Python 或 TypeScript 逻辑,请使用代码评估器。当你的应用、流水线或 CI 作业计算分数并通过 API 或 SDK 将它们发送到 Langfuse 时,使用本页。

通过 API/SDK 接入分数

分数可以在不同的粒度级别附加:到单个 traces、到 trace 内的特定 observations,或到完整的 sessions。

关于分数和分数配置的 POST 和 GET 端点的完整细节,参见 API 参考。

Trace 或 Observation 级分数

你可以通过 Langfuse SDK 或 API 添加分数。分数可以采用四种数据类型之一:Numeric、Categorical、Boolean 或 Text。细节参见分数类型。

如果使用 trace_id 手动接入分数以将分数链接到 trace,则无需等到 trace 被创建。该分数会显示在分数表中,并在具有相同 trace_id 的 trace 被创建后链接到该 trace。

下面是按 Score 数据类型的示例。

对于 trace 和 observation 分数,trace_id/traceId 是必需的,observation_id/observationId 是可选的。如果你将分数附加到 observation,请始终同时提供 observation ID 和相应的 trace ID。

Numeric

Numeric 分数值必须以 float 提供。

python

from langfuse import get_client
langfuse = get_client()

# Method 1: Score via low-level method
langfuse.create_score(
    name="correctness",
    value=0.9,
    trace_id="trace_id_here",
    observation_id="observation_id_here", # optional
    data_type="NUMERIC", # optional, inferred if not provided
    comment="Factually correct", # optional
)

# Method 2: Score current span/generation (within context)
with langfuse.start_as_current_observation(as_type="span", name="my-operation") as span:
    # Score the current span
    span.score(
        name="correctness",
        value=0.9,
        data_type="NUMERIC",
        comment="Factually correct"
    )

    # Score the trace
    span.score_trace(
        name="overall_quality",
        value=0.95,
        data_type="NUMERIC"
    )


# Method 3: Score via the current context
with langfuse.start_as_current_observation(as_type="span", name="my-operation"):
    # Score the current span
    langfuse.score_current_span(
        name="correctness",
        value=0.9,
        data_type="NUMERIC",
        comment="Factually correct"
    )

    # Score the trace
    langfuse.score_current_trace(
        name="overall_quality",
        value=0.95,
        data_type="NUMERIC"
    )

Categorical

Categorical 分数值必须以字符串提供。

python

from langfuse import get_client
langfuse = get_client()

# Method 1: Score via low-level method
langfuse.create_score(
    name="accuracy",
    value="partially correct",
    trace_id="trace_id_here",
    observation_id="observation_id_here", # optional
    data_type="CATEGORICAL", # optional, inferred if not provided
    comment="Some factual errors", # optional
)

# Method 2: Score current span/generation (within context)
with langfuse.start_as_current_observation(as_type="span", name="my-operation") as span:
    # Score the current span
    span.score(
        name="accuracy",
        value="partially correct",
        data_type="CATEGORICAL",
        comment="Some factual errors"
    )

    # Score the trace
    span.score_trace(
        name="overall_quality",
        value="partially correct",
        data_type="CATEGORICAL"
    )

# Method 3: Score via the current context
with langfuse.start_as_current_observation(as_type="span", name="my-operation"):
    # Score the current span
    langfuse.score_current_span(
        name="accuracy",
        value="partially correct",
        data_type="CATEGORICAL",
        comment="Some factual errors"
    )

    # Score the trace
    langfuse.score_current_trace(
        name="overall_quality",
        value="partially correct",
        data_type="CATEGORICAL"
    )

Boolean

Boolean 分数必须以 float 提供,其中 1 为 true,0 为 false。通过 v3 scores API 读取时,该值作为布尔值返回。关于 POST/GET 分数端点的更多细节,参见 API 参考。

python

from langfuse import get_client
langfuse = get_client()

# Method 1: Score via low-level method
langfuse.create_score(
    name="helpfulness",
    value=0, # 0 or 1
    trace_id="trace_id_here",
    observation_id="observation_id_here", # optional
    data_type="BOOLEAN", # required, numeric values without data type would be inferred as NUMERIC
    comment="Incorrect answer", # optional
)

# Method 2: Score current span/generation (within context)
with langfuse.start_as_current_observation(as_type="span", name="my-operation") as span:
    # Score the current span
    span.score(
        name="helpfulness",
        value=1, # 0 or 1
        data_type="BOOLEAN",
        comment="Very helpful response"
    )

    # Score the trace
    span.score_trace(
        name="overall_quality",
        value=1, # 0 or 1
        data_type="BOOLEAN"
    )
# Method 3: Score via the current context
with langfuse.start_as_current_observation(as_type="span", name="my-operation"):
    # Score the current span
    langfuse.score_current_span(
        name="helpfulness",
        value=1, # 0 or 1
        data_type="BOOLEAN",
        comment="Very helpful response"
    )

    # Score the trace
    langfuse.score_current_trace(
        name="overall_quality",
        value=1, # 0 or 1
        data_type="BOOLEAN"
    )

Text

Text 分数值必须以 1 到 500 字符之间的字符串提供。

python

from langfuse import get_client
langfuse = get_client()

# Method 1: Score via low-level method
langfuse.create_score(
    name="reviewer_notes",
    value="The response was helpful but could be more concise.",
    trace_id="trace_id_here",
    observation_id="observation_id_here", # optional
    data_type="TEXT", # optional, inferred if not provided
    comment="Reviewed by QA team", # optional
)

# Method 2: Score current span/generation (within context)
with langfuse.start_as_current_observation(as_type="span", name="my-operation") as span:
    # Score the current span
    span.score(
        name="reviewer_notes",
        value="The response was helpful but could be more concise.",
        data_type="TEXT",
        comment="Reviewed by QA team"
    )

    # Score the trace
    span.score_trace(
        name="overall_notes",
        value="Good quality overall, minor formatting issues.",
        data_type="TEXT"
    )

# Method 3: Score via the current context
with langfuse.start_as_current_observation(as_type="span", name="my-operation"):
    # Score the current span
    langfuse.score_current_span(
        name="reviewer_notes",
        value="The response was helpful but could be more concise.",
        data_type="TEXT",
        comment="Reviewed by QA team"
    )

    # Score the trace
    langfuse.score_current_trace(
        name="overall_notes",
        value="Good quality overall, minor formatting issues.",
        data_type="TEXT"
    )

Numeric

Numeric 分数值必须以 float 提供。

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

langfuse.score.create({
  id: "unique_id", // optional, can be used as an idempotency key to update the score subsequently
  traceId: message.traceId,
  observationId: message.generationId, // optional
  name: "correctness",
  value: 0.9,
  dataType: "NUMERIC", // optional, inferred if not provided
  comment: "Factually correct", // optional
});

// Flush the scores in short-lived environments
await langfuse.flush();

Categorical

Categorical 分数值必须以字符串提供。

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

langfuse.score.create({
  id: "unique_id", // optional, can be used as an idempotency key to update the score subsequently
  traceId: message.traceId,
  observationId: message.generationId, // optional
  name: "accuracy",
  value: "partially correct",
  dataType: "CATEGORICAL", // optional, inferred if not provided
  comment: "Factually correct", // optional
});

// Flush the scores in short-lived environments
await langfuse.flush();

Boolean

Boolean 分数必须以 float 提供,其中 1 为 true,0 为 false。通过 v3 scores API 读取时,该值作为布尔值返回。关于 POST/GET 分数端点的更多细节,参见 API 参考。

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

langfuse.score.create({
  id: "unique_id", // optional, can be used as an idempotency key to update the score subsequently
  traceId: message.traceId,
  observationId: message.generationId, // optional
  name: "helpfulness",
  value: 0, // 0 or 1
  dataType: "BOOLEAN", // required, numeric values without data type would be inferred as NUMERIC
  comment: "Incorrect answer", // optional
});

// Flush the scores in short-lived environments
await langfuse.flush();

Text

Text 分数值必须以 1 到 500 字符之间的字符串提供。

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

langfuse.score.create({
  id: "unique_id", // optional, can be used as an idempotency key to update the score subsequently
  traceId: message.traceId,
  observationId: message.generationId, // optional
  name: "reviewer_notes",
  value: "The response was helpful but could be more concise.",
  dataType: "TEXT", // optional, inferred if not provided
  comment: "Reviewed by QA team", // optional
});

// Flush the scores in short-lived environments
await langfuse.flush();

你也可以直接通过 REST API 创建分数。使用 HTTP Basic Auth 进行身份验证,以你的 Langfuse Public Key 为用户名,Secret Key 为密码。

Numeric

Numeric 分数值必须以 float 提供。

bash

curl -X POST https://cloud.langfuse.com/api/public/scores \
  -u "pk-lf-...":"sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "traceId": "trace_id_here",
    "observationId": "observation_id_here",
    "name": "correctness",
    "value": 0.9,
    "dataType": "NUMERIC",
    "comment": "Factually correct"
  }'

Categorical

Categorical 分数值必须以字符串提供。

bash

curl -X POST https://cloud.langfuse.com/api/public/scores \
  -u "pk-lf-...":"sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "traceId": "trace_id_here",
    "observationId": "observation_id_here",
    "name": "accuracy",
    "value": "partially correct",
    "dataType": "CATEGORICAL",
    "comment": "Some factual errors"
  }'

Boolean

Boolean 分数必须以 float 提供,其中 1 为 true,0 为 false。通过 v3 scores API 读取时,该值作为布尔值返回。

bash

curl -X POST https://cloud.langfuse.com/api/public/scores \
  -u "pk-lf-...":"sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "traceId": "trace_id_here",
    "observationId": "observation_id_here",
    "name": "helpfulness",
    "value": 0,
    "dataType": "BOOLEAN",
    "comment": "Incorrect answer"
  }'

Text

Text 分数值必须以 1 到 500 字符之间的字符串提供。

bash

curl -X POST https://cloud.langfuse.com/api/public/scores \
  -u "pk-lf-...":"sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "traceId": "trace_id_here",
    "observationId": "observation_id_here",
    "name": "reviewer_notes",
    "value": "The response was helpful but could be more concise.",
    "dataType": "TEXT",
    "comment": "Reviewed by QA team"
  }'

浏览器分数接入

当分数在前端代码中创建时(例如点赞/点踩用户反馈、星级评分或客户端质量信号),使用 @langfuse/browser。浏览器 SDK 只需要 Langfuse 公钥,并通过接入 API 立即发送每个分数。不要在浏览器代码中暴露密钥。

对于后端服务、脚本、CI 作业和评估流水线,请使用 @langfuse/client,如上面的 JS/TS SDK 示例所示。

bash

npm install @langfuse/browser

import { LangfuseBrowserClient } from "@langfuse/browser";

const langfuse = new LangfuseBrowserClient({
  publicKey: process.env.NEXT_PUBLIC_LANGFUSE_PUBLIC_KEY!,
  baseUrl: process.env.NEXT_PUBLIC_LANGFUSE_BASE_URL, // optional, defaults to https://cloud.langfuse.com
});

await langfuse.score({
  traceId: message.traceId,
  observationId: message.generationId, // optional
  id: `user-feedback-${message.traceId}`, // optional, use as an idempotency key
  name: "user-feedback",
  value: 1, // 1 for positive, 0 for negative
  dataType: "BOOLEAN",
  comment: "Helpful answer", // optional
});

score() 在接入成功后返回 ``。无需调用 flush()。

Session 级分数

要为整个 session 打分(而不将分数附加到 trace 或 observation),请仅提供 session_id(Python SDK)或 sessionId(JS/TS SDK 和 API)。

python

from langfuse import get_client
langfuse = get_client()

langfuse.create_score(
    name="session_quality",
    value=0.85,
    session_id="session_id_here",
    data_type="NUMERIC",
    comment="Overall conversation quality"
)

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

langfuse.score.create({
  name: "session_quality",
  value: 0.85,
  sessionId: "session_id_here",
  dataType: "NUMERIC",
  comment: "Overall conversation quality",
});

await langfuse.flush();

bash

curl -X POST https://cloud.langfuse.com/api/public/scores \
  -u "pk-lf-...":"sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session_id_here",
    "name": "session_quality",
    "value": 0.85,
    "dataType": "NUMERIC",
    "comment": "Overall conversation quality"
  }'

进阶

防止重复分数

默认情况下,Langfuse 允许在同一 trace 上有多个相同 name 的分数。如果你想随时间追踪分数的演进,或者例如你在同一 trace 上收到了多个用户反馈分数,这很有用。

在某些情况下,你想防止此行为或覆盖现有分数。分数由三个字段标识——其 id、其 name 和其日期(toDate(timestamp))——只有当三者都匹配时,新分数才会替换现有分数。为此,创建一个幂等键并在创建分数时将其作为 id(JS/TS)/ score_id(Python)传递(例如 trace_id-score_name),并在各次调用中保持 name 和 timestamp 不变。如果三者中任何一个不同——例如相同的 id 但不同的 name——你会得到一个额外的分数而非替换。

不要发送部分分数更新(仅更改的字段)并依赖 Langfuse 将它们合并到现有记录中。此合并仅在创建后的有限窗口内发生,已弃用,并将被移除。始终发送完整的分数。

关于 Langfuse 不可变数据模型的更多细节,参见如何更新 traces、observations 和分数。

强制分数配置

当你想为未来分析标准化分数时,分数配置很有帮助。

要强制分数配置,你可以在创建分数时提供 configId,以引用先前创建的 ScoreConfig。Score Configs 可以在 Langfuse UI 中或通过我们的 API 定义。查看我们关于如何创建和管理分数配置的指南。

每当你提供 ScoreConfig 时,分数数据将根据配置进行校验。适用以下规则:

分数名称:必须等于配置的名称
分数数据类型:提供时,必须匹配配置的数据类型
类型为 NUMERIC 时的分数值:值必须在配置中定义的最小值和最大值范围内(如果提供,min 和 max 是可选的,否则分别假设为 -∞ 和 +∞)
类型为 CATEGORICAL 时的分数值:值必须映射到配置中定义的类别之一
类型为 BOOLEAN 时的分数值:值必须等于 0 或 1
类型为 TEXT 时的分数值:值必须是最多 500 字符的非空字符串

Numeric 分数

接入数值分数时,你可以将值作为 float 提供。如果提供 configId,分数值将根据配置的数值范围校验,该范围可能由最小值和/或最大值定义。

python

from langfuse import get_client
langfuse = get_client()

# Method 1: Score via low-level method
langfuse.create_score(
    trace_id="trace_id_here",
    observation_id="observation_id_here", # optional
    session_id="session_id_here", # optional, ID of the session the score relates to
    name="accuracy",
    value=0.9,
    comment="Factually correct", # optional
    score_id="unique_id", # optional, can be used as an idempotency key to update the score subsequently
    config_id="78545-6565-3453654-43543", # optional, to ensure that the score follows a specific min/max value range
    data_type="NUMERIC" # optional, possibly inferred
)

# Method 2: Score within context
with langfuse.start_as_current_observation(as_type="span", name="my-operation") as span:
    span.score(
        name="accuracy",
        value=0.9,
        comment="Factually correct",
        config_id="78545-6565-3453654-43543",
        data_type="NUMERIC"
    )

Categorical 分数

分类分数用于评估落入特定类别的数据。接入分类分数时,你可以将值作为字符串提供。如果提供 configId,分数值将根据配置的类别校验。

python

from langfuse import get_client
langfuse = get_client()

# Method 1: Score via low-level method
langfuse.create_score(
    trace_id="trace_id_here",
    observation_id="observation_id_here", # optional
    name="correctness",
    value="correct",
    comment="Factually correct", # optional
    score_id="unique_id", # optional, can be used as an idempotency key to update the score subsequently
    config_id="12345-6565-3453654-43543", # optional, to ensure that the score maps to a specific category defined in a score config
    data_type="CATEGORICAL" # optional, possibly inferred
)

# Method 2: Score within context
with langfuse.start_as_current_observation(as_type="span", name="my-operation") as span:
    span.score(
        name="correctness",
        value="correct",
        comment="Factually correct",
        config_id="12345-6565-3453654-43543",
        data_type="CATEGORICAL"
    )

Boolean 分数

接入布尔分数时,你可以将值作为 float 提供。如果提供 configId,分数的名称和配置的名称必须匹配,且它们的数据类型也必须匹配。

python

from langfuse import get_client
langfuse = get_client()

# Method 1: Score via low-level method
langfuse.create_score(
    trace_id="trace_id_here",
    observation_id="observation_id_here", # optional
    name="helpfulness",
    value=1,
    comment="Factually correct", # optional
    score_id="unique_id", # optional, can be used as an idempotency key to update the score subsequently
    config_id="93547-6565-3453654-43543", # optional, can be used to infer the score data type and validate the score value
    data_type="BOOLEAN" # optional, possibly inferred
)

# Method 2: Score within context
with langfuse.start_as_current_observation(as_type="span", name="my-operation") as span:
    span.score(
        name="helpfulness",
        value=1,
        comment="Factually correct",
        config_id="93547-6565-3453654-43543",
        data_type="BOOLEAN"
    )

Text 分数

接入文本分数时,将值作为字符串提供(1–500 字符)。如果提供 configId,分数的名称和配置的名称必须匹配,且它们的数据类型也必须匹配。

python

from langfuse import get_client
langfuse = get_client()

# Method 1: Score via low-level method
langfuse.create_score(
    trace_id="trace_id_here",
    observation_id="observation_id_here", # optional
    name="reviewer_notes",
    value="The response was helpful but could be more concise.",
    comment="Reviewed by QA team", # optional
    score_id="unique_id", # optional, can be used as an idempotency key to update the score subsequently
    config_id="24680-6565-3453654-43543", # optional
    data_type="TEXT" # optional, possibly inferred
)

# Method 2: Score within context
with langfuse.start_as_current_observation(as_type="span", name="my-operation") as span:
    span.score(
        name="reviewer_notes",
        value="The response was helpful but could be more concise.",
        comment="Reviewed by QA team",
        config_id="24680-6565-3453654-43543",
        data_type="TEXT"
    )

Numeric 分数

接入数值分数时,你可以将值作为 float 提供。如果提供 configId,分数值将根据配置的数值范围校验,该范围可能由最小值和/或最大值定义。

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

langfuse.score.create({
  traceId: message.traceId,
  observationId: message.generationId, // optional
  name: "accuracy",
  value: 0.9,
  comment: "Factually correct", // optional
  id: "unique_id", // optional, can be used as an idempotency key to update the score subsequently
  configId: "78545-6565-3453654-43543", // optional, to ensure that the score follows a specific min/max value range
  dataType: "NUMERIC", // optional, possibly inferred
});

// Flush the scores in short-lived environments
await langfuse.flush();

Categorical 分数

分类分数用于评估落入特定类别的数据。接入分类分数时,你可以将值作为字符串提供。如果提供 configId,分数值将根据配置的类别校验。

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

langfuse.score.create({
  traceId: message.traceId,
  observationId: message.generationId, // optional
  name: "correctness",
  value: "correct",
  comment: "Factually correct", // optional
  id: "unique_id", // optional, can be used as an idempotency key to update the score subsequently
  configId: "12345-6565-3453654-43543", // optional, to ensure that a score maps to a specific category defined in a score config
  dataType: "CATEGORICAL", // optional, possibly inferred
});

// Flush the scores in short-lived environments
await langfuse.flush();

Boolean 分数

接入布尔分数时,你可以将值作为 float 提供。如果提供 configId,分数的名称和配置的名称必须匹配,且它们的数据类型也必须匹配。

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

langfuse.score.create({
  traceId: message.traceId,
  observationId: message.generationId, // optional
  name: "helpfulness",
  value: 1,
  comment: "Factually correct", // optional
  id: "unique_id", // optional, can be used as an idempotency key to update the score subsequently
  configId: "93547-6565-3453654-43543", // optional, can be used to infer the score data type and validate the score value
  dataType: "BOOLEAN", // optional, possibly inferred
});

// Flush the scores in short-lived environments
await langfuse.flush();

Text 分数

接入文本分数时,将值作为字符串提供(1–500 字符)。如果提供 configId,分数的名称和配置的名称必须匹配,且它们的数据类型也必须匹配。

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

langfuse.score.create({
  traceId: message.traceId,
  observationId: message.generationId, // optional
  name: "reviewer_notes",
  value: "The response was helpful but could be more concise.",
  comment: "Reviewed by QA team", // optional
  id: "unique_id", // optional, can be used as an idempotency key to update the score subsequently
  configId: "24680-6565-3453654-43543", // optional
  dataType: "TEXT", // optional, possibly inferred
});

// Flush the scores in short-lived environments
await langfuse.flush();

你也可以通过 REST API 提供 configId 来强制分数配置。

Numeric 分数

接入数值分数时,你可以将值作为 float 提供。如果提供 configId,分数值将根据配置的数值范围校验。

bash

curl -X POST https://cloud.langfuse.com/api/public/scores \
  -u "pk-lf-...":"sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "unique_id",
    "traceId": "trace_id_here",
    "observationId": "observation_id_here",
    "name": "accuracy",
    "value": 0.9,
    "dataType": "NUMERIC",
    "configId": "78545-6565-3453654-43543",
    "comment": "Factually correct"
  }'

Categorical 分数

分类分数用于评估落入特定类别的数据。如果提供 configId,分数值将根据配置的类别校验。

bash

curl -X POST https://cloud.langfuse.com/api/public/scores \
  -u "pk-lf-...":"sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "unique_id",
    "traceId": "trace_id_here",
    "observationId": "observation_id_here",
    "name": "correctness",
    "value": "correct",
    "dataType": "CATEGORICAL",
    "configId": "12345-6565-3453654-43543",
    "comment": "Factually correct"
  }'

Boolean 分数

接入布尔分数时,你可以将值作为 float 提供。如果提供 configId,分数的名称和配置的名称必须匹配,且它们的数据类型也必须匹配。

bash

curl -X POST https://cloud.langfuse.com/api/public/scores \
  -u "pk-lf-...":"sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "unique_id",
    "traceId": "trace_id_here",
    "observationId": "observation_id_here",
    "name": "helpfulness",
    "value": 1,
    "dataType": "BOOLEAN",
    "configId": "93547-6565-3453654-43543",
    "comment": "Factually correct"
  }'

Text 分数

接入文本分数时,将值作为字符串提供(1–500 字符)。如果提供 configId,分数的名称和配置的名称必须匹配,且它们的数据类型也必须匹配。

bash

curl -X POST https://cloud.langfuse.com/api/public/scores \
  -u "pk-lf-...":"sk-lf-..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "unique_id",
    "traceId": "trace_id_here",
    "observationId": "observation_id_here",
    "name": "reviewer_notes",
    "value": "The response was helpful but could be more concise.",
    "dataType": "TEXT",
    "configId": "24680-6565-3453654-43543",
    "comment": "Reviewed by QA team"
  }'

关于 POST/GET 分数配置端点的更多细节,参见 API 参考。

推断的分数属性

某些分数属性可能会根据你的输入被推断:

如果你不提供分数数据类型,它将始终被推断。细节见下表。
对于布尔和分类分数,我们会尽可能以数值和字符串格式提供分数值。未作为输入提供的分数值格式,即翻译后的值,在下表中称为推断值。
通过 v3 scores API 读取时,布尔分数作为单个布尔 value 返回。
对于分类分数,始终提供字符串表示,且仅当提供了 ScoreConfig 时才会产生类别的数值映射。

详细示例:

Numeric 分数

例如,假设你想接入一个数值分数来衡量准确性。我们在下面包含了一个可能的分数接入场景表。

值	数据类型	Config Id	描述	推断的数据类型	有效
`0.9`	`Null`	`Null`	数据类型被推断	`NUMERIC`	是
`0.9`	`NUMERIC`	`Null`	无属性被推断		是
`depth`	`NUMERIC`	`Null`	错误:值的数据类型与提供的数据类型不匹配		否
`0.9`	`NUMERIC`	`78545`	无属性被推断		取决于配置校验
`0.9`	`Null`	`78545`	数据类型被推断	`NUMERIC`	取决于配置校验
`depth`	`NUMERIC`	`78545`	错误:值的数据类型与提供的数据类型不匹配		否

Categorical 分数

例如,假设你想接入一个分类分数来衡量正确性。我们在下面包含了一个可能的分数接入场景表。

值	数据类型	Config Id	描述	推断的数据类型	推断的值表示	有效
`correct`	`Null`	`Null`	数据类型被推断	`CATEGORICAL`		是
`correct`	`CATEGORICAL`	`Null`	无属性被推断			是
`1`	`CATEGORICAL`	`Null`	错误:值的数据类型与提供的数据类型不匹配			否
`correct`	`CATEGORICAL`	`12345`	数值被推断		`4` 数值配置类别映射	取决于配置校验
`correct`	`NULL`	`12345`	数据类型被推断	`CATEGORICAL`		取决于配置校验
`1`	`CATEGORICAL`	`12345`	错误:值的数据类型与提供的数据类型不匹配			否

Boolean 分数

例如,假设你想接入一个布尔分数来衡量有用性。我们在下面包含了一个可能的分数接入场景表。

值	数据类型	Config Id	描述	推断的数据类型	推断的值表示	有效
`1`	`BOOLEAN`	`Null`	值的字符串等价被推断		`True`	是
`true`	`BOOLEAN`	`Null`	错误:值的数据类型与提供的数据类型不匹配			否
`3`	`BOOLEAN`	`Null`	错误:布尔数据类型期望 `0` 或 `1` 作为输入值			否
`0.9`	`Null`	`93547`	数据类型和值的字符串等价被推断	`BOOLEAN`	`True`	取决于配置校验
`depth`	`BOOLEAN`	`93547`	错误:值的数据类型与提供的数据类型不匹配			否

Text 分数

例如,假设你想接入一个文本分数来捕获审阅者备注。文本分数必须是最多 500 字符的非空字符串。

值	数据类型	Config Id	描述	推断的数据类型	有效
`"Good response"`	`Null`	`Null`	数据类型被推断	`TEXT`	是
`"Good response"`	`TEXT`	`Null`	无属性被推断		是
`0.9`	`TEXT`	`Null`	错误:值的数据类型与提供的数据类型不匹配		否
`"Good response"`	`TEXT`	`24680`	无属性被推断		取决于配置校验
`"Good response"`	`Null`	`24680`	数据类型被推断	`TEXT`	取决于配置校验
`""`	`TEXT`	`Null`	错误:文本分数必须非空		否

通过 API/SDK 更新现有分数

创建分数时,你可以提供可选的 id(JS/TS)/ score_id(Python)参数。重新接入的分数仅当其 id、name 和 timestamp(按日期粒度,toDate(timestamp))都匹配时才覆盖现有分数——仅匹配的 id 是不够的,任何差异都会创建重复而非更新。

要在不先获取现有分数的情况下覆盖分数,请在最初创建分数时设置一个稳定的 id 作为幂等键,并在后续调用中保持 name 和 timestamp 不变。细节参见防止重复分数。

通过 API/SDK 打分

通过 API/SDK 接入分数

Trace 或 Observation 级分数

Numeric

Categorical

Boolean

Text

Numeric

Categorical

Boolean

Text

Numeric

Categorical

Boolean

Text

浏览器分数接入

Session 级分数

进阶

防止重复分数

强制分数配置

Numeric 分数

Categorical 分数

Boolean 分数

Text 分数

Numeric 分数

Categorical 分数

Boolean 分数

Text 分数

Numeric 分数

Categorical 分数

Boolean 分数

Text 分数

推断的分数属性

Numeric 分数

Categorical 分数

Boolean 分数

Text 分数

通过 API/SDK 更新现有分数

相关指南