rg.Suggestion

用于与 Argilla 记录建议互动的类。建议通常由模型预测创建，与 Response 不同，后者通常由 UI 中的用户创建或从数据源作为标签使用。

使用示例

添加带有建议的记录

建议可以直接添加到记录中，也可以通过字典结构添加。以下示例演示如何将建议添加到记录对象，以及如何从记录对象访问建议

从字典中添加响应，其中键是问题名称，值是响应

dataset.records.log(
    [
        {
            "text": "Hello World, how are you?",
            "label": "negative", # this will be used as a suggestion
        },
    ]
)

如果您的数据包含建议的分数，您也可以通过 mapping 参数添加它们。以下示例演示如何将带有分数的建议添加到记录对象

dataset.records.log(
    [
        {
            "prompt": "Hello World, how are you?",
            "label": "negative",  # this will be used as a suggestion
            "score": 0.9,  # this will be used as the suggestion score
            "model": "model_name",  # this will be used as the suggestion agent
        },
    ],
    mapping={
        "score": "label.suggestion.score",
        "model": "label.suggestion.agent",
    },  # `label` is the question name in the dataset settings
)

或者，直接实例化 Record 和相关的 Suggestions 对象，就像这样

dataset.records.log(
    [
        rg.Record(
            fields={"text": "Hello World, how are you?"},
            suggestions=[rg.Suggestion("negative", "label", score=0.9, agent="model_name")],
        )
    ]
)

迭代带有建议的记录

与响应一样，可以通过问题名称作为记录的属性从 Record 访问建议。因此，如果问题名为 label，则可以将建议作为 record.label 访问。以下示例演示如何从记录对象访问建议

for record in dataset.records(with_suggestions=True):
    print(record.suggestions["label"].value)

我们还可以在迭代记录时使用 add 方法向记录添加建议

for record in dataset.records(with_suggestions=True):
    if not record.suggestions["label"]: # (1)
        record.suggestions.add(
            rg.Suggestion("positive", "label", score=0.9, agent="model_name")
        ) # (2)

1. 验证记录是否包含建议
2. 如果记录尚未包含建议，则向记录添加建议

每种 Question 类型的格式

根据 Question 类型，可能需要以稍微不同的方式格式化响应。

对于 LabelQuestion对于 MultiLabelQuestion对于 RankingQuestion对于 RatingQuestion对于 SpanQuestion对于 TextQuestion

rg.Suggestion(
    question_name="label",
    value="positive",
    score=0.9,
    agent="model_name"
)

rg.Suggestion(
    question_name="multi-label",
    value=["positive", "negative"],
    score=0.9,
    agent="model_name"
)

rg.Suggestion(
    question_name="rank",
    value=["1", "3", "2"],
    score=0.9,
    agent="model_name"
)

rg.Suggestion(
    question_name="rating",
    value=4,
    score=0.9,
    agent="model_name"
)

rg.Suggestion(
    question_name="span",
    value=[{"start": 0, "end": 9, "label": "MISC"}],
    score=0.9,
    agent="model_name"
)

rg.Suggestion(
    question_name="text",
    value="value",
    score=0.9,
    agent="model_name"
)

---

Suggestion

基类：Resource

用于与 Argilla 建议互动的类。建议通常是记录的模型预测。建议在用户界面中呈现为“提示”或“建议”，供用户查看并接受或拒绝。

属性

名称	类型	描述
question_name	str	建议所针对的问题的名称。
value	str	建议的值
score	float	建议的分数。例如，模型预测的概率。
agent	str	创建建议的代理。例如，模型名称。
type	str	建议的类型，可以是“model”或“human”。

源代码位于 src/argilla/suggestions.py

