Sarashina API UX/UI 設計・実装ガイド

Sarashina API の概要と設計思想

Sarashina API は、SB Intuitions が開発した国産大規模言語モデル「Sarashina」を、HTTP API 経由で利用できるサービスです。日本語の文脈理解・文化的ニュアンス・敬語表現に強みを持ち、国内データセンターでの運用によりデータ主権（ソブリン性）を確保しています。

設計上の核心: Sarashina は「日本語らしさ」を体現するモデルです。UX/UI も単なる機能の羅列ではなく、日本語の豊かさ（婉曲表現、省略、文脈推論）をユーザー体験として昇華させる設計が求められます。

提供モデルと用途マトリクス

モデルID	コンテキスト	主な用途	APIカテゴリ
`sarashina3-mini`	128k tokens	標準対話、Tool-calling、数学・コーディング	Chat Completions
`sarashina3-nano`	128k tokens	高速バッチ処理（抽出・要約・分類）	Chat Completions
`sarashina3-guard`	64k tokens	入出力の安全性判定・モデレーション	Chat Completions
`sarashina3-embedding`	8,000 tokens	テキストベクトル化、RAG候補抽出	Embeddings
`sarashina3-rerank`	8,000 tokens	クエリと文書の関連度スコアリング	Rerank
`sarashina3-translate`	5,000文字	日英・英日訳（文脈・トーン考慮）	Translate

UX/UI 設計の基本原則

1. 日本語の「間」を尊重する

日本語は省略や婉曲を前提とします。UI上では「完全な文を強制する」より、「意図を補完する補助」を提供します。例：箇条書き入力を受け付け、AIが文脈を補って生成する。

2. 敬語レベルの可視化

ビジネス用途では、敬語の度合いをユーザーが選択・確認できるUIが重要です。丁寧語・謙譲語・尊敬語のトーンをプレビューし、修正できるフローを設けます。

3. 遅延の設計

LLMの応答には時間がかかります。スケルトン画面、ストリーミング表示、進行状況の可視化により、ユーザーの不安を軽減します。特に日本語の長文生成では待機体験が重要です。

4. 安全性の透明性

Guardモデルによる判定結果を、過剰に威圧的にならず、かつ明確に伝えます。「生成できません」ではなく、「表現を調整して再作成しますか？」といった前向きな回復設計を採用します。

エンドポイント別 UI パターン

Chat Completions（対話・生成）

対話モデル sarashina3-mini と軽量モデル sarashina3-nano は、最も汎用的に使われるエンドポイントです。

推奨 UI パターン

チャットインターフェース

吹き出し形式のメッセージ表示
ストリーミング応答の文字ごと表示
再生成・コピー・評価（👍/👎）ボタン
会話履歴のセッション管理

テンプレート駆動生成

「議事録」「報告書」「メール」など業務テンプレート選択
入力項目をフォーム化し、AIが体裁を整える
生成後のワンクリック編集モード

CONCEPT

// チャットUI の状態設計（React想定）
interface ChatMessage {
  role: "user" | "assistant" | "system";
  content: string;
  status: "sending" | "streaming" | "done" | "error";
  guardResult?: GuardDecision; // guardモデルの判定結果
}

// 送信フロー
async function sendMessage(text: string) {
  // 1. ユーザーメッセージを即座に表示（楽観的UI）
  appendMessage({ role: "user", content: text, status: "done" });

  // 2. ストリーミング応答を受信しながら表示更新
  const stream = await fetchChatStream({
    model: "sarashina3-mini",
    messages: buildHistory(),
    stream: true,
  });

  // 3. chunkごとに assistant メッセージを更新
  for await (const chunk of stream) {
    appendContent(chunk.content);
  }
}

Embeddings（埋め込み・検索）

sarashina3-embedding は、文書やFAQをベクトル化し、意味的類似度で検索するRAGシステムの核となります。

推奨 UI パターン

セマンティック検索

キーワードでは捉えにくい「意味的な近さ」で文書を探せる検索窓。類似度スコアを薄いバーで視覚化します。

