Langfuse Integration with MariaDB Vector Store Documentation

Overview

This document describes a Python script (main.py) that integrates Langfuse for tracing with a MariaDB vector store using LangChain and Sentence Transformers. The script demonstrates how to:

• Initialize a Sentence Transformer model for embeddings.
• Set up Langfuse for tracing application logic.
• Configure a MariaDB vector store.
• Add documents to the vector store and perform a similarity search.
• Log results to Langfuse for observability.

Architecture Flow

Prerequisites

To run the script, ensure the following are installed and configured:

• Python 3.8+
• Dependencies:
  • langfuse
  • langchain-mariadb
  • langchain-community
  • sentence-transformers
  • python-dotenv
• MariaDB: A running MariaDB instance with a database named langchain.
• Environment Variables:
  • Create a .env file in the project root with the following:

    LANGFUSE_PUBLIC_KEY=<your-langfuse-public-key>
    LANGFUSE_SECRET_KEY=<your-langfuse-secret-key>
    MARIADB_USER=<your-mariadb-username>
    MARIADB_PASSWORD=<your-mariadb-password>
• Langfuse Account: Sign up at Langfuse to obtain LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY.

Installation

1. Clone the repository or copy the script to your local environment.

2. Install the required Python packages:

   pip install langfuse langchain-mariadb langchain-community sentence-transformers python-dotenv

3. Set up the .env file with your credentials.

4. Ensure MariaDB is running and accessible at localhost with the database langchain created.

Code Structure

The script (main.py) is structured as follows:

import os
from langfuse import get_client
from langchain_mariadb import MariaDBStore
from sentence_transformers import SentenceTransformer
from langchain_core.documents import Document
from langchain_community.embeddings import HuggingFaceEmbeddings
from dotenv import load_dotenv

load_dotenv()

model = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")

os.environ["LANGFUSE_PUBLIC_KEY"] = os.getenv("LANGFUSE_PUBLIC_KEY")
os.environ["LANGFUSE_SECRET_KEY"] = os.getenv("LANGFUSE_SECRET_KEY")
os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com"
 
langfuse = get_client()
 
if langfuse.auth_check():
    print("Langfuse client is authenticated and ready!")
else:
    print("Authentication failed. Check your credentials.")

url = f"mariadb+mariadbconnector://{os.getenv('MARIADB_USER')}:{os.getenv('MARIADB_PASSWORD')}@localhost/langchain"
vectorstore = MariaDBStore(
    embeddings=model,
    embedding_length=384,
    datasource=url,
    collection_name="my_docs",
)

with langfuse.start_as_current_span(name="mariadb-trace") as span:
    vectorstore.add_documents(
        [
            Document(page_content="The sun is a star."),
            Document(page_content="The moon is a natural satellite.")
        ]
    )
    results = vectorstore.similarity_search("Tell me about celestial bodies.")
    span.update_trace(
        metadata={"query": "Tell me about celestial bodies."}
    )
    print(f"Search results: {results}")

langfuse.flush()

Usage

1. Ensure MariaDB is running and the langchain database exists.

2. Populate the .env file with your Langfuse and MariaDB credentials.

3. Run the script:

   python main.py

4. Expected output:

   • Confirmation of Langfuse authentication.
   • Search results from the MariaDB vector store, e.g.:

     Langfuse client is authenticated and ready!
     Search results: [Document(page_content='The sun is a star.'), Document(page_content='The moon is a natural satellite.')]

5. Check the Langfuse dashboard (https://cloud.langfuse.com) for trace details under the mariadb-trace span.

Notes

• Embedding Model: The all-MiniLM-L6-v2 model is used for its balance of performance and efficiency. Other models can be used by changing the model_name parameter, but ensure the embedding_length matches the model’s output dimension.
• MariaDB: Ensure the database user has appropriate permissions to create and modify tables in the langchain database.
• Langfuse: Traces are logged to the Langfuse cloud instance. Ensure your credentials are valid to avoid authentication errors.
• Error Handling: The script includes basic authentication checks for Langfuse. Additional error handling (e.g., for MariaDB connection failures) can be added as needed.

Troubleshooting

• Langfuse Authentication Failure:
  • Verify LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY in the .env file.
  • Ensure the Langfuse host URL is correct.
• MariaDB Connection Issues:
  • Check that MariaDB is running and accessible at localhost.
  • Confirm the MARIADB_USER and MARIADB_PASSWORD are correct.
  • Ensure the langchain database exists.
• No Search Results:
  • Verify that documents were added successfully to the vector store.
  • Ensure the query is relevant to the stored documents.