6.6 KiB
6.6 KiB
TRUEREF-0018 — Embedding Provider Configuration UI
Priority: P2 Status: Pending Depends On: TRUEREF-0007, TRUEREF-0015 Blocks: —
Overview
A settings page within the web UI that allows users to configure the embedding provider without editing environment variables or config files. Supports switching between "None" (FTS5-only), OpenAI-compatible API, and local model (if available). Includes a live connectivity test before saving.
Acceptance Criteria
- Settings page at
/settingswith embedding provider section - Provider selector: None / OpenAI-compatible / Local model
- OpenAI provider form: base URL, API key (masked), model name, dimensions
- "Test Connection" button that validates the API key and model before saving
- Success/error feedback from connection test
- Save configuration (calls
PUT /api/v1/settings/embedding) - Current configuration loaded from
GET /api/v1/settings/embedding - Warning shown when "None" is selected (search will be FTS5-only, lower quality)
- Local model option shows whether
@xenova/transformersis installed - Preset buttons for common providers (OpenAI, Ollama, Azure OpenAI)
Provider Presets
const PROVIDER_PRESETS = [
{
name: 'OpenAI',
baseUrl: 'https://api.openai.com/v1',
model: 'text-embedding-3-small',
dimensions: 1536
},
{
name: 'Ollama (local)',
baseUrl: 'http://localhost:11434/v1',
model: 'nomic-embed-text',
dimensions: 768
},
{
name: 'Azure OpenAI',
baseUrl: 'https://{resource}.openai.azure.com/openai/deployments/{deployment}/v1',
model: 'text-embedding-3-small',
dimensions: 1536
}
];
Settings Page Component
<!-- src/routes/settings/+page.svelte -->
<script lang="ts">
let provider = $state<'none' | 'openai' | 'local'>('none');
let baseUrl = $state('https://api.openai.com/v1');
let apiKey = $state('');
let model = $state('text-embedding-3-small');
let dimensions = $state<number | undefined>(1536);
let testStatus = $state<'idle' | 'testing' | 'ok' | 'error'>('idle');
let testError = $state<string | null>(null);
let saving = $state(false);
async function testConnection() {
testStatus = 'testing';
testError = null;
try {
const res = await fetch('/api/v1/settings/embedding/test', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ provider, openai: { baseUrl, apiKey, model, dimensions } })
});
if (res.ok) {
testStatus = 'ok';
} else {
const data = await res.json();
testStatus = 'error';
testError = data.error;
}
} catch (e) {
testStatus = 'error';
testError = (e as Error).message;
}
}
async function save() {
saving = true;
await fetch('/api/v1/settings/embedding', {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ provider, openai: { baseUrl, apiKey, model, dimensions } })
});
saving = false;
}
</script>
<div class="mx-auto max-w-2xl py-8">
<h1 class="mb-6 text-2xl font-bold text-gray-900">Settings</h1>
<section class="rounded-xl border border-gray-200 bg-white p-6">
<h2 class="mb-1 text-lg font-semibold">Embedding Provider</h2>
<p class="mb-4 text-sm text-gray-500">
Embeddings enable semantic search. Without them, only keyword search (FTS5) is used.
</p>
<div class="mb-4 flex gap-2">
{#each ['none', 'openai', 'local'] as p}
<button
onclick={() => (provider = p)}
class="rounded-lg px-4 py-2 text-sm {provider === p
? 'bg-blue-600 text-white'
: 'border border-gray-200 text-gray-700 hover:bg-gray-50'}"
>
{p === 'none' ? 'None (FTS5 only)' : p === 'openai' ? 'OpenAI-compatible' : 'Local Model'}
</button>
{/each}
</div>
{#if provider === 'none'}
<div class="rounded-lg border border-amber-200 bg-amber-50 p-3 text-sm text-amber-700">
Search will use keyword matching only. Results may be less relevant for complex questions.
</div>
{/if}
{#if provider === 'openai'}
<div class="space-y-3">
<!-- Preset buttons -->
<div class="flex flex-wrap gap-2">
{#each PROVIDER_PRESETS as preset}
<button
onclick={() => {
baseUrl = preset.baseUrl;
model = preset.model;
dimensions = preset.dimensions;
}}
class="rounded border border-gray-200 px-2.5 py-1 text-xs text-gray-600 hover:bg-gray-50"
>
{preset.name}
</button>
{/each}
</div>
<label class="block">
<span class="text-sm font-medium">Base URL</span>
<input
type="text"
bind:value={baseUrl}
class="mt-1 w-full rounded-lg border px-3 py-2 text-sm"
/>
</label>
<label class="block">
<span class="text-sm font-medium">API Key</span>
<input
type="password"
bind:value={apiKey}
class="mt-1 w-full rounded-lg border px-3 py-2 text-sm"
placeholder="sk-..."
/>
</label>
<label class="block">
<span class="text-sm font-medium">Model</span>
<input
type="text"
bind:value={model}
class="mt-1 w-full rounded-lg border px-3 py-2 text-sm"
/>
</label>
<label class="block">
<span class="text-sm font-medium">Dimensions (optional override)</span>
<input
type="number"
bind:value={dimensions}
class="mt-1 w-full rounded-lg border px-3 py-2 text-sm"
/>
</label>
<div class="flex items-center gap-3">
<button
onclick={testConnection}
class="rounded-lg border border-gray-300 px-3 py-1.5 text-sm"
>
{testStatus === 'testing' ? 'Testing...' : 'Test Connection'}
</button>
{#if testStatus === 'ok'}
<span class="text-sm text-green-600">✓ Connection successful</span>
{:else if testStatus === 'error'}
<span class="text-sm text-red-600">✗ {testError}</span>
{/if}
</div>
</div>
{/if}
<div class="mt-6 flex justify-end">
<button
onclick={save}
disabled={saving}
class="rounded-lg bg-blue-600 px-4 py-2 text-sm text-white disabled:opacity-50"
>
{saving ? 'Saving...' : 'Save Settings'}
</button>
</div>
</section>
</div>
Test Connection Endpoint
POST /api/v1/settings/embedding/test
Request body: same as PUT /api/v1/settings/embedding
Action: create a provider instance, call embed(['test']), return success/failure
Response 200: { "ok": true, "dimensions": 1536 }
Response 400: { "error": "API key is invalid" }
Files to Create
src/routes/settings/+page.sveltesrc/routes/api/v1/settings/embedding/test/+server.ts
Files to Modify
src/routes/api/v1/settings/embedding/+server.ts— already defined in TRUEREF-0007