文書アップロード＋問い合わせ

PDFやテキストをアップロード後、内容について質問できる「文書チャット」UI。引用元ページを明記します。

クラスタリング可視化

大量の文書を埋め込み空間上でグループ化し、トピックごとに色分け表示。探索的な情報発見を支援します。

CONCEPT

// RAG検索フロー
async function semanticSearch(query: string) {
  // 1. クエリをベクトル化
  const queryVec = await embedText(query, "sarashina3-embedding");

  // 2. ベクトルDBで近傍検索（例：pgvector, Milvus, Pinecone）
  const candidates = await vectorSearch(queryVec, { topK: 20 });

  // 3. UIに「関連度スコア」付きで一覧表示
  return candidates.map(c => ({
    title: c.title,
    excerpt: c.text.slice(0, 120) + "…",
    scoreBar: Math.round(c.similarity * 100), // %表示
    source: c.meta.source,
  }));
}

Rerank（リランキング）

sarashina3-rerank は、検索で得た候補文書をクエリとの関連度で再並び替えします。RAGの精度向上に必須の後段処理です。

推奨 UI パターン

検索結果の再構成

初回検索結果の上部に「関連度で並び替えました」という補足表示
各結果に「関連度」バッジ（高・中・低）を付与
上位3件を「おすすめ」として強調表示

フィードバックループ

「この結果は役に立ちましたか？」の評価を収集
評価データをrerank指示のチューニングに活用
ユーザーの業種・部門ごとに最適化された並び順を学習

Translate（翻訳）

sarashina3-translate は、文脈やトーンを汲んだ自然な日英・英日翻訳を提供します。単なる単語変換ではなく、ビジネスメールや技術文書のニュアンスを保持します。

推奨 UI パターン

並列対訳エディタ

左側に原文、右側に訳文をリアルタイム表示
段落単位でハイライト同期（ホバーで対応箇所を強調）
「ビジネス」「カジュアル」「技術」などトーン選択プルダウン

バッチ翻訳

CSV/Excelアップロード後、列単位で一括翻訳
進捗バーと残り時間推定を表示
翻訳結果の差分（原文との対比）をハイライト

Guard（安全性判定）

sarashina3-guard は、T1〜T12 カテゴリで入出力テキストの安全性を判定します。UI上では「ブロック」ではなく「ガイド」として機能させるのが重要です。

推奨 UI パターン

穏やかな警告

赤色の強い警告ではなく、落ち着いたトーンで理由を説明
「別の表現を試す」ボタンを即座に提供
カテゴリ別アイコンで直感的にリスクを伝達

運用ダッシュボード

管理者向けにカテゴリ別検出数の時系列グラフを提供
ユーザー単位・部門単位の傾向分析
誤検出のフィードバック送信機能

入出力の自動チェック

送信前に入力を判定し、問題があれば送信前に確認を促す
応答後に出力を判定し、結果を控えめに提示する
自動チェックは任意（既定オフ）。API 呼び出しと待ち時間が増える点を明示する

実装アーキテクチャ

推奨構成（Next.js + API Routes 例）

主要コンポーネントの責務

層	責務	Sarashina API 利用例
Presentation	ストリーミング表示、入力補助、状態可視化	チャットUI、翻訳エディタ、検索結果一覧
API Gateway	認証、レート制限、リトライ、ログ	API Key のサーバ側管理、Guard判定の前後処理
Application	ユースケース調整、プロンプト構築、RAGパイプライン	Embed → VectorSearch → Rerank → Chat の連携
Infrastructure	ベクトルDB、キャッシュ、ストレージ	Embedding の永続化、文書の前処理・チャンキング

フロントエンド実装の詳細手法

ストリーミング応答の UI 実装

Sarashina3-mini のチャット応答はストリーミングを前提とした設計が推奨されます。文字が逐次表示されることで「思考中」ではなく「話している」感覚を演出できます。

React

