238 lines
6.6 KiB
Markdown
238 lines
6.6 KiB
Markdown
# 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 `/settings` with 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/transformers` is installed
|
|
- [ ] Preset buttons for common providers (OpenAI, Ollama, Azure OpenAI)
|
|
|
|
---
|
|
|
|
## Provider Presets
|
|
|
|
```typescript
|
|
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
|
|
|
|
```svelte
|
|
<!-- 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.svelte`
|
|
- `src/routes/api/v1/settings/embedding/test/+server.ts`
|
|
|
|
## Files to Modify
|
|
|
|
- `src/routes/api/v1/settings/embedding/+server.ts` — already defined in TRUEREF-0007
|