Langfuseのプロンプト管理機能の紹介と、私が気になった点をまとめてみました。誰かの参考になれば幸いです🙇♂️
Langfuseのプロンプト管理機能
Langfuseにはプロンプト管理機能があり、LLMの呼び出しに利用するプロンプトをLangfuse上で管理することができます。Langfuse上で管理できて嬉しい点としては以下があげられます。
- アプリケーションをデプロイすることなく、プロンプトを変更可能
- Score Systemやメトリクスを利用したプロンプトの効果測定が可能
- Playgroundを利用したプロンプトのバージョン間の差異確認が容易
などなど
プロンプトの作成
プロンプトの作成方法は簡単で、Langfuseの[Prompts]から[New prompt]でプロンプトの作成ができます。
試しにこんな感じで、プロンプトを作成してみましょう。
- Name: what_is_this
- Prompt What is {{this}} ?
{{}}で文字列を囲うと、変数として認識されます。今回は{{this}}と記載したので、thisという変数が利用可能なプロンプトになります。他にも、@@@langfusePrompt:name=<Name>|label=latest@@@表記で、Langfuse上で管理している他のプロンプトを参照することも可能です。この機能は画像上の[Add prompt reference]からも利用できます。
プロンプトを作成すると、下記のような画面に遷移します。#1はバージョンを表していて、ProductionラベルとLatestラベルが自動で付与されます。
プロンプトの利用方法
プロンプトの利用は簡単で、get_promptメソッドに作成したプロンプトの名前を渡すだけです。
langfuse = get_client()
prompt = langfuse.get_prompt("what_is_this")
compileメソッドでthis変数の中身を渡し、文字列への変換もできます。
print(prompt.compile(this="foo"))
# What is foo?
また、LangChainのプロンプトにも変換できます。
from langchain_core.prompts import PromptTemplate
prompt_template = PromptTemplate.from_template(
prompt.get_langchain_prompt(),
metadata={"langfuse_prompt": prompt},
)
利用の全体像はこんな感じです。
from langfuse import get_client
from langfuse.langchain import CallbackHandler
from langchain_core.prompts import PromptTemplate
from langchain_openai import ChatOpenAI
langfuse = get_client()
langfuse_handler = CallbackHandler()
prompt = langfuse.get_prompt("what_is_this")
prompt_template = PromptTemplate.from_template(
prompt.get_langchain_prompt(),
metadata={"langfuse_prompt": prompt},
)
llm = ChatOpenAI(model="gpt-5-mini-2025-08-07")
completion_chain = prompt_template | llm
res = completion_chain.invoke({"this": "アドベントカレンダー"},config={"callbacks": [langfuse_handler]})
print(res.content)
という機能なのですが、いくつか気になる点があります。
気になった点
metadataとかcallbacksって必要？
どちらもプロンプトを取得するだけであれば不要です。
設定しておくと下記のようなことができます。
- metadataの設定：プロンプトをトレースに紐づける
- callbacksの設定：Langfuseにトレースを連携する
Langfuseで管理するプロンプトをトレースに紐づけるとさまざまな情報が確認できます。
例えば、下記のようにプロンプトで生成されたトレース（正確にはGenerataion）へのリンクがUI上で生成されます。
他にも紐ついたトレースをもとに、トークン数やコストの統計も確認できます。
なので、特段理由がない限りはプロンプトとトレースを紐づけておくと何かと便利です。
callbacksに関しては、Langfuseにトレースのデータを送信するための設定で、これがないとLangfuseにトレースが連携されません。
プロンプトのラベルって何に使うの？
取得するプロンプトのバージョンを選択する際に利用します。
例えば、Langfuse上で先ほどのプロンプトに「一言で教えて」という文字列を追加し更新します。するとバージョン2が作成され、下記のようにラベルが振られます。
ただし、下記のような設定でプロンプトを取得していると、バージョン#2のプロンプトを取得できません。
prompt = langfuse.get_prompt("what_is_this")
プロンプトの取得に利用するget_promptメソッドでは、オプションとしてlabelを指定できます。
このラベルですが、何も指定しないとProductionラベルを持つプロンプトを取得する仕様です。そのため、バージョン#2があったとしてもProductionラベルが付与されたバージョン#1のプロンプトを引き続き取得してしまいます。
ラベルの移動は下記のボタンから行えます。
Promote to productionを選択するとことで、Productionラベルをバージョン#2のプロンプトに付与でき、get_promptメソッドでも取得できます。
また、カスタムラベルも作成できるので、Stageラベルなどの環境ごとのラベルを作成しても便利かもしれません。
prompt = langfuse.get_prompt("what_is_this",label="Stage")
毎回プロンプトを取得するの？Langfuseが落ちたらプロンプトが取得できない？
キャッシュが利用できるので、キャッシュが有効であればLangfuseが落ちても大丈夫。
get_promptメソッドの引数にcache_ttl_secondsがあり、設定をしておくと、有効時間内であればキャッシュからプロンプトを取得します。当然ではありますが、キャッシュから取得する際には、Langfuseにプロンプト取得のリクエストは投げません。
ただし、キャッシュを設定したとしても有効期限が切れていたり、初回リクエストの際には、Langfuseへのリクエストが必要になります。その時にLangfuseが落ちていると、プロンプトが取得できません。
そのようなケースにも対応するのであれば、get_promptメソッドにfallbackを設定したりする対策が考えられます。公式ドキュメントにも記載があるので、見てみると良いかもです！