|
| 1 | +import functools |
| 2 | +import os |
| 3 | +from typing import List, Optional |
| 4 | + |
| 5 | +import openai |
| 6 | + |
| 7 | +import dspy |
| 8 | +from dsp.modules.cache_utils import CacheMemory, NotebookCacheMemory, cache_turn_on |
| 9 | +from dsp.utils import dotdict |
| 10 | + |
| 11 | +# Check for necessary libraries and suggest installation if not found. |
| 12 | +try: |
| 13 | + import clickhouse_connect |
| 14 | +except ImportError: |
| 15 | + raise ImportError( |
| 16 | + "The 'myscale' extra is required to use MyScaleRM. Install it with `pip install dspy-ai[myscale]`", |
| 17 | + ) |
| 18 | + |
| 19 | +# Verify the compatibility of the OpenAI library version installed. |
| 20 | +try: |
| 21 | + major, minor, _ = map(int, openai.__version__.split('.')) |
| 22 | + OPENAI_VERSION_COMPATIBLE = major >= 1 and minor >= 16 |
| 23 | +except Exception: |
| 24 | + OPENAI_VERSION_COMPATIBLE = False |
| 25 | + |
| 26 | +if not OPENAI_VERSION_COMPATIBLE: |
| 27 | + raise ImportError( |
| 28 | + "An incompatible OpenAI library version is installed. Ensure you have version 1.16.1 or later.", |
| 29 | + ) |
| 30 | + |
| 31 | +# Attempt to handle specific OpenAI errors; fallback to general ones if necessary. |
| 32 | +try: |
| 33 | + import openai.error |
| 34 | + ERRORS = (openai.error.RateLimitError, openai.error.ServiceUnavailableError, openai.error.APIError) |
| 35 | +except Exception: |
| 36 | + ERRORS = (openai.RateLimitError, openai.APIError) |
| 37 | + |
| 38 | + |
| 39 | +class MyScaleRM(dspy.Retrieve): |
| 40 | + """ |
| 41 | + A retrieval module that uses MyScaleDB to return the top passages for a given query. |
| 42 | +
|
| 43 | + MyScaleDB is a fork of ClickHouse that focuses on vector similarity search and full |
| 44 | + text search. MyScaleRM is designed to facilitate easy retrieval of information from |
| 45 | + MyScaleDB using embeddings. It supports embedding generation through either a local |
| 46 | + model or the OpenAI API. This class abstracts away the complexities of connecting to |
| 47 | + MyScaleDB, managing API keys, and processing queries to return semantically |
| 48 | + relevant results. |
| 49 | +
|
| 50 | + Assumes that a table named `database.table` exists in MyScaleDB, and that the |
| 51 | + table has column named `vector_column` that stores vector data and a vector index has |
| 52 | + been created on this column. Other metadata are stored in `metadata_columns`. |
| 53 | +
|
| 54 | + Args: |
| 55 | + client (clickhouse_connect.driver.client.Client): A client connection to the MyScaleDB. |
| 56 | + table (str): Name of the table within the database to perform queries against. |
| 57 | + database (str, optional): Name of the database to query within MyScaleDB. |
| 58 | + metadata_columns(List[str], optional): A list of columns to include in the results. |
| 59 | + vector_column (str, optional): The name of the column in the table that stores vector data. |
| 60 | + k (int, optional): The number of closest matches to retrieve for a given query. |
| 61 | + openai_api_key (str, optional): The API key for accessing OpenAI's services. |
| 62 | + model (str, optional): Specifies the particular OpenAI model to use for embedding generation. |
| 63 | + use_local_model (bool): Flag indicating whether a local model is used for embeddings. |
| 64 | +
|
| 65 | + """ |
| 66 | + |
| 67 | + def __init__(self, |
| 68 | + client: clickhouse_connect.driver.client.Client, |
| 69 | + table: str, |
| 70 | + database: str = "default", |
| 71 | + metadata_columns: List[str] = ["text"], |
| 72 | + vector_column: str = "vector", |
| 73 | + k: int = 3, |
| 74 | + openai_api_key: Optional[str] = None, |
| 75 | + openai_model: Optional[str] = None, |
| 76 | + local_embed_model: Optional[str] = None): |
| 77 | + self.client = client |
| 78 | + self.database = database |
| 79 | + self.table = table |
| 80 | + if not metadata_columns: |
| 81 | + raise ValueError("metadata_columns is required") |
| 82 | + self.metadata_columns = metadata_columns |
| 83 | + self.vector_column = vector_column |
| 84 | + self.k = k |
| 85 | + self.openai_api_key = openai_api_key |
| 86 | + self.model = openai_model |
| 87 | + self.use_local_model = False |
| 88 | + |
| 89 | + if local_embed_model: |
| 90 | + self.setup_local_model(local_embed_model) |
| 91 | + elif openai_api_key: |
| 92 | + os.environ['OPENAI_API_KEY'] = self.openai_api_key |
| 93 | + |
| 94 | + def setup_local_model(self, model_name: str): |
| 95 | + """ |
| 96 | + Configures a local model for embedding generation, including model and tokenizer loading. |
| 97 | +
|
| 98 | + Args: |
| 99 | + model_name: The name or path to the pre-trained model to load. |
| 100 | +
|
| 101 | + Raises: |
| 102 | + ModuleNotFoundError: If necessary libraries (torch or transformers) are not installed. |
| 103 | + """ |
| 104 | + try: |
| 105 | + import torch |
| 106 | + from transformers import AutoModel, AutoTokenizer |
| 107 | + except ImportError as exc: |
| 108 | + raise ModuleNotFoundError( |
| 109 | + """You need to install PyTorch and Hugging Face's transformers library to use a local embedding model. |
| 110 | + Install the pytorch using `pip install torch` and transformers using `pip install transformers` """, |
| 111 | + ) from exc |
| 112 | + |
| 113 | + try: |
| 114 | + self._local_embed_model = AutoModel.from_pretrained(model_name) |
| 115 | + self._local_tokenizer = AutoTokenizer.from_pretrained(model_name) |
| 116 | + self.use_local_model = True |
| 117 | + except Exception as e: |
| 118 | + raise ValueError(f"Failed to load model or tokenizer. Error: {str(e)}") |
| 119 | + |
| 120 | + if torch.cuda.is_available(): |
| 121 | + self.device = torch.device('cuda:0') |
| 122 | + elif torch.backends.mps.is_available(): |
| 123 | + self.device = torch.device('mps') |
| 124 | + else: |
| 125 | + self.device = torch.device('cpu') |
| 126 | + |
| 127 | + self._local_embed_model.to(self.device) |
| 128 | + |
| 129 | + @functools.lru_cache(maxsize=None if cache_turn_on else 0) |
| 130 | + @NotebookCacheMemory.cache |
| 131 | + def get_embeddings(self, queries: List[str]) -> List[List[float]]: |
| 132 | + """ |
| 133 | + Determines the appropriate source (OpenAI or local model) for embedding generation based on class configuration, |
| 134 | + and retrieves embeddings for the provided queries. |
| 135 | +
|
| 136 | + Args: |
| 137 | + queries: A list of text queries to generate embeddings for. |
| 138 | +
|
| 139 | + Returns: |
| 140 | + A list of embeddings, each corresponding to a query in the input list. |
| 141 | +
|
| 142 | + Raises: |
| 143 | + ValueError: If neither an OpenAI API key nor a local model has been configured. |
| 144 | + """ |
| 145 | + if self.openai_api_key and self.model: |
| 146 | + return self._get_embeddings_from_openai(queries) |
| 147 | + elif self.use_local_model: |
| 148 | + return self._get_embedding_from_local_model(queries) |
| 149 | + else: |
| 150 | + raise ValueError("No valid method for obtaining embeddings is configured.") |
| 151 | + |
| 152 | + #TO DO Add this method as Util method outside MyScaleRM |
| 153 | + @CacheMemory.cache |
| 154 | + def _get_embeddings_from_openai(self, queries: List[str]) -> List[List[float]]: |
| 155 | + """ |
| 156 | + Uses the OpenAI API to generate embeddings for a list of queries. |
| 157 | +
|
| 158 | + Args: |
| 159 | + queries: A list of strings for which to generate embeddings. |
| 160 | +
|
| 161 | + Returns: |
| 162 | + A list of lists, where each inner list contains the embedding of a query. |
| 163 | + """ |
| 164 | + |
| 165 | + response = openai.embeddings.create( |
| 166 | + model=self.model, |
| 167 | + input=queries) |
| 168 | + return response.data[0].embedding |
| 169 | + |
| 170 | + #TO DO Add this method as Util method outside MyScaleRM |
| 171 | + @CacheMemory.cache |
| 172 | + def _get_embedding_from_local_model(self, query: str) -> List[float]: |
| 173 | + """ |
| 174 | + Generates embeddings for a single query using the configured local model. |
| 175 | +
|
| 176 | + Args: |
| 177 | + query: The text query to generate an embedding for. |
| 178 | +
|
| 179 | + Returns: |
| 180 | + A list of floats representing the query's embedding. |
| 181 | + """ |
| 182 | + import torch |
| 183 | + self._local_embed_model.eval() # Ensure the model is in evaluation mode |
| 184 | + |
| 185 | + inputs = self._local_tokenizer(query, return_tensors="pt", padding=True, truncation=True).to(self.device) |
| 186 | + with torch.no_grad(): |
| 187 | + output = self._local_embed_model(**inputs) |
| 188 | + embedding = output.last_hidden_state.mean(dim=1).cpu().numpy().tolist()[0] |
| 189 | + |
| 190 | + return embedding |
| 191 | + |
| 192 | + def forward(self, user_query: str, k: Optional[int] = None) -> dspy.Prediction: |
| 193 | + """ |
| 194 | + Executes a retrieval operation based on a user's query and returns the top k relevant results. |
| 195 | +
|
| 196 | + Args: |
| 197 | + user_query: The query text to search for. |
| 198 | + k: Optional; The number of top matches to return. Defaults to the class's configured k value. |
| 199 | +
|
| 200 | + Returns: |
| 201 | + A dspy.Prediction object containing the formatted retrieval results. |
| 202 | +
|
| 203 | + Raises: |
| 204 | + ValueError: If the user_query is None. |
| 205 | + """ |
| 206 | + if user_query is None: |
| 207 | + raise ValueError("Query is required") |
| 208 | + k = k if k is not None else self.k |
| 209 | + embeddings = self.get_embeddings([user_query]) |
| 210 | + columns_string = ', '.join(self.metadata_columns) |
| 211 | + result = self.client.query(f""" |
| 212 | + SELECT {columns_string}, |
| 213 | + distance({self.vector_column}, {embeddings}) as dist FROM {self.database}.{self.table} ORDER BY dist LIMIT {k} |
| 214 | + """) |
| 215 | + |
| 216 | + # We convert the metadata into strings to pass to dspy.Prediction |
| 217 | + results = [] |
| 218 | + for row in result.named_results(): |
| 219 | + if len(self.metadata_columns) == 1: |
| 220 | + results.append(row[self.metadata_columns[0]]) |
| 221 | + else: |
| 222 | + row_strings = [f"{column}: {row[column]}" for column in self.metadata_columns] # Format row data |
| 223 | + row_string = "\n".join(row_strings) # Combine formatted data |
| 224 | + results.append(row_string) # Append to results |
| 225 | + |
| 226 | + return dspy.Prediction(passages=[dotdict({"long_text": passage}) for passage in results]) # Return results as Prediction |
0 commit comments