function ChatStream() {
  const [messages, setMessages] = useState<ChatMessage[]>([]);
  const [input, setInput] = useState("");

  const handleSend = async () => {
    const userMsg: ChatMessage = { role: "user", content: input, status: "done" };
    setMessages(prev => [...prev, userMsg]);

    const assistantMsg: ChatMessage = { role: "assistant", content: "", status: "streaming" };
    setMessages(prev => [...prev, assistantMsg]);

    const res = await fetch("/api/chat", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ message: input, history: messages }),
    });

    const reader = res.body?.getReader();
    const decoder = new TextDecoder();
    let buffer = "";

    while (reader) {
      const { done, value } = await reader.read();
      if (done) break;
      buffer += decoder.decode(value, { stream: true });
      // SSE形式のchunkをパースしてUI更新
      updateLastMessage(buffer);
    }
  };

  return (
    <div className="chat-container">
      {messages.map((m, i) => (
        <Bubble key={i} role={m.role} status={m.status}>
          {m.content}
          {m.status === "streaming" && <Cursor />}
        </Bubble>
      ))}
    </div>
  );
}

生成の中断（停止ボタン）

ストリーミング中は常に「停止」を提供します。長い生成や誤った入力を途中で止められることは、待機の不安を減らし、無駄なトークン消費も防ぎます。

AbortController を作り、fetch と読み取りループの両方に signal を渡す
中断はエラー扱いにせず、そこまでの出力を残して静かに終了する（空なら「停止しました」と明示）
チャット・翻訳・RAG で一貫した停止体験を提供する

RAG パイプラインの UI 統合

Embeddings + Rerank + Chat Completions を組み合わせた RAG は、現在最も実用的な企業導入パターンです。UI上では「根拠の提示」が信頼性を左右します。

TypeScript

interface RAGResponse {
  answer: string;
  sources: {
    title: string;
    excerpt: string;
    page?: number;
    relevance: number; // rerankスコア
  }[];
}

// UI上で回答と引用をセットで表示
function RAGAnswer({ data }: { data: RAGResponse }) {
  return (
    <div className="rag-answer">
      <article className="prose">{data.answer}</article>
      <aside className="sources">
        <h5>引用元</h5>
        <ol>
          {data.sources.map((s, i) => (
            <li key={i}>
              <span className="source-title">{s.title}</span>
              <span className="source-excerpt">{s.excerpt}</span>
              <RelevanceBar score={s.relevance} />
            </li>
          ))}
        </ol>
      </aside>
    </div>
  );
}

翻訳 UI のトーン制御

Translate API は文脈を汲むため、ユーザーに「トーン」を選択させることで品質を向上させられます。

TypeScript

type Tone = "business-formal" | "business-casual" | "technical" | "marketing";

async function translate(text: string, tone: Tone, direction: "ja-en" | "en-ja") {
  const res = await fetch("/api/translate", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "sarashina3-translate",
      text,
      tone,
      direction,
    }),
  });
  return res.json();
}

// UI側ではセグメンテッドコントロールでトーンを選択
// [ ビジネス正式 | ビジネスカジュアル | 技術 | マーケティング ]

セキュリティ・プライバシー・運用設計

API Key の管理

API Key はブラウザに露出させず、必ずサーバサイド（API Route / BFF）で管理します。Vercel の Environment Variables や AWS Secrets Manager などを利用し、クライアントからは間接的にのみアクセスさせます。

Guard の多層防御

入力時と出力時の両方で Guard を適用します。入力Guardで不適切なプロンプトを事前に防ぎ、出力Guardで生成物の安全性を最終確認します。UI上では「修正提案」として回復フローを設計します。

ログと監査

法人利用では、誰がいつどのモデルを使用したかの監査ログが必要です。ユーザーID、セッションID、モデルID、トークン数、応答時間を構造化ログとして蓄積し、ダッシュボードで可視化します。

データ主権の設計

Sarashina は国内データセンターで運用されます。機密文書を Embedding する際は、ベクトルDBも国内リージョンに配置し、クロスボーダー通信を排除したアーキテクチャを文書化します。

レート制限とフォールバック

