Wyszukiwanie Semantyczne z vLLM (/sens)

[dam2452]

Zadanie polega na wdrożeniu wyszukiwania semantycznego (semantic search) w oparciu o wektory (embeddingi) generowane przez zewnętrzny serwis vLLM. Nowa funkcjonalność pozwoli użytkownikom wyszukiwać klipy na podstawie znaczenia tekstu i opisu sceny, a nie tylko dokładnego dopasowania słów kluczowych.

Specyfikacja Funkcjonalna

Komenda /sens

Aliasy: /meaning, /sen

Działanie:

1. Użytkownik wpisuje frazę, np. /sens "rozmowa o polityce przy jedzeniu".
2. Bot przesyła treść zapytania do lokalnej instancji vLLM (działającej na CPU z modelem Qwen3-VL-Embedding-8B-GGUF).
3. vLLM zwraca wektor (embedding) reprezentujący znaczenie wpisanego tekstu.
4. Bot wykonuje zapytanie wektorowe (k-NN lub Cosine Similarity) do Elasticsearch, porównując otrzymany wektor z wektorami scen zapisanymi w indeksie.
5. Zwracane są najbardziej pasujące semantycznie wyniki (format wyświetlania analogiczny do /sz).

Wymagania Techniczne

1. Integracja z vLLM (API)

• Należy dodać klienta API kompatybilnego z OpenAI (vLLM wystawia endpoint /v1/embeddings).
• Konfiguracja bota musi zawierać adres URL serwisu vLLM (np. http://192.168.1.X:8000/v1).
• Model do użycia w zapytaniu: dam2452/Qwen3-VL-Embedding-8B-GGUF.

2. Zapytanie Elasticsearch

• Wykorzystanie script_score z funkcją cosineSimilarity lub natywnego wyszukiwania k-NN w Elasticu.
• Należy upewnić się, że wymiarowość wektora zapytania zgadza się z wymiarowością pola wektorowego w indeksie (dla Qwen zazwyczaj 3584 lub 1536 - do weryfikacji w modelu).

Kryteria Akceptacji

1. Wpisanie /sens [opis] zwraca wyniki powiązane tematycznie, nawet jeśli nie zawierają dokładnie tych samych słów.
2. Bot poprawnie komunikuje się z instancją vLLM i obsługuje ewentualne timeouty (generowanie na CPU może chwilę trwać).
3. Wyniki są posortowane od najwyższego do najniższego stopnia dopasowania semantycznego.

---

🚀 Instrukcja uruchomienia vLLM (Docker CPU + GGUF)

Aby odpalić ten konkretny model (GGUF) na CPU przy użyciu vLLM, wykonaj poniższe kroki.

Wymagania:

• Pobrany plik modelu: Qwen3-VL-Embedding-8B-Q4_K_M.gguf (lub inny kwant).
• Zainstalowany Docker.

1. Struktura katalogów

Załóżmy, że masz model w katalogu /home/user/models/:

/home/user/models/
└── Qwen3-VL-Embedding-8B-Q4_K_M.gguf

2. Komenda Docker

Użyjemy oficjalnego obrazu vllm/vllm-openai:latest (lub wersji cpu-specific, jeśli dostępna, ale standardowy obraz vLLM często wykrywa brak GPU i robi fallback, jednak dla pewności lepiej użyć dedykowanych flag lub builda).

Zalecana komenda dla środowiska CPU (może wymagać obrazu vllm/vllm-cpu-env lub instalacji pip install vllm --extra-index-url https://download.pytorch.org/whl/cpu wewnątrz kontenera, ale spróbujmy standardowego podejścia dla GGUF):

docker run -d \
  --name vllm-cpu-embedding \
  --network host \
  -v /home/user/models:/models \
  -e VLLM_TARGET_DEVICE=cpu \
  vllm/vllm-openai:latest \
  --model /models/Qwen3-VL-Embedding-8B-Q4_K_M.gguf \
  --tokenizer Qwen/Qwen2.5-VL-7B-Instruct \
  --quantization gguf \
  --dtype float32 \
  --device cpu \
  --served-model-name qwen-embedding \
  --max-model-len 8192

Kluczowe parametry:

• --tokenizer: Modele GGUF w vLLM często potrzebują wskazania oryginalnego tokenizera z HuggingFace (tutaj podałem Qwen/Qwen2.5-VL-7B-Instruct jako bazę, bo Qwen3-VL to świeża sprawa, jeśli to nie zadziała, spróbuj pominąć ten parametr - vLLM spróbuje wyciągnąć go z pliku GGUF).
• --dtype float32: Na CPU float16 bywa problematyczne (brak wsparcia AVX dla fp16), float32 jest bezpieczniejsze.
• --quantization gguf: Wymusza loader GGUF.

Testowanie

Gdy kontener wstanie, sprawdź czy działa (to jest endpoint, który bot będzie odpytywał):

curl http://localhost:8000/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-embedding",
    "input": "To jest testowe zdanie o sensie życia."
  }'

Daj znać jak pójdzie z tym Dockerem – jeśli vllm będzie marudził na architekturę Qwen3 (bo to nowość), alternatywą która na 100% łyknie GGUF na CPU jest llama.cpp w trybie server (embedding), ale trzymajmy się Twojego wymogu vLLM.