class Suggestion(Resource):
    """Class for interacting with Argilla Suggestions. Suggestions are typically model predictions for records.
    Suggestions are rendered in the user interfaces as 'hints' or 'suggestions' for the user to review and accept or reject.

    Attributes:
        question_name (str): The name of the question that the suggestion is for.
        value (str): The value of the suggestion
        score (float): The score of the suggestion. For example, the probability of the model prediction.
        agent (str): The agent that created the suggestion. For example, the model name.
        type (str): The type of suggestion, either 'model' or 'human'.
    """

    _model: SuggestionModel

    def __init__(
        self,
        question_name: str,
        value: Any,
        score: Union[float, List[float], None] = None,
        agent: Optional[str] = None,
        type: Optional[Literal["model", "human"]] = None,
        _record: Optional["Record"] = None,
    ) -> None:
        super().__init__()

        if question_name is None:
            raise ValueError("question_name is required")
        if value is None:
            raise ValueError("value is required")

        self._record = _record
        self._model = SuggestionModel(
            question_name=question_name,
            value=value,
            type=type,
            score=score,
            agent=agent,
        )

    ##############################
    # Properties
    ##############################

    @property
    def value(self) -> Any:
        """The value of the suggestion."""
        return self._model.value

    @property
    def question_name(self) -> Optional[str]:
        """The name of the question that the suggestion is for."""
        return self._model.question_name

    @question_name.setter
    def question_name(self, value: str) -> None:
        self._model.question_name = value

    @property
    def type(self) -> Optional[Literal["model", "human"]]:
        """The type of suggestion, either 'model' or 'human'."""
        return self._model.type

    @property
    def score(self) -> Optional[Union[float, List[float]]]:
        """The score of the suggestion."""
        return self._model.score

    @score.setter
    def score(self, value: float) -> None:
        self._model.score = value

    @property
    def agent(self) -> Optional[str]:
        """The agent that created the suggestion."""
        return self._model.agent

    @agent.setter
    def agent(self, value: str) -> None:
        self._model.agent = value

    @property
    def record(self) -> Optional["Record"]:
        """The record that the suggestion is for."""
        return self._record

    @record.setter
    def record(self, value: "Record") -> None:
        self._record = value

    @classmethod
    def from_model(cls, model: SuggestionModel, record: "Record") -> "Suggestion":
        question = record.dataset.settings.questions[model.question_id]
        model.question_name = question.name
        model.value = cls.__from_model_value(model.value, question)

        instance = cls(question.name, model.value, _record=record)
        instance._model = model

        return instance

    def api_model(self) -> SuggestionModel:
        if self.record is None or self.record.dataset is None:
            return self._model

        question = self.record.dataset.settings.questions[self.question_name]
        if question:
            return SuggestionModel(
                value=self.__to_model_value(self.value, question),
                question_name=None if not question else question.name,
                question_id=None if not question else question.id,
                type=self._model.type,
                score=self._model.score,
                agent=self._model.agent,
                id=self._model.id,
            )
        else:
            raise RecordSuggestionsError(
                f"Record suggestion is invalid because question with name={self.question_name} does not exist in the dataset ({self.record.dataset.name}). Available questions are: {list(self.record.dataset.settings.questions._properties_by_name.keys())}"
            )

    @classmethod
    def __to_model_value(cls, value: Any, question: "QuestionType") -> Any:
        if isinstance(question, RankingQuestion):
            return cls.__ranking_to_model_value(value)
        return value

    @classmethod
    def __from_model_value(cls, value: Any, question: "QuestionType") -> Any:
        if isinstance(question, RankingQuestion):
            return cls.__ranking_from_model_value(value)
        return value

    @classmethod
    def __ranking_from_model_value(cls, value: List[Dict[str, Any]]) -> List[str]:
        return [v["value"] for v in value]

    @classmethod
    def __ranking_to_model_value(cls, value: List[str]) -> List[Dict[str, str]]:
        return [{"value": str(v)} for v in value]

value: Any property

建议的值。

question_name: Optional[str] property writable

建议所针对的问题的名称。

type: Optional[Literal['model', 'human']] property

建议的类型，可以是“model”或“human”。

score: Optional[Union[float, List[float]]] property writable

建议的分数。

agent: Optional[str] property writable

创建建议的代理。

record: Optional[Record] property writable

建议所针对的记录。