---
title: "🤗 Hugging Face and 🪢 Langfuse: 5 Ways to use them Together"
description: "Hugging Face and Langfuse are popular platforms to develop and run LLM applications. This guide shows you 5 ways how to use both platforms together to simplify open source LLM development."
ogImage: /images/blog/2025-03-13-hugging-face-with-langfuse/hugging-face-with-langfuse.png
tag: guide
date: 2025/03/13
author: "Jannik"

---

Hugging Face and Langfuse are popular platforms to develop and run LLM applications. This guide shows you 5 ways how to use both platforms together to simplify your open source LLM development.

> **What is Hugging Face?** [Hugging Face](https://huggingface.co) is a platform for machine learning and AI. It provides a range of tools and services for developers to build, train, and deploy machine learning and language models.

> **What is Langfuse?** [Langfuse](https://langfuse.com) is an open-source platform for LLM engineering. It provides tracing and monitoring capabilities for AI agents, helping developers debug, analyze, and optimize their products. Langfuse integrates with various tools and frameworks via native integrations, OpenTelemetry, and SDKs.

**This guide shows you how to:**

- Trace Hugging Face models
- Evaluate Hugging Face smolagents
- Use Hugging Face models in the Playground and Evaluators
- Use Hugging Face datasets for Dataset Experiments
- Deploy Langfuse on Hugging Face Spaces

---

## 1) Trace Hugging Face Models with Langfuse

Hugging Face allows you to query a variety of open source and specialized fine tuned models. One of the most common integration patterns is to query a Hugging Face model with Python and automatically trace the model calls via Langfuse. Using the [Langfuse OpenAI integration](/integrations/model-providers/openai-py), you can easily point to any Hugging Face model endpoint. For example calling the `Meta-Llama-3-8B-Instruct` model:

```python
import os
from langfuse.openai import OpenAI
from langfuse import observe

# Set up your environment variables
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."
os.environ["LANGFUSE_BASE_URL"] = "https://cloud.langfuse.com"
os.environ["HUGGINGFACE_ACCESS_TOKEN"] = "hf_..."

# Initialize the OpenAI client pointing to the Hugging Face Inference API
client = OpenAI(
    base_url="https://api-inference.huggingface.co/models/meta-llama/Meta-Llama-3-8B-Instruct/v1/",
    api_key=os.getenv('HUGGINGFACE_ACCESS_TOKEN'),
)

# Optionally, use the @observe() decorator to trace other application logic as well
@observe()
def get_poem():
    completion = client.chat.completions.create(
        model="model-name",  # this can be an arbitrary identifier
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Write a poem about language models"},
        ]
    )
    return completion.choices[0].message.content

print(get_poem())
```

![Hugging Face Model Trace in Langfuse](/images/cookbook/huggingface/huggingface-example-trace.png)

_[Public example trace link](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/0c205096-fbd9-48b9-afa3-5837483488d8?timestamp=2025-01-09T15%3A03%3A08.365Z)_

For more examples, check out the [Langfuse Hugging Face Integration documentation](/integrations/model-providers/huggingface).

---

## 2) Trace Hugging Face Smolagents with Langfuse

For developers using Hugging Face’s minimalistic agent framework—**[smolagents](https://github.com/huggingface/smolagents)**—integrating with Langfuse can help you trace multi-step processes and monitor your agents’ reasoning. Below is a simplified example that shows how to instrument smolagents:

```python
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from openinference.instrumentation.smolagents import SmolagentsInstrumentor

# Initialize the tracer provider and set up the OTLP exporter to send traces to Langfuse
trace_provider = TracerProvider()
trace_provider.add_span_processor(SimpleSpanProcessor(OTLPSpanExporter()))
SmolagentsInstrumentor().instrument(tracer_provider=trace_provider)

# Now, create a smolagent and run it
from smolagents import CodeAgent, ToolCallingAgent, DuckDuckGoSearchTool, HfApiModel

# Initialize the model (you can provide additional parameters as needed)
model = HfApiModel(model_id="deepseek-ai/DeepSeek-R1-Distill-Qwen-32B")

# Create an agent that can perform a web search
search_agent = ToolCallingAgent(
    tools=[DuckDuckGoSearchTool()],
    model=model,
    name="search_agent",
    description="Agent to perform web searches."
)

# Create a manager agent that coordinates the operations
manager_agent = CodeAgent(
    tools=[],
    model=model,
    managed_agents=[search_agent],
)

result = manager_agent.run("How can Langfuse be used to monitor and improve the reasoning of smolagents when executing multi-step tasks?")
print(result)
```

![Hugging Face Smolagent Trace in Langfuse](/images/cookbook/integration-smolagents/smolagent_example_trace.png)

_[Public example trace link](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/ce5160f9bfd5a6cd63b07d2bfcec6f54?timestamp=2025-02-11T09%3A25%3A45.163Z&display=details)_

This integration allows you to see detailed traces for each step your smolagent performs. Learn more about this integration in the [smolagents documentation](https://huggingface.co/docs/smolagents/en/index).

---

## 3) Hugging Face Models in Playground and Evaluators

You can also use Hugging Face models in the [Langfuse Playground](/docs/playground) and for [LLM-as-a-Judge evaluators](/docs/scores/model-based-evals). This lets you test your prompts and use open source models for model-based evaluations.

To add a Hugging Face model in Langfuse, navigate to your project settings. Create a new model connection and select openai as the provider. Replace the API Base URL with the endpoint for the model (e.g. `https://api-inference.huggingface.co/models/meta-llama/Meta-Llama-3-8B-Instruct/v1/`). Add your Hugging Face access token to the API Key field. For the model name, you can use any arbitrary identifier.

![Hugging Face Playground in Langfuse](/images/cookbook/huggingface/add-hugging-face-to-playground.png)

Learn more about how to set up Langfuse’s [LLM-as-a-Judge evaluators](/docs/scores/model-based-evals) and the [Langfuse Playground](/docs/playground).

---

## 4) Hugging Face Datasets for Dataset Experiments

Hugging Face offers a variety of datasets that can be used to evaluate LLMs and AI agents. These datasets can be used to run [Langfuse Dataset Experiments](/docs/datasets/overview).

This example shows how you can bring Hugging Face datasets into your observability pipeline, allowing you to track performance and evaluation scores with Langfuse.

First, we fetch a dataset from Hugging Face. In this case the [GSM8K dataset](https://huggingface.co/datasets/openai/gsm8k) containing math word problems.

```python
import os
import pandas as pd
from datasets import load_dataset
from langfuse import Langfuse

# Load a benchmark dataset (e.g., GSM8K)
dataset = load_dataset("openai/gsm8k", split="train[:10]")  # limit to first 10 for demo
df = pd.DataFrame(dataset)
print("First few rows of the dataset:")
print(df.head())

# Initialize your Langfuse client (ensure you have your API key configured)
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."
os.environ["LANGFUSE_BASE_URL"] = "https://cloud.langfuse.com"
langfuse = Langfuse(api_key=os.getenv("LANGFUSE_SECRET_KEY"))

# Create a new dataset in Langfuse
dataset_name = "GSM8K_Benchmark"
langfuse.create_dataset(
    name=dataset_name,
    description="Benchmark dataset for evaluating LLM performance",
    metadata={"type": "benchmark"}
)

# Upload each dataset item to Langfuse
for i, row in df.iterrows():
    langfuse.create_dataset_item(
        dataset_name=dataset_name,
        input={"question": row["question"]},
        expected_output={"answer": row["answer"]},
        metadata={"index": i}
    )
```

![Hugging Face Dataset in Langfuse](/images/cookbook/huggingface-agent-course/example-dataset.png)

You can then loop over the dataset items to test your application for every dataset input.

```python
dataset = langfuse.get_dataset("<langfuse_dataset_name>")

# Run our agent against each dataset item
for item in dataset.items:
    langfuse_trace, output = run_your_application(item.input["text"])

    # Link the trace to the dataset item for analysis
    item.link(
        langfuse_trace,
        run_name="notebook-run-01",
        run_metadata={ "model": model.model_id }
    )

    # Optionally, store a quick evaluation score for demonstration
    langfuse_trace.score(
        name="<example_eval>",
        value=1,
        comment="This is a comment"
    )
```

You can repeat this process with different:

- Models (OpenAI GPT, local LLM, etc.)
- Tools (search vs. no search)
- Prompts (different system messages)

Then compare them side-by-side in Langfuse:

![Dataset run overview](/images/cookbook/huggingface-agent-course/dataset_runs.png)
![Dataset run comparison](/images/cookbook/huggingface-agent-course/dataset-run-comparison.png)

For more details on how to use Langfuse Dataset Experiments, check out the [docs](/docs/datasets/overview).

---

## 5) Deploy Langfuse on Hugging Face Spaces

Langfuse can also be deployed directly on Hugging Face Spaces—combining the instant accessibility of Spaces with the power of Langfuse observability.

To deploy, simply create a new Hugging Face Space, select Docker as your SDK, and choose Langfuse as the template. You’ll need to set up persistent storage and configure the environment variables for secure operation.

![Hugging Face Spaces Deployment](/images/cookbook/huggingface/huggingface-space-setup.png)

For a step-by-step guide on deploying Langfuse on Spaces, check out the [Hugging Face Langfuse Spaces documentation](https://huggingface.co/docs/hub/en/spaces-sdks-docker-langfuse#what-is-langfuse).

---

### Next Steps

Find out more about all features in the [Langfuse docs](/docs).

(Note: This blog post was also published on Hugging Face ([link](https://huggingface.co/blog/MJannik/hugging-face-and-langfuse)))

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/blog/2025-03-13-use-hugging-face-together-with-langfuse.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.