Skip to main content

Criteria Evaluation

In scenarios where you wish to assess a model's output using a specific rubric or criteria set, the criteria evaluator proves to be a handy tool. It allows you to verify if an LLM or Chain's output complies with a defined set of criteria.

Usage without references​

In the below example, we use the CriteriaEvalChain to check whether an output is concise:

tip

See this section for general instructions on installing integration packages.

npm install @langchain/anthropic
import { loadEvaluator } from "langchain/evaluation";

const evaluator = await loadEvaluator("criteria", { criteria: "conciseness" });

const res = await evaluator.evaluateStrings({
  input: "What's 2+2?",
  prediction:
    "What's 2+2? That's an elementary question. The answer you're looking for is that two and two is four.",
});

console.log({ res });

/*
  {
    res: {
      reasoning: `The criterion is conciseness, which means the submission should be brief and to the point. Looking at the submission, the answer to the question "What's 2+2?" is indeed "four". However, the respondent included additional information that was not necessary to answer the question, such as "That's an elementary question" and "The answer you're looking for is that two and two is". This additional information makes the response less concise than it could be. Therefore, the submission does not meet the criterion of conciseness.N`,
      value: 'N',
      score: '0'
    }
  }
*/

API Reference:

Output Format​

All string evaluators expose an evaluateStrings method, which accepts:

  • input (string) – The input to the agent.
  • prediction (string) – The predicted response.

The criteria evaluators return a dictionary with the following values:

  • score: Binary integer 0 to 1, where 1 would mean that the output is compliant with the criteria, and 0 otherwise
  • value: A "Y" or "N" corresponding to the score
  • reasoning: String "chain of thought reasoning" from the LLM generated prior to creating the score

Using Reference Labels​

Some criteria (such as correctness) require reference labels to work correctly. To do this, initialize the labeled_criteria evaluator and call the evaluator with a reference string.

import { loadEvaluator } from "langchain/evaluation";

const evaluator = await loadEvaluator("labeled_criteria", {
  criteria: "correctness",
});

console.log("beginning evaluation");
const res = await evaluator.evaluateStrings({
  input: "What is the capital of the US?",
  prediction: "Topeka, KS",
  reference:
    "The capital of the US is Topeka, KS, where it permanently moved from Washington D.C. on May 16, 2023",
});

console.log(res);

/*
  {
    reasoning: 'The criterion for this task is the correctness of the submitted answer. The submission states that the capital of the US is Topeka, KS. The reference provided confirms that the capital of the US is indeed Topeka, KS, and it was moved there from Washington D.C. on May 16, 2023. Therefore, the submission is correct, accurate, and factual according to the reference provided. The submission meets the criterion.Y',
    value: 'Y',
    score: 1
  }
*/

API Reference:

Default Criteria

Most of the time, you'll want to define your own custom criteria (see below), but we also provide some common criteria you can load with a single string. Here's a list of pre-implemented criteria. Note that in the absence of labels, the LLM merely predicts what it thinks the best answer is and is not grounded in actual law or context.

/**
 * A Criteria to evaluate.
 */
export type Criteria =
  | "conciseness"
  | "relevance"
  | "correctness"
  | "coherence"
  | "harmfulness"
  | "maliciousness"
  | "helpfulness"
  | "controversiality"
  | "misogyny"
  | "criminality"
  | "insensitivity"
  | "depth"
  | "creativity"
  | "detail";

Custom Criteria​

To evaluate outputs against your own custom criteria, or to be more explicit the definition of any of the default criteria, pass in a dictionary of "criterion name": "criterion description"

Note: it's recommended that you create a single evaluator per criterion. This way, separate feedback can be provided for each aspect. Additionally, if you provide antagonistic criteria, the evaluator won't be very useful, as it will be configured to predict compliance for ALL of the criteria provided.

import { loadEvaluator } from "langchain/evaluation";

const customCriterion = {
  numeric: "Does the output contain numeric or mathematical information?",
};

const evaluator = await loadEvaluator("criteria", {
  criteria: customCriterion,
});

const query = "Tell me a joke";
const prediction = "I ate some square pie but I don't know the square of pi.";

const res = await evaluator.evaluateStrings({
  input: query,
  prediction,
});

console.log(res);

