57 lines
2.3 KiB
Markdown
57 lines
2.3 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.
|
|
|
|
**Why is this package in my results?** Each result knows which search
|
|
strategy produced it. The controller exposes this as
|
|
`@search_sources` (a hash mapping package ids to `:exact`,
|
|
`:name_prefix`, `:name_contains`, `:semantic` or `:fulltext`). For
|
|
debugging you can render a small badge on every result card by adding
|
|
`show_sources=1` to the URL, e.g.
|
|
`https://screenshots.debian.net/packages?search=sqlite&show_sources=1`.
|
|
|
|
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
|
|
|