288 lines
13 KiB
HTML
288 lines
13 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<title>06 Search - Momentry API Docs</title>
|
|
<style>
|
|
* { margin: 0; padding: 0; box-sizing: border-box; }
|
|
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; background: #f5f5f5; color: #333; padding: 40px; }
|
|
.container { max-width: 960px; margin: 0 auto; background: white; border-radius: 12px; box-shadow: 0 2px 12px rgba(0,0,0,0.08); padding: 40px; }
|
|
h1 { font-size: 24px; margin: 24px 0 12px; }
|
|
h2 { font-size: 20px; margin: 20px 0 10px; color: #222; }
|
|
h3 { font-size: 16px; margin: 16px 0 8px; color: #444; }
|
|
p { line-height: 1.6; margin: 8px 0; }
|
|
table { border-collapse: collapse; width: 100%; margin: 12px 0; font-size: 14px; }
|
|
th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; }
|
|
th { background: #f0f0f0; font-weight: 600; }
|
|
code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; font-size: 13px; }
|
|
pre { background: #f8f8f8; border: 1px solid #ddd; border-radius: 6px; padding: 12px; overflow-x: auto; margin: 12px 0; }
|
|
pre code { background: none; padding: 0; }
|
|
a { color: #0066cc; }
|
|
.back { display: inline-block; margin-bottom: 20px; color: #666; }
|
|
.back:hover { color: #333; }
|
|
.topbar { display: flex; justify-content: space-between; align-items: center; margin-bottom: 20px; }
|
|
.logout-btn { font-size: 13px; color: #999; text-decoration: none; }
|
|
.logout-btn:hover { color: #cc0000; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="container">
|
|
<div class="topbar">
|
|
<a class="back" href="index.html">← Back to index</a>
|
|
<a class="logout-btn" href="#" onclick="fetch('/api/v1/auth/logout',{method:'POST'}).then(()=>window.location.reload());return false">Logout</a>
|
|
</div>
|
|
<!-- module: search -->
|
|
<!-- description: Vector search, BM25, smart search, universal search, visual search -->
|
|
<!-- depends: 01_auth -->
|
|
|
|
<h2>Search APIs</h2>
|
|
<h3><code>POST /api/v1/search/smart</code></h3>
|
|
<p><strong>Auth</strong>: Required
|
|
<strong>Scope</strong>: file-level</p>
|
|
<p>Semantic vector search using EmbeddingGemma-300m. Generates a query embedding via EmbeddingGemma (port 11436), then searches pgvector <code>story_parent</code> and <code>llm_parent</code> chunks by cosine similarity.</p>
|
|
<h4>Request Parameters</h4>
|
|
<table class="table">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Required</th>
|
|
<th>Default</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>file_uuid</code></td>
|
|
<td>string</td>
|
|
<td>Yes</td>
|
|
<td>—</td>
|
|
<td>File UUID to search within</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>query</code></td>
|
|
<td>string</td>
|
|
<td>Yes</td>
|
|
<td>—</td>
|
|
<td>Search text</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>limit</code></td>
|
|
<td>integer</td>
|
|
<td>No</td>
|
|
<td>5</td>
|
|
<td>Max results to return</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>page</code></td>
|
|
<td>integer</td>
|
|
<td>No</td>
|
|
<td>1</td>
|
|
<td>Page number</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>page_size</code></td>
|
|
<td>integer</td>
|
|
<td>No</td>
|
|
<td>5</td>
|
|
<td>Items per page</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<h4>Example</h4>
|
|
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/search/smart"</span><span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Authorization: Bearer </span><span class="nv">$JWT</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"file_uuid": "'</span><span class="s2">"</span><span class="nv">$FILE_UUID</span><span class="s2">"</span><span class="s1">'", "query": "Audrey Hepburn"}'</span>
|
|
</code></pre></div>
|
|
|
|
<h4>Response (200)</h4>
|
|
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"query"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Audrey Hepburn"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"results"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
|
<span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"parent_id"</span><span class="p">:</span><span class="w"> </span><span class="mi">1087822</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"scene_order"</span><span class="p">:</span><span class="w"> </span><span class="mi">1087822</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"start_frame"</span><span class="p">:</span><span class="w"> </span><span class="mi">104438</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"end_frame"</span><span class="p">:</span><span class="w"> </span><span class="mi">104538</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"fps"</span><span class="p">:</span><span class="w"> </span><span class="mf">24.0</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"start_time"</span><span class="p">:</span><span class="w"> </span><span class="mf">4351.6</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"end_time"</span><span class="p">:</span><span class="w"> </span><span class="mf">4355.76</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"summary"</span><span class="p">:</span><span class="w"> </span><span class="s2">"[4352s-4356s, 4s] Cast: Audrey Hepburn. Total: 2 lines, 10 words. Speakers: Audrey Hepburn (2 lines)"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"similarity"</span><span class="p">:</span><span class="w"> </span><span class="mf">0.67</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="w"> </span><span class="p">],</span>
|
|
<span class="w"> </span><span class="nt">"page"</span><span class="p">:</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"page_size"</span><span class="p">:</span><span class="w"> </span><span class="mi">5</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"strategy"</span><span class="p">:</span><span class="w"> </span><span class="s2">"semantic_vector_search"</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<hr />
|
|
<h3><code>POST /api/v1/search/universal</code></h3>
|
|
<p><strong>Auth</strong>: Required
|
|
<strong>Scope</strong>: file-level</p>
|
|
<p>Multi-type BM25 full-text search across chunks, frames, and persons. Uses PostgreSQL <code>tsvector</code>.</p>
|
|
<h4>Request Parameters</h4>
|
|
<table class="table">
|
|
<thead>
|
|
<tr>
|
|
<th>Field</th>
|
|
<th>Type</th>
|
|
<th>Required</th>
|
|
<th>Default</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><code>query</code></td>
|
|
<td>string</td>
|
|
<td>Yes</td>
|
|
<td>—</td>
|
|
<td>Search text</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>file_uuid</code></td>
|
|
<td>string</td>
|
|
<td>No</td>
|
|
<td>—</td>
|
|
<td>Restrict to specific file</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>types</code></td>
|
|
<td>string[]</td>
|
|
<td>No</td>
|
|
<td><code>["chunk","frame","person"]</code></td>
|
|
<td>Search types</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>limit</code></td>
|
|
<td>integer</td>
|
|
<td>No</td>
|
|
<td>10</td>
|
|
<td>Max results per type</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>page</code></td>
|
|
<td>integer</td>
|
|
<td>No</td>
|
|
<td>1</td>
|
|
<td>Page number</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>page_size</code></td>
|
|
<td>integer</td>
|
|
<td>No</td>
|
|
<td>20</td>
|
|
<td>Items per page</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<h4>Example</h4>
|
|
<div class="codehilite"><pre><span></span><code>curl<span class="w"> </span>-s<span class="w"> </span>-X<span class="w"> </span>POST<span class="w"> </span><span class="s2">"</span><span class="nv">$API</span><span class="s2">/api/v1/search/universal"</span><span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Content-Type: application/json"</span><span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>-H<span class="w"> </span><span class="s2">"Authorization: Bearer </span><span class="nv">$JWT</span><span class="s2">"</span><span class="w"> </span><span class="se">\</span>
|
|
<span class="w"> </span>-d<span class="w"> </span><span class="s1">'{"file_uuid": "'</span><span class="s2">"</span><span class="nv">$FILE_UUID</span><span class="s2">"</span><span class="s1">'", "query": "Cary Grant"}'</span>
|
|
</code></pre></div>
|
|
|
|
<h4>Response (200)</h4>
|
|
<div class="codehilite"><pre><span></span><code><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"results"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span>
|
|
<span class="w"> </span><span class="p">{</span>
|
|
<span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"chunk"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"chunk_id"</span><span class="p">:</span><span class="w"> </span><span class="s2">"bd80fec92b0b6963d177a2c55bf713e2_2"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"chunk_type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"story_child"</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"start_frame"</span><span class="p">:</span><span class="w"> </span><span class="mi">5103</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"end_frame"</span><span class="p">:</span><span class="w"> </span><span class="mi">5127</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"start_time"</span><span class="p">:</span><span class="w"> </span><span class="mf">212.64</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"end_time"</span><span class="p">:</span><span class="w"> </span><span class="mf">213.64</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"text"</span><span class="p">:</span><span class="w"> </span><span class="s2">"[213s-214s] Cary Grant: \"Olá!\""</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"score"</span><span class="p">:</span><span class="w"> </span><span class="mf">0.9</span>
|
|
<span class="w"> </span><span class="p">}</span>
|
|
<span class="w"> </span><span class="p">],</span>
|
|
<span class="w"> </span><span class="nt">"total"</span><span class="p">:</span><span class="w"> </span><span class="mi">20</span><span class="p">,</span>
|
|
<span class="w"> </span><span class="nt">"took_ms"</span><span class="p">:</span><span class="w"> </span><span class="mi">18</span>
|
|
<span class="p">}</span>
|
|
</code></pre></div>
|
|
|
|
<hr />
|
|
<h3><code>POST /api/v1/search/frames</code></h3>
|
|
<p><strong>Auth</strong>: Required
|
|
<strong>Scope</strong>: file-level</p>
|
|
<p>Search face detection frames by identity name or trace ID.</p>
|
|
<hr />
|
|
<h3><code>POST /api/v1/search/identity_text</code></h3>
|
|
<p><strong>Auth</strong>: Required
|
|
<strong>Scope</strong>: file-level</p>
|
|
<p>Search text chunks spoken by a specific identity.</p>
|
|
<hr />
|
|
<h3>Visual Search</h3>
|
|
<table class="table">
|
|
<thead>
|
|
<tr>
|
|
<th>Method</th>
|
|
<th>Endpoint</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>POST</td>
|
|
<td><code>/api/v1/search/visual</code></td>
|
|
<td>Search visual chunks</td>
|
|
</tr>
|
|
<tr>
|
|
<td>POST</td>
|
|
<td><code>/api/v1/search/visual/class</code></td>
|
|
<td>Search by object class</td>
|
|
</tr>
|
|
<tr>
|
|
<td>POST</td>
|
|
<td><code>/api/v1/search/visual/density</code></td>
|
|
<td>Search by object density</td>
|
|
</tr>
|
|
<tr>
|
|
<td>POST</td>
|
|
<td><code>/api/v1/search/visual/combination</code></td>
|
|
<td>Search by object combination</td>
|
|
</tr>
|
|
<tr>
|
|
<td>POST</td>
|
|
<td><code>/api/v1/search/visual/stats</code></td>
|
|
<td>Visual chunk statistics</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<h4>Embedding Model</h4>
|
|
<table class="table">
|
|
<thead>
|
|
<tr>
|
|
<th>Detail</th>
|
|
<th>Value</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><strong>Model</strong></td>
|
|
<td>EmbeddingGemma-300m</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>Endpoint</strong></td>
|
|
<td><code>POST /api/v1/embeddings</code> on port 11436</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>Dimension</strong></td>
|
|
<td>768</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>Storage</strong></td>
|
|
<td>pgvector (<code>chunk.embedding</code> column)</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<hr />
|
|
<p><em>Updated: 2026-05-19 12:49:24</em></p>
|
|
</div>
|
|
</body>
|
|
</html> |