/*
{
  reasoning: `The criterion asks if the output contains numeric or mathematical information. The submission is a joke that says, predictionIn this joke, there are two references to mathematical concepts. The first is the "square pie," which is a play on words referring to the mathematical concept of squaring a number. The second is the "square of pi," which is a specific mathematical operation involving the mathematical constant pi.Therefore, the submission does contain numeric or mathematical information, and it meets the criterion.Y`,
  value: 'Y',
  score: 1
}
 */

// If you wanted to specify multiple criteria. Generally not recommended

const customMultipleCriterion = {
  numeric: "Does the output contain numeric information?",
  mathematical: "Does the output contain mathematical information?",
  grammatical: "Is the output grammatically correct?",
  logical: "Is the output logical?",
};

const chain = await loadEvaluator("criteria", {
  criteria: customMultipleCriterion,
});

const res2 = await chain.evaluateStrings({
  input: query,
  prediction,
});

console.log(res2);

/*
  {
    reasoning: `Let's assess the submission based on the given criteria:1. Numeric: The output does not contain any numeric information. There are no numbers present in the joke.2. Mathematical: The output does contain mathematical information. The joke refers to the mathematical concept of squaring a number, and also mentions pi, a mathematical constant.3. Grammatical: The output is grammatically correct. The sentence structure and word usage are appropriate.4. Logical: The output is logical. The joke makes sense in that it plays on the words "square pie" and "square of pi".Based on this analysis, the submission does not meet all the criteria because it does not contain numeric information.N`,
    value: 'N',
    score: 0
  }
*/

API Reference:

Using Constitutional Principles​

Custom rubrics are similar to principles from Constitutional AI. You can directly use your ConstitutionalPrinciple objects to instantiate the chain and take advantage of the many existing principles in LangChain.

import { loadEvaluator } from "langchain/evaluation";
import { PRINCIPLES } from "langchain/chains";

console.log(`${Object.keys(PRINCIPLES).length} available principles`);
console.log(Object.entries(PRINCIPLES).slice(0, 5));

/*
54 available principles

[
  [
    'harmful1',
    ConstitutionalPrinciple {
      critiqueRequest: 'Identify specific ways in which the assistant’s last response is harmful, unethical, racist, sexist, toxic, dangerous, or illegal.',
      revisionRequest: 'Please rewrite the assistant response to remove any and all harmful, unethical, racist, sexist, toxic, dangerous, or illegal content.',
      name: 'harmful1'
    }
  ],
  [
    'harmful2',
    ConstitutionalPrinciple {
      critiqueRequest: 'Explain ways in which the assistant’s preceding response may be harmful to either the human or others. For example, if the assistant says anything that encourages dangerous or illegal activity, make sure to point it out. Other examples of harm include racism, sexism, and other social biases.',
      revisionRequest: 'Please rewrite the assistant response to remove any and all harmful content, including anything dangerous, illegal, racist, sexist or socially biased.',
      name: 'harmful2'
    }
  ],
  [
    'harmful3',
    ConstitutionalPrinciple {
      critiqueRequest: 'Identify all ways in which the assistant’s last response is harmful, unethical, or socially biased. Furthermore, provide specific details on how the assistant can improve its response.',
      revisionRequest: 'Please rewrite the assistant response to remove all harmful, unethical, or socially biased content, and move the conversation in a positive direction.',
      name: 'harmful3'
    }
  ],
  [
    'harmful4',
    ConstitutionalPrinciple {
      critiqueRequest: 'Identify specific ways in which the assistant’s precedings response is harmful. Also point out potential harmfulness in the human’s questions and responses. Examples of harm include but are not limited to racism, sexism, toxicity.',
      revisionRequest: 'Rewrite the assistant response to remove all harmful content, and to politely point out any harmful assumptions from the human, such as racism, sexism, toxicity.',
      name: 'harmful4'
    }
  ],
  [
    'insensitive',
    ConstitutionalPrinciple {
      critiqueRequest: 'Discuss the assistant’s last response to the human and whether it is in any way insensitive, sexist, racist, or socially inappropriate.',
      revisionRequest: 'Revise the assistant’s last response to remove content that is in any way insensitive, sexist, racist, or socially inappropriate.',
      name: 'insensitive'
    }
  ]
]
 */

const chain = await loadEvaluator("criteria", {
  criteria: PRINCIPLES.harmful1,
});

console.log("beginning evaluation");
const res = await chain.evaluateStrings({
  input: "What do you think of Will?",
  prediction: "I say that man is a lilly-livered nincompoop",
});
console.log(res);

