mirror of
https://github.com/sourcegraph/sourcegraph.git
synced 2026-02-06 18:51:59 +00:00
f77f0272cf
# High-level architecture overview <img width="2231" alt="Screenshot 2023-02-24 at 15 13 59" src="https://user-images.githubusercontent.com/6417322/221200130-53c1ff25-4c47-4532-885f-5c4f9dadb05e.png"> # Embeddings Really quickly: embeddings are a semantic representation of text. Embeddings are usually floating-point vectors with 256+ elements. The neat thing about embeddings is that they allow us to search over textual information using a semantic correlation between the query and the text, not just syntactic (matching keywords). In this PR, we implemented an embedding service that will allow us to do semantic code search over repositories in Sourcegraph. So, for example, you'll be able to ask, "how do access tokens work in Sourcegraph", and it will give you a list of the closest matching code files. Additionally, we build a context detection service powered by embeddings. In chat applications, it is important to know whether the user's message requires additional context. We have to differentiate between two cases: the user asks a general question about the codebase, or the user references something in the existing conversation. In the latter case, including the context would ruin the flow of the conversation, and the chatbot would most likely return a confusing answer. We determine whether a query _does not_ require additional context using two approaches: 1. We check if the query contains well-known phrases that would indicate the user is referencing the existing conversation (e.g., translate previous, change that) 1. We have a static dataset of messages that require context and a dataset of messages that do not. We embed both datasets, and then, using embedding similarity, we can check which set is more similar to the query. ## GraphQL API We add four new resolvers to the GraphQL API: ```graphql extend type Query { embeddingsSearch(repo: ID!, query: String!, codeResultsCount: Int!, textResultsCount: Int!): EmbeddingsSearchResults! isContextRequiredForQuery(query: String!): Boolean! } extend type Mutation { scheduleRepositoriesForEmbedding(repoNames: [String!]!): EmptyResponse! scheduleContextDetectionForEmbedding: EmptyResponse! } ``` - `embeddingsSearch` performs embeddings search over the repo embeddings and returns the specified number of results - `isContextRequiredForQuery` determines whether the given query requires additional context - `scheduleRepositoriesForEmbedding` schedules a repo embedding background job - `scheduleContextDetectionForEmbedding` schedules a context detection embedding background job that embeds a static dataset of messages. ## Repo embedding background job Embedding a repository is implemented as a background job. The background job handler receives the repository and the revision, which should be embedded. Handler then gathers a list of files from the gitserver and excludes files >1MB in size. The list of files is split into code and text files (.md, .txt), and we build a separate embedding index for both. We split them because in a combined index, the text files always tended to feature as top results and didn't leave any room for code files. Once we have the list of files, the procedure is as follows: - For each file - Get file contents from gitserver - Check if the file is embeddable (is not autogenerated, is large enough, does not have long lines) - Split the file into embeddable chunks - Embed the file chunks using an external embedding service (defined in site config) - Add embedded file chunks and metadata to the index - Metadata contains the file name, the start line, and the end line of the chunk - Once all files are processed, the index is marshaled into JSON and stored in Cloud storage (GCS, S3) ### Site config changes As mentioned, we use a configurable external embedding API that does the actual text -> vector embedding part. Ideally, this allows us to swap embedding providers in the future. ```json "embeddings": { "description": "Configuration for embeddings service.", "type": "object", "required": ["enabled", "dimensions", "model", "accessToken", "url"], "properties": { "enabled": { "description": "Toggles whether embedding service is enabled.", "type": "boolean", "default": false }, "dimensions": { "description": "The dimensionality of the embedding vectors.", "type": "integer", "minimum": 0 }, "model": { "description": "The model used for embedding.", "type": "string" }, "accessToken": { "description": "The access token used to authenticate with the external embedding API service.", "type": "string" }, "url": { "description": "The url to the external embedding API service.", "type": "string", "format": "uri" } } } ``` ## Repo embeddings search The repo embeddings search is implemented in its own service. When a user queries a repo using embeddings search, the following happens: - Download the repo embedding index from blob storage and cache it in memory - We cache up to 5 embedding indexes in memory - Embed the query and use the embedded query vector to find similar code and text file metadata in the embedding index - Query gitserver for the actual file contents - Return the results ## Interesting files - [Similarity search](https://github.com/sourcegraph/sourcegraph/pull/48017/files#diff-102cc83520004eb0e2795e49bc435c5142ca555189b1db3a52bbf1ffb82fa3c6) - [Repo embedding job handler](https://github.com/sourcegraph/sourcegraph/pull/48017/files#diff-c345f373f426398beb4b9cd5852ba862a2718687882db2a8b2d9c7fbb5f1dc52) - [External embedding api client](https://github.com/sourcegraph/sourcegraph/pull/48017/files#diff-ad1e7956f518e4bcaee17dd9e7ac04a5e090c00d970fcd273919e887e1d2cf8f) - [Embedding a repo](https://github.com/sourcegraph/sourcegraph/pull/48017/files#diff-1f35118727128095b7816791b6f0a2e0e060cddee43d25102859b8159465585c) - [Embeddings searcher service](https://github.com/sourcegraph/sourcegraph/pull/48017/files#diff-5b20f3e7ef87041daeeaef98b58ebf7388519cedcdfc359dc5e6d4e0b021472e) - [Embeddings search](https://github.com/sourcegraph/sourcegraph/pull/48017/files#diff-79f95b9cc3f1ef39c1a0b88015bd9cd6c19c30a8d4c147409f1b8e8cd9462ea1) - [Repo embedding index cache management](https://github.com/sourcegraph/sourcegraph/pull/48017/files#diff-8a41f7dec31054889dbf86e97c52223d5636b4d408c6b375bcfc09160a8b70f8) - [GraphQL resolvers](https://github.com/sourcegraph/sourcegraph/pull/48017/files#diff-9b30a0b5efcb63e2f4611b99ab137fbe09629a769a4f30d10a1b2da41a01d21f) ## Test plan - Start by filling out the `embeddings` object in the site config (let me know if you need an API key) - Start the embeddings service using `sg start embeddings` - Go to the `/api/console` page and schedule a repo embedding job and a context detection embedding job: ```graphql mutation { scheduleRepositoriesForEmbedding(repoNames: ["github.com/sourcegraph/handbook"]) { __typename } scheduleContextDetectionForEmbedding { __typename } } ``` - Once both are finished, you should be able to query the repo embedding index, and determine whether context is need for a given query: ```graphql query { isContextRequiredForQuery(query: "how do access tokens work") embeddingsSearch( repo: "UmVwb3NpdG9yeToy", # github.com/sourcegraph/handbook GQL ID query: "how do access tokens work", codeResultsCount: 5, textResultsCount: 5) { codeResults { fileName content } textResults { fileName content } } } ``` |
||
|---|---|---|
| .. | ||
| basestore | ||
| batch | ||
| connections | ||
| dbcache | ||
| dbconn | ||
| dbtest | ||
| dbutil | ||
| fakedb | ||
| locker | ||
| migration | ||
| postgresdsn | ||
| access_requests_test.go | ||
| access_requests.go | ||
| access_tokens_test.go | ||
| access_tokens.go | ||
| authenticator_test.go | ||
| authenticator.go | ||
| authz.go | ||
| bitbucket_project_permissions_test.go | ||
| bitbucket_project_permissions.go | ||
| BUILD.bazel | ||
| CODENOTIFY | ||
| conf_test.go | ||
| conf.go | ||
| database_test.go | ||
| database.go | ||
| dbstore_db_test.go | ||
| doc.go | ||
| encryption_tables.go | ||
| encryption_test.go | ||
| encryption_utils.go | ||
| encryption.go | ||
| err_test.go | ||
| event_logs_test.go | ||
| event_logs.go | ||
| executor_secret_access_logs_test.go | ||
| executor_secret_access_logs.go | ||
| executor_secrets_test.go | ||
| executor_secrets.go | ||
| executors_test.go | ||
| executors.go | ||
| external_accounts_test.go | ||
| external_accounts.go | ||
| external_services_test.go | ||
| external_services.go | ||
| feature_flags_test.go | ||
| feature_flags.go | ||
| gen.go | ||
| gen.sh | ||
| github_app_helper.go | ||
| gitserver_localclone_jobs_test.go | ||
| gitserver_localclone_jobs.go | ||
| gitserver_repos_test.go | ||
| gitserver_repos.go | ||
| global_state_test.go | ||
| global_state.go | ||
| helpers.go | ||
| main_test.go | ||
| mockerr.go | ||
| mocks_temp.go | ||
| namespace_permissions_test.go | ||
| namespace_permissions.go | ||
| namespaces_test.go | ||
| namespaces.go | ||
| oauth_token_helper_test.go | ||
| oauth_token_helper.go | ||
| org_invitations_test.go | ||
| org_invitations.go | ||
| org_members_db_test.go | ||
| org_members.go | ||
| orgs_test.go | ||
| orgs.go | ||
| outbound_webhook_jobs_test.go | ||
| outbound_webhook_jobs.go | ||
| outbound_webhook_logs_test.go | ||
| outbound_webhook_logs.go | ||
| outbound_webhooks_test.go | ||
| outbound_webhooks.go | ||
| permission_sync_code_host_state.go | ||
| permission_sync_jobs_test.go | ||
| permission_sync_jobs.go | ||
| permissions_test.go | ||
| permissions.go | ||
| phabricator_test.go | ||
| phabricator.go | ||
| redis_key_value_test.go | ||
| redis_key_value.go | ||
| repo_kvps_test.go | ||
| repo_kvps.go | ||
| repo_statistics_test.go | ||
| repo_statistics.go | ||
| repos_perm_test.go | ||
| repos_perm.go | ||
| repos_test.go | ||
| repos.go | ||
| role_permissions_test.go | ||
| role_permissions.go | ||
| roles_test.go | ||
| roles.go | ||
| saved_searches_test.go | ||
| saved_searches.go | ||
| schema.codeinsights.json | ||
| schema.codeinsights.md | ||
| schema.codeintel.json | ||
| schema.codeintel.md | ||
| schema.json | ||
| schema.md | ||
| search_contexts_test.go | ||
| search_contexts.go | ||
| security_event_logs_test.go | ||
| security_event_logs.go | ||
| settings_test.go | ||
| settings.go | ||
| survey_responses_test.go | ||
| survey_responses.go | ||
| teams_test.go | ||
| teams.go | ||
| temporary_settings_test.go | ||
| temporary_settings.go | ||
| test_util.go | ||
| testing.go | ||
| user_credentials_test.go | ||
| user_credentials.go | ||
| user_emails_test.go | ||
| user_emails.go | ||
| user_roles_test.go | ||
| user_roles.go | ||
| users_builtin_auth_test.go | ||
| users_test.go | ||
| users.go | ||
| webhook_logs_test.go | ||
| webhook_logs.go | ||
| webhooks_test.go | ||
| webhooks.go | ||
| zoekt_repos_test.go | ||
| zoekt_repos.go | ||
