외부 임베딩 제공자
외부 임베딩 제공자 (inference-external-inference-providers)
Qdrant Cloud는 외부 임베딩 모델 제공자의 API를 대신 호출해 주는 프록시 역할을 할 수 있어요. 즉, OpenAI, Cohere, Jina AI, OpenRouter 같은 제공자의 임베딩 모델을 Qdrant API를 통해서 그대로 사용할 수 있습니다. 외부 임베딩 서비스나 별도 파이프라인을 구축할 필요 없이 한 번의 API 호출로 데이터를 임베딩·저장·인덱싱하는 구조를 원한다면 요긴한 기능이에요.
출처: Qdrant 공식문서
Qdrant Cloud가 프록시로 지원하는 외부 임베딩 모델 제공자는 다음과 같습니다.
- OpenAI
- Cohere
- Jina AI
- OpenRouter
이를 통해 이 제공자들이 지원하는 어떤 임베딩 모델이든 Qdrant API로 접근할 수 있어요.
외부 임베딩 모델을 사용할 때는 컬렉션이 올바른 차원(dimensionality)의 벡터로 구성되어 있는지 확인하세요. 출력 차원에 대한 자세한 내용은 해당 모델의 문서를 참고하면 됩니다.
API 키
외부 제공자의 임베딩 모델을 사용하려면 그 제공자의 API 키가 필요해요. 예를 들어 OpenAI 모델에 접근하려면 OpenAI API 키가 필요합니다. Qdrant는 API 키를 저장하거나 캐시하지 않으므로, 매 추론 요청마다 키를 제공해야 해요.
제공자의 API 키는 요청 헤더(openai-api-key, cohere-api-key, jina-api-key, openrouter-api-key)에 넣어 전달합니다. 예를 들면:
from qdrant_client import QdrantClient , models from qdrant_client.context_headers import headers client = QdrantClient ( url = "https://xyz-example.qdrant.io:6333" , api_key = "<your-qdrant-api-key>" , cloud_inference = True ) with headers ({ "openai-api-key" : "<YOUR_OPENAI_API_KEY>" }): client . upsert ( collection_name = "{collection_name}" , points = [ models . PointStruct ( id = 1 , vector = models . Document ( text = "Recipe for baking chocolate chip cookies" , model = "openai/text-embedding-3-large" , ) ) ] )
또는 요청 본문의 options 객체에 API 키를 넣어 전달할 수도 있어요.
PUT /collections/{collection_name}/points?wait=true { "points": [ { "id": 1, "vector": { "text": "Recipe for baking chocolate chip cookies", "model": "openai/text-embedding-3-large", "options": { "openai-api-key": "<YOUR_OPENAI_API_KEY>" } } } ] }
OpenAI
모델 이름 앞에 openai/를 붙이면 임베딩 요청이 자동으로 OpenAI Embeddings API로 라우팅됩니다.
예를 들어 데이터 수집 시 OpenAI의 text-embedding-3-large 모델을 사용하려면 모델 이름 앞에 openai/를 붙이면 돼요. OpenAI API 키를 요청 헤더(openai-api-key)나 요청 본문의 options 객체에 넣어 제공합니다. 이 예시는 OpenAI 전용 API 파라미터 dimensions를 사용해 차원을 512로 줄인 모습이에요.
PUT /collections/{collection_name}/points?wait=true { "points": [ { "id": 1, "vector": { "text": "Recipe for baking chocolate chip cookies", "model": "openai/text-embedding-3-large", "options": { "openai-api-key": "<YOUR_OPENAI_API_KEY>", "dimensions": 512 } } } ] }
from qdrant_client import QdrantClient , models from qdrant_client.context_headers import headers client = QdrantClient ( url = "https://xyz-example.qdrant.io:6333" , api_key = "<your-qdrant-api-key>" , cloud_inference = True ) with headers ({ "openai-api-key" : "<YOUR_OPENAI_API_KEY>" }): client . upsert ( collection_name = "{collection_name}" , points = [ models . PointStruct ( id = 1 , vector = models . Document ( text = "Recipe for baking chocolate chip cookies" , model = "openai/text-embedding-3-large" , options = { "dimensions" : 512 } ) ) ] )
쿼리 시에도 같은 모델을 사용할 수 있어요. 모델 이름 앞에 openai/를 붙이고 options 객체에 OpenAI API 키를 제공하면 됩니다. 이 예시도 OpenAI 전용 dimensions 파라미터로 차원을 512로 줄입니다.
POST /collections/{collection_name}/points/query { "query": { "text": "How to bake cookies?", "model": "openai/text-embedding-3-large", "options": { "openai-api-key": "<YOUR_OPENAI_API_KEY>", "dimensions": 512 } } }
from qdrant_client import QdrantClient , models from qdrant_client.context_headers import headers client = QdrantClient ( url = "https://xyz-example.qdrant.io:6333" , api_key = "<your-qdrant-api-key>" , cloud_inference = True ) with headers ({ "openai-api-key" : "<YOUR_OPENAI_API_KEY>" }): client . query_points ( collection_name = "{collection_name}" , query = models . Document ( text = "How to bake cookies?" , model = "openai/text-embedding-3-large" , options = { "dimensions" : 512 } ) )
Qdrant는 OpenAI API 키를 저장하거나 캐시하지 않기 때문에, 매 추론 요청마다 키를 제공해야 한다는 점을 기억하세요.
Cohere
모델 이름 앞에 cohere/를 붙이면 임베딩 요청이 자동으로 Cohere Embed API로 라우팅됩니다.
예를 들어 데이터 수집 시 Cohere의 멀티모달 embed-v4.0 모델을 사용하려면 모델 이름 앞에 cohere/를 붙이세요. Cohere API 키는 요청 헤더(cohere-api-key)나 요청 본문의 options 객체에 넣습니다. 이 예시는 Cohere 전용 API 파라미터 output_dimension으로 차원을 512로 줄인 모습이에요.
PUT /collections/{collection_name}/points?wait=true { "points": [ { "id": 1, "vector": { "image": "", "model": "cohere/embed-v4.0", "options": { "cohere-api-key": "<YOUR_COHERE_API_KEY>", "output_dimension": 512 } } } ] }
from qdrant_client import QdrantClient , models from qdrant_client.context_headers import headers client = QdrantClient ( url = "https://xyz-example.qdrant.io:6333" , api_key = "<your-qdrant-api-key>" , cloud_inference = True ) with headers ({ "cohere-api-key" : "<YOUR_COHERE_API_KEY>" }): client . upsert ( collection_name = "{collection_name}" , points = [ models . PointStruct ( id = 1 , vector = models . Image ( image = "", model = "cohere/embed-v4.0" , options = { "output_dimension" : 512 } ) ) ] )
Cohere의 embed-v4.0 모델은 이미지를 URL로 전달하는 것을 지원하지 않아요. base64로 인코딩된 이미지를 Data URL로 제공해야 합니다.
쿼리 시에도 같은 모델을 쓸 수 있어요. 모델 이름 앞에 cohere/를 붙이고 options 객체에 Cohere API 키를 제공합니다. 이 예시도 output_dimension으로 차원을 512로 줄여요.
POST /collections/{collection_name}/points/query { "query": { "text": "a green square", "model": "cohere/embed-v4.0", "options": { "cohere-api-key": "<YOUR_COHERE_API_KEY>", "output_dimension": 512 } } }
from qdrant_client import QdrantClient , models from qdrant_client.context_headers import headers client = QdrantClient ( url = "https://xyz-example.qdrant.io:6333" , api_key = "<your-qdrant-api-key>" , cloud_inference = True ) with headers ({ "cohere-api-key" : "<YOUR_COHERE_API_KEY>" }): client . query_points ( collection_name = "{collection_name}" , query = models . Document ( text = "a green square" , model = "cohere/embed-v4.0" , options = { "output_dimension" : 512 } ) )
Qdrant는 Cohere API 키를 저장하거나 캐시하지 않으므로 매 추론 요청마다 키를 제공해야 해요.
Jina AI
모델 이름 앞에 jinaai/를 붙이면 임베딩 요청이 자동으로 Jina AI Embedding API로 라우팅됩니다.
예를 들어 데이터 수집 시 Jina AI의 멀티모달 jina-clip-v2 모델을 사용하려면 모델 이름 앞에 jinaai/를 붙이세요. Jina AI API 키는 요청 헤더(jina-api-key)나 요청 본문의 options 객체에 넣습니다. 이 예시는 Jina AI 전용 dimensions 파라미터로 차원을 512로 줄인 모습이에요.
PUT /collections/{collection_name}/points?wait=true { "points": [ { "id": 1, "vector": { "image": "https://qdrant.tech/example.png", "model": "jinaai/jina-clip-v2", "options": { "jina-api-key": "<YOUR_JINAAI_API_KEY>", "dimensions": 512 } } } ] }
from qdrant_client import QdrantClient , models from qdrant_client.context_headers import headers client = QdrantClient ( url = "https://xyz-example.qdrant.io:6333" , api_key = "<your-qdrant-api-key>" , cloud_inference = True ) with headers ({ "jina-api-key" : "<YOUR_JINAAI_API_KEY>" }): client . upsert ( collection_name = "{collection_name}" , points = [ models . PointStruct ( id = 1 , vector = models . Image ( image = "https://qdrant.tech/example.png" , model = "jinaai/jina-clip-v2" , options = { "dimensions" : 512 } ) ) ] )
쿼리 시에도 같은 모델을 쓸 수 있어요. 모델 이름 앞에 jinaai/를 붙이고 options 객체에 Jina AI API 키를 제공합니다. 이 예시도 dimensions로 차원을 512로 줄여요.
POST /collections/{collection_name}/points/query { "query": { "text": "Mission to Mars", "model": "jinaai/jina-clip-v2", "options": { "jina-api-key": "<YOUR_JINAAI_API_KEY>", "dimensions": 512 } } }
from qdrant_client import QdrantClient , models from qdrant_client.context_headers import headers client = QdrantClient ( url = "https://xyz-example.qdrant.io:6333" , api_key = "<your-qdrant-api-key>" , cloud_inference = True ) with headers ({ "jina-api-key" : "<YOUR_JINAAI_API_KEY>" }): client . query_points ( collection_name = "{collection_name}" , query = models . Document ( text = "Mission to Mars" , model = "jinaai/jina-clip-v2" , options = { "dimensions" : 512 } ) )
Qdrant는 Jina AI API 키를 저장하거나 캐시하지 않으므로 매 추론 요청마다 키를 제공해야 해요.
OpenRouter
OpenRouter는 여러 임베딩 모델을 제공하는 플랫폼이에요. OpenRouter Embeddings API가 제공하는 모델 중 하나를 쓰려면 모델 이름 앞에 openrouter/를 붙이면 됩니다.
예를 들어 데이터 수집 시 mistralai/mistral-embed-2312 모델을 사용하려면 모델 이름 앞에 openrouter/를 붙이세요. OpenRouter API 키는 요청 헤더(openrouter-api-key)나 요청 본문의 options 객체에 넣어 제공합니다.
PUT /collections/{collection_name}/points?wait=true { "points": [ { "id": 1, "vector": { "text": "Recipe for baking chocolate chip cookies", "model": "openrouter/mistralai/mistral-embed-2312", "options": { "openrouter-api-key": "<YOUR_OPENROUTER_API_KEY>" } } } ] }
from qdrant_client import QdrantClient , models from qdrant_client.context_headers import headers client = QdrantClient ( url = "https://xyz-example.qdrant.io:6333" , api_key = "<your-qdrant-api-key>" , cloud_inference = True ) with headers ({ "openrouter-api-key" : "<YOUR_OPENROUTER_API_KEY>" }): client . upsert ( collection_name = "{collection_name}" , points = [ models . PointStruct ( id = 1 , vector = models . Document ( text = "Recipe for baking chocolate chip cookies" , model = "openrouter/mistralai/mistral-embed-2312" , ) ) ] )
쿼리 시에도 같은 모델을 쓸 수 있어요. 모델 이름 앞에 openrouter/를 붙이고 options 객체에 OpenRouter API 키를 제공합니다.
POST /collections/{collection_name}/points/query { "query": { "text": "How to bake cookies?", "model": "openrouter/mistralai/mistral-embed-2312", "options": { "openrouter-api-key": "<YOUR_OPENROUTER_API_KEY>" } } }
from qdrant_client import QdrantClient , models from qdrant_client.context_headers import headers client = QdrantClient ( url = "https://xyz-example.qdrant.io:6333" , api_key = "<your-qdrant-api-key>" , cloud_inference = True ) with headers ({ "openrouter-api-key" : "<YOUR_OPENROUTER_API_KEY>" }): client . query_points ( collection_name = "{collection_name}" , query = models . Document ( text = "How to bake cookies?" , model = "openrouter/mistralai/mistral-embed-2312" , ) )
Qdrant는 OpenRouter API 키를 저장하거나 캐시하지 않으므로 매 추론 요청마다 키를 제공해야 합니다.