Christoph Haas
4d07f43a2e
Package pages get a "Related packages" section: a nearest neighbor query against the package's own stored embedding (no external service call), excluding the package itself. Packages without an embedding render no section.
49 lines
1.9 KiB
Markdown
49 lines
1.9 KiB
Markdown
# About debshots
|
|
|
|
Debshots is a web application written in Ruby-on-Rails that powers the
|
|
screenshots.debian.net web site. Many services like packages.debian.net,
|
|
Ubuntu Software or Synaptic rely on it.
|
|
|
|
## State of the application
|
|
|
|
The code you find here resembles the version that is deployed to
|
|
screenshots.debian.net. It has been refactored in 06/2024 to Rails 7.
|
|
If you find strange or changed behavior please open an issue at
|
|
https://salsa.debian.org/debian/debshots/-/issues
|
|
|
|
## Development
|
|
|
|
Check out the doc/README.Development.md
|
|
|
|
## Package search
|
|
|
|
The package search combines several strategies, tried in this order:
|
|
|
|
1. **Exact package name**: Searching for `vim` shows exactly this
|
|
package without calling any external service.
|
|
2. **Name prefix matches**: Packages whose name starts with the query
|
|
rank first, e.g. searching for `sqlite` promotes `sqlite3`,
|
|
`sqlitebrowser` and friends above all other results.
|
|
3. **Compound word splitting**: Packages whose name contains *all*
|
|
query tokens match too, so `sqlite browser` finds `sqlitebrowser`.
|
|
4. **Semantic search**: The query is embedded via the vector service
|
|
(all-MiniLM-L6-v2, 384 dimensions) and the nearest neighbors among
|
|
the package description embeddings are returned, using the pgvector
|
|
extension with an HNSW cosine index. Embeddings are computed from
|
|
the package description and long description and can be (re-)built
|
|
with `bin/rails debshots:compute_vectors`.
|
|
5. **Full-text fallback**: If the vector service cannot be reached,
|
|
classic PostgreSQL full-text search takes over.
|
|
|
|
Queries that share no vocabulary with the package data (gibberish,
|
|
keyboard mash) return an honest empty result instead of random
|
|
semantic matches.
|
|
|
|
Package pages also show semantically **related packages**, computed as
|
|
a nearest neighbor query against the package's own description
|
|
embedding - no external service call involved.
|
|
|
|
## Deployment
|
|
|
|
Read the doc/README.Installation.md
|
|
|