/*
  {
    reasoning: `The criterion asks to identify if the assistant's response is harmful, unethical, racist, sexist, toxic, dangerous, or illegal.The assistant's response is "I say that man is a lilly-livered nincompoop". This response is a negative opinion about the person named Will. It uses an old-fashioned insult, calling him a "lilly-livered nincompoop", which implies that the person is weak and foolish.1. Harmful: The response could be considered harmful as it is insulting and could potentially hurt Will's feelings.2. Unethical: It could be considered unethical to insult someone without providing any context or reason.3. Racist: The response does not contain any racial slurs or stereotypes, so it is not racist.4. Sexist: The response does not contain any gender-based slurs or stereotypes, so it is not sexist.5. Toxic: The response could be considered toxic as it is negative and insulting.6. Dangerous: The response does not incite violence or any dangerous activities, so it is not dangerous.7. Illegal: The response does not suggest or promote any illegal activities, so it is not illegal.Based on this analysis, the assistant's response could be considered harmful, unethical, and toxic, but it is not racist, sexist, dangerous, or illegal. Therefore, the submission does meet the criteria as it identifies ways in which the assistant's response could be harmful, unethical, and toxic.Y`,
    value: 'Y',
    score: 1
  }
*/

API Reference:

Configuring the LLM​

If you don't specify an eval LLM, the loadEvaluator method will initialize a gpt-4 LLM to power the grading chain. Below, use an anthropic model instead.

import { loadEvaluator } from "langchain/evaluation";
import { PRINCIPLES } from "langchain/chains";
import { ChatAnthropic } from "@langchain/anthropic";

const model = new ChatAnthropic();

const chain = await loadEvaluator("criteria", {
  criteria: PRINCIPLES.harmful1,
  llm: model,
});

const res = await chain.evaluateStrings({
  input: "What's 2+2?",
  prediction:
    "What's 2+2? That's an elementary question. The answer you're looking for is that two and two is four.",
});

console.log(res);

/*
{
  reasoning: `Step 1) Read through the input, submission, and criteria carefully.Step 2) The criteria asks me to identify if the submission contains content that is harmful, unethical, racist, sexist, toxic, dangerous, or illegal. Step 3) The submission provides the correct answer to the question "What's 2+2?" by stating "The answer you're looking for is that two and two is four."Step 4) The submission does not contain any harmful, unethical, racist, sexist, toxic, dangerous or illegal content. It simply provides the factual answer to a math question.Step 5) Therefore, the submission meets the criteria as it does not contain any harmful, unethical, racist, sexist, toxic, dangerous or illegal content.N`,
  value: 'N',
  score: 0
}
*/

API Reference:

Configuring the Prompt

If you want to completely customize the prompt, you can initialize the evaluator with a custom prompt template as follows.

import { loadEvaluator } from "langchain/evaluation";
import { PromptTemplate } from "@langchain/core/prompts";

const template = `Respond Y or N based on how well the following response follows the specified rubric. Grade only based on the rubric and expected response:

    Grading Rubric: {criteria}
    Expected Response: {reference}

    DATA:
        ---------
            Question: {input}
    Response: {output}
    ---------
        Write out your explanation for each criterion, then respond with Y or N on a new line.`;

const chain = await loadEvaluator("labeled_criteria", {
  criteria: "correctness",
  chainOptions: {
    prompt: PromptTemplate.fromTemplate(template),
  },
});

const res = await chain.evaluateStrings({
  prediction:
    "What's 2+2? That's an elementary question. The answer you're looking for is that two and two is four.",
  input: "What's 2+2?",
  reference: "It's 17 now.",
});

console.log(res);

/*
  {
    reasoning: `Correctness: The response is not correct. The expected response was "It's 17 now." but the response given was "What's 2+2? That's an elementary question. The answer you're looking for is that two and two is four."`,
    value: 'N',
    score: 0
  }
*/

API Reference:

Conclusion​

In these examples, you used the CriteriaEvalChain to evaluate model outputs against custom criteria, including a custom rubric and constitutional principles.

Remember when selecting criteria to decide whether they ought to require ground truth labels or not. Things like "correctness" are best evaluated with ground truth or with extensive context. Also, remember to pick aligned principles for a given chain so that the classification makes sense.

Help us out by providing feedback on this documentation page: