# \[Guide\] Writing Effective Evals

**URL:** <https://community.palantir.com/t/guide-writing-effective-evals/2856>\
**Category:** Ask the Community\
**Tags:** aip-logic\
**Created:** [February 11, 2025, 3:09pm UTC](https://community.palantir.com/t/guide-writing-effective-evals/2856 "2025-02-11T15:09:53Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![colton](https://avatars.discourse-cdn.com/v4/letter/c/e5b9ba/32.png) [@colton](https://community.palantir.com/u/colton)\
**Post date:** [February 11, 2025, 3:09pm UTC](https://community.palantir.com/t/guide-writing-effective-evals/2856/1 "2025-02-11T15:09:54Z")

</div>

// We’re working on better docs for [AIP Evals](https://www.palantir.com/docs/foundry/logic/evaluations-overview), but in the interim wanted to share some best practices and learnings from Palantir engineers putting evals to work in the field. For what Evals are at a high level and why they’re critical to production AIP workflows, check out this [introductory blog post](https://blog.palantir.com/from-prototype-to-production-engineering-responsible-ai-3-ea18818cd222) and this [deep dive](https://blog.palantir.com/evaluating-generative-ai-a-field-manual-0cdaf574a9e1). This post pulls together learnings from Palantir's [Privacy and Civil Liberties (PCL) dev team](https://www.palantir.com/pcl/) from embedding with Palantir engineers in the field. The case studies are representative examples of how Evals were applied to various AIP Logic implementations and how those implementations evolved based on what was learned from the evaluation results.

## Why write Evals?

- **Adapt at warp speed** : Evals let you pivot quickly (i.e., compare and switch between models and model versions) and keep switching costs low without compromising quality. You’ll know exactly what changed and why. 
- **Spot issues fast** : Testing prevents accidental regressions in your AI as you keep iterating. 
- **Build trust & alignment** : Show customers/users your AI meets real-world requirements — and keeps meeting them after every change. 

Even if you only have limited time to invest in writing evals, the payoff in clarity and reliability is huge. 
## Quick Overview of the Evals Workflow
 // Here’s a [worksheet](https://community.palantir.com/t/worksheet-evals-field-manual/2855) that steps through each of these stages in granular detail 

- **Define the Problem & AI Task** : Identify exactly what you’re using AI for (e.g., summarizing documents, classifying tickets, extracting entities, etc.). 
- **Collect/Create Test Cases** : Gather real data and/or create synthetic test cases that represent a variety of inputs. 
- **Decide on Evaluation Methods** : 

  - Deterministic checks (e.g., regex, exact match, numeric ranges) 
  - LLM-as-Judge for open-ended/subjective output (e.g., comprehensiveness, groundedness) 
  - Ideally: keep to simple pass/fail outputs for your evaluators 

- **Run, Observe, Fix** : Evaluate, see where it fails, fix the system. 
- **Repeat** : Over time, you’ll refine your tests, add new ones, and keep track of improvements. 

> **Tip** : Start small; add complexities later if needed. Don’t let perfect be the enemy of good — **ship an initial eval suite** and learn from it.

## Example #1: Summarization

### Problem Overview
 A function takes in a block of text and returns a summary. 
### What Evaluators We Used

- **Out of the box in AIP Evals**

  - String length check (summary must be \< n characters). 
  - Regex match (summary must be, e.g., bulleted) 
  - Keyword checker (e.g., “X,” “Y,” if they appear in the source). 

- **Custom No-Code (Evaluator backed by AIP Logic)**

  - LLM-as-a-Judge: “Does this {summary bullet, sentence, etc.} accurately reflect [the input text]?” 

    -  

 ![LLM-as-a-Judge in AIP Logic](https://canada1.discourse-cdn.com/palantir/original/2X/5/5e1fd037c3c9a8ed01551240618940a53d92ccf0.png)

    - We’ve found it effective to force the LLM to return quotes from the input text that you can use to validate your validator. Helpful when writing evals on this evaluator.  
    - Provide 2–3 examples of grounded vs. ungrounded summaries as few-shot examples so the LLM judge sees how a “pass” vs. “fail” looks.  

- **Custom Pro-Code (Evaluator backed by a Function)**  

  - Word count (summary must be ~150 words)  

### What We Changed As A Result
  

- Prompt Engineering: For example, “Ensure you mention any mention of X or Z explicitly in the summary.” or “Be concise”  

## Example #2: Classification
  

### Problem Overview
  
A function takes in some input and classifies it into two or more categories (ex: yes/no, pass/fail, score 1-10). Optional (but recommended): the LLM is prompted to provide an explanation prior to the output classification.  

### What Evaluators we Used
  

- **Out of the box in AIP Evals**  

  - Exact string/integer match (expected vs. actual classification)  
  - String length (on explanation)  
  - Keyword checker (on explanation)  
  - Numeric range (for scores)  

- **Custom No-Code (Evaluator backed by AIP Logic)**  

  - LLM-as-a-Judge: e.g., “Does this output explanation align with this output classification?”  

### What we changed & Impact of iterating with Evals
  

- Prompt Engineering: Refine the classification criteria for each potential output, give further instructions for more concise/relevant explanations, etc.  
- OAG (Ontology-assisted-generation): Even better if you can represent the classification criteria as an object type, rather than hardcoding it into the prompt  
- Use of tools and deterministic processes: augment LLM use with deterministic functions and tools for more consistent results.  
-   
  ![Custom Evals dashboard for binary classification](https://canada1.discourse-cdn.com/palantir/original/2X/8/86645aebf34f8461ac3c6c4aec0cc14d177994ed.png)  
 

## Example #3: Semantic Search
  

### Problem Overview
  
A function takes in a search query and returns the top K most semantically similar objects.  

### What Evaluators We Used
  

- **Out of the box in AIP Evals**  

  - Exact Object match (e.g., if you’re returning the top search result)  

- **Custom No-Code (Evaluator backed by AIP Logic)**  

  - LLM-as-a-Judge: Score/classify each search result based on quality/relevance, average it.  

- **Custom Pro-Code (Evaluator backed by a Function)**  

  - Recall %: count the number of relevant results vs. the number of total results in the search  

### What We Changed & Impact of Iterating with Evals
  

- Upgrade Embedding Model: We switched from text-embedding-ada-002 to text-embedding-3-small.  
- Tune Queries/Embedding Process: Tuned logic to generate more descriptive search queries / embed more semantically relevant properties of embedded objects.  
- **Impact** : With one partner, we saw the quality of search results improve across the board. Raised both the floor + ceiling of result quality.  
-   
  ![Evals results showing improvements](https://canada1.discourse-cdn.com/palantir/original/2X/8/8738147242176a280c4e7c692caceccb517ec27e.png)  
 

## Key Patterns Across Examples
  

- **Start with a small set of pass/fail**  **checks**.  

  - Don’t overcomplicate scoring scales / rubrics.  

- **Bring domain experts in to define what “correct” means**.  

  - Your goal is to use them to sniff out hidden rules or corner cases + codify their tribal knowledge as evals (both for your main function under test + also for any LLM-as-a-Judge evaluators).  

- **Use real data + synthetic data:**  

  - Real data captures actual complexities, synthetic helps push edge cases systematically.  

- **LLM-as-Judge is powerful** but needs clear prompts and examples of “pass vs. fail.”  

  - _Write Evals for your LLM-as-Judge functions_ to ensure alignment between their outputs + human preferences. You can often use the same test cases between your main LLM function and your LLM-as-a-Judge functions.  

- **Watch out for** :  

  - _Cost or latency overhead_ (as we all know, LLM calls aren’t free / instantaneous).  
  - _When to fix prompt instructions vs. update few-shot examples vs. add new tests._  

## Closing Advice
  

- **Build Quick, Update Often** : Even a single day of test writing can reveal major failures. Add or refine tests each time you find an error.  
- **Don’t Stress Perfection** : It’s normal to accept some failing test cases, especially if you’re rapidly iterating. Decide thresholds that fit your + your customers’ risk tolerance.  
- **Start small** : _A handful of carefully chosen test cases with pass/fail checks_ can work wonders.  
- **Evals are not optional** if you want to maintain velocity with confidence — they’re a minimal investment that pays off with every iteration.  

## References & Further Reading
  

- For basic AIP Evals setup: [From Prototype to Production: Testing and Evaluating AI Systems with AIP Evals (PCL Blog)](https://blog.palantir.com/from-prototype-to-production-engineering-responsible-ai-3-ea18818cd222)  
- For a deep dive into the theory/tradecraft of writing effective evals: [Evaluating Generative AI: A Field Manual (PCL Blog)](https://blog.palantir.com/evaluating-generative-ai-a-field-manual-0cdaf574a9e1)  
- Other useful blog posts:  

  - [Your AI Product Needs Evals](https://hamel.dev/blog/posts/evals/index.html)  
  - [Creating a LLM-as-a-Judge That Drives Business Results](https://hamel.dev/blog/posts/llm-judge/)  
  - [Who Validates the Validators? Aligning LLM-Assisted Evaluation of LLM Outputs with Human Preferences](https://arxiv.org/abs/2404.12272)  
  - [What We’ve Learned From A Year of Building with LLMs](https://applied-llms.org/)  
  - [What AI engineers can learn from qualitative research methods in HCI](https://ianarawjo.medium.com/what-ai-engineers-can-learn-from-qualitative-research-methods-in-hci-5b29b9b7465a)

---

<div class="post-metadata">

**Author:** ![anjor](https://yyz1.discourse-cdn.com/palantir/user_avatar/community.palantir.com/anjor/32/391_2.png) [@anjor](https://community.palantir.com/u/anjor)\
**Post date:** [March 13, 2025, 10:55am UTC](https://community.palantir.com/t/guide-writing-effective-evals/2856/2 "2025-03-13T10:55:05Z")

</div>

This is great, thank you so much for writing it up!

Is there any way to have evals on datasets as opposed to ontology? The use case I have in mind is data extraction from mediasets using LLMs. It’s weird to add an object type for the raw mediaset just for the evals.

---

<div class="post-metadata">

**Author:** ![colton](https://avatars.discourse-cdn.com/v4/letter/c/e5b9ba/32.png) [@colton](https://community.palantir.com/u/colton)\
**Post date:** [March 13, 2025, 5:50pm UTC](https://community.palantir.com/t/guide-writing-effective-evals/2856/3 "2025-03-13T17:50:36Z")

</div>

At the moment, the best way to do this is the way you identified — by building that dataset into the Ontology, you can pull it into AIP Evals via an Object set-backed evaluation suite. That being said, we’d be curious to know more about your use case to inform our product development!

---

<div class="post-metadata">

**Author:** ![system](https://yyz1.discourse-cdn.com/palantir/user_avatar/community.palantir.com/system/32/3_2.png) [@system](https://community.palantir.com/u/system)\
**Post date:** [May 12, 2025, 5:51pm UTC](https://community.palantir.com/t/guide-writing-effective-evals/2856/4 "2025-05-12T17:51:31Z")

</div>

This topic was automatically closed 60 days after the last reply. New replies are no longer allowed.