状況	UI挙動	技術的対応
429 Too Many Requests	「混雑しています。自動的に再試行します」	Exponential Backoff + Queue
タイムアウト	「応答に時間がかかっています。短くまとめて再送信」	max_tokens縮小、要約モード自動切替
Guardブロック	「別の表現を試してください」+ 例示	Guard結果に基づく再プロンプト生成
長文生成	進捗パーセント + 生成セクション別表示	Chunked generation + SSE

デザインシステムとコンポーネント

Sarashina API を利用するアプリケーションに共通して求められる UI コンポーネント群を定義します。これらは業種を問わず再利用可能なパターンです。

共通コンポーネント一覧

SmartInput

プレースホルダーが入力例を循環表示。箇条書き入力を自動で整形。文字数カウントとトークン予測を併記。

StreamingBubble

吹き出し内で文字が逐次出現。コードブロックはシンタックスハイライト。生成中は脈動アニメーション。生成中は「停止」ボタンで中断できる。

SourceCitation

引用元文書のタイトル、該当箇所、関連度バーをセットで表示。クリックで原文へスクロール。

ToneSelector

翻訳・生成のトーンをアイコン付きセグメントで選択。ホバーで各トーンの説明ツールチップ。

GuardNotice

穏やかな色調で理由を説明。修正提案（別の表現・再判定・このまま送信）ボタンを用意し、過剰な警告色を避ける。入出力の自動チェックにも対応。

TokenEstimator

入力テキストに対するトークン数と料金のリアルタイム推定。予算上限に近づくと穏やかに警告。

推奨デザイントークン（白×ミント / ブルータリスト）

トークン	値	用途
`color.bg`	`#ffffff`	ページ背景（白）
`color.fg`	`#0b0b0b`	主要テキスト・罫線（墨）
`color.accent`	`#00e5a8`	プライマリアクション、強調（ミント）
`color.muted`	`#f2f2f2`	下地、ホバー、見出し背景
`color.ink-soft`	`#555555`	補足テキスト、ラベル
`font.ui`	Inter / Noto Sans JP	本文、UIラベル（可読性）
`font.mono`	Roboto Mono	コード、ラベル、数値
`radius.card`	`4px`	角丸（ほぼ直角）
`border.width`	`3–4px`	枠線（太い実線で区切る）

導入ワークフロー

要件定義とモデル選定

対話中心なら mini、大量バッチなら nano、RAGなら embedding + rerank の組み合わせを選定。Guard が必要な公開サービスか、社内閉域かを判断します。

プロトタイプ（Playground → UI）

Sarashina サービスの Playground でプロンプトを検証し、期待する出力トーン・長さ・構造を確定させてから UI に落とし込みます。

コンポーネント実装

SmartInput、StreamingBubble、SourceCitation など共通コンポーネントを先に実装し、各画面で再利用します。Storybook 等で状態パターンを網羅的に確認します。

統合テストと Guard 調整

実際の業務データで Embeddings の精度、Rerank の並び順、Guard の誤検出率を測定。しきい値や指示文をチューニングします。

本番運用と継続的改善

ユーザー評価（👍/👎）と Guard ログを収集し、プロンプトや Rerank 指示を継続的に改善。A/Bテストでモデル切り替えの効果を検証します。

まとめ

Sarashina API を活用した UX/UI 設計の本質は、「日本語の豊かさを技術で支える」ことにあります。単なる機能実装ではなく、日本語特有の婉曲表現・敬語・文脈推論を、ユーザーが自然に使いこなせるインターフェースに翻訳することが求められます。

各エンドポイントの特性を理解し、Chat Completions ではストリーミングとトーン制御を、Embeddings/Rerank では根拠の可視化を、Translate では文脈を汲んだ対訳エディタを、Guard では穏やかな回復体験を設計することで、国産LLMならではの信頼性と使いやすさを両立できます。

次のステップ: 本ガイドに基づき、まずは Playground でプロンプトを検証し、最小限のチャットUIプロトタイプを構築してください。その後、RAGや翻訳などのユースケースに応じてコンポーネントを拡張していくことを推奨します。