Open WebUI Pipelines における Valves の仕組みをわかりやすく解説

Web UI から処理パイプラインの設定を動的に管理・操作できる Open WebUI Pipelines の中でも、Valves は非常に重要な機構です。本記事では、Valves の基本概念から活用シーン、実装サンプルまでを、できるだけ明快に整理してご紹介します。

---

1. Valves とは？

1.1 役割の概要

• Valves は、Filter や Pipe における管理者向けの設定スイッチ。
• UI 上で「どのように処理を流すか」を柔軟に変えられる制御ポイントです。
• UserValves は、エンドユーザーがチャットや対話中に操作できる設定項目となります。

この仕組みにより「コードを変更せずに動作をカスタマイズ可能」な柔軟性が得られます。

---

2. なぜ Valves が有効か？

• 動的な制御
  管理者／ユーザーが UI 経由で調整可能なため、処理の柔軟性が向上します。

• コードの安全性維持
  本番環境での設定変更もコード修正無しで完了。CI/CD サイクルを変えずに動作調整できます。

• 可視性・管理性の向上
  GUI によって設定項目が明確かつ直感的に表示されるため、運用負荷が軽減されます。

---

3. Valves の基本構造と使い方

3.1 定義パターン（コード例）

from pydantic import BaseModel, Field
from typing import Literal

class MyFilter:
    class Valves(BaseModel):
        threshold: int = Field(default=10, description="閾値設定")
        mode: Literal["fast", "safe"] = Field(default="fast", description="動作モード")
        priority: int = Field(default=0, description="実行優先度")

    class UserValves(BaseModel):
        enable_feature: bool = Field(default=False, description="機能のオン/オフ")

    def __init__(self):
        # 定義された Valve の初期値がここに入る
        self.valves = self.Valves()
        self.user_valves = self.UserValves()

• Valves：管理者が UI から調整できる設定
• UserValves：実行時にエンドユーザーがオン／オフなど変更できる設定

3.2 実行例（実際の処理フロー内での使用）

def inlet(self, body: dict, __user__: dict):
    if self.user_valves.enable_feature:
        # ユーザーがオンにした機能を有効化
        ...
    # threshold に応じて処理分岐
    if some_value > self.valves.threshold:
        ...

このように、処理内部で Valve に基づいた分岐や動作変更が可能となります。

---

4. 実践的な活用例：OpenAI API モデルリストを動的に取得

from pydantic import BaseModel, Field
import requests

class OpenAIPipe:
    class Valves(BaseModel):
        NAME_PREFIX: str = Field(default="OPENAI/", description="モデル一覧の接頭辞")
        OPENAI_API_BASE_URL: str = Field(default="https://api.openai.com/v1", description="API エンドポイント")
        OPENAI_API_KEY: str = Field(default="", description="認証用 API キー")

    def __init__(self):
        self.valves = self.Valves()

    def pipes(self):
        if not self.valves.OPENAI_API_KEY:
            return []
        headers = {"Authorization": f"Bearer {self.valves.OPENAI_API_KEY}"}
        r = requests.get(f"{self.valves.OPENAI_API_BASE_URL}/models", headers=headers)
        models = r.json().get("data", [])
        return [
            {"id": m["id"], "name": f"{self.valves.NAME_PREFIX}{m['id']}"}
            for m in models if "gpt" in m["id"]
        ]

• 管理者が UI 上で OPENAI_API_KEY や NAME_PREFIX を設定すると、パイプが動的に応答。
• API Key 更新やエンドポイント変更もコード修正不要で反映できます。

---

5. まとめ（TIQ 表）

項目	説明
Valves	管理者向け設定。UI から操作でき、処理パラメータを動的に変更可能。
UserValves	ユーザー向け設定。対話中にユーザーがオン／オフなど切り替えできる項目。
コード変更不要	設定変更が GUI 操作のみで完結、自動化や CI に影響なし。
実用性	モデル切替や閾値調整、API 設定などに柔軟に対応可能。

---

6. 最後に

Open WebUI Pipelines の Valves 機構によって、エンジニアはシステムの柔軟な制御と運用効率を両立できます。コードの変更なく振る舞いを変えられる、というUIとコードの橋渡し役として非